Integration

Postcoder is quick and easy to add to most websites and applications.

Start with our example code for address lookup, email and mobile validation, or try an example below.

Community submitted examples

If you have built a wrapper, library or integration for Postcoder, we'd love to hear about it.

iOS example

iOS example including UI and Swift code created and maintained by Stephen Keable

NodeJS examples

Straightforward NodeJS wrappers for our API endpoints created and maintained by Stephen Keable

Code snippets

These snippets demonstrate an address lookup using the address method.

<?php
  /*
  Postcoder PHP example
	Allies Computing Ltd

	Demonstrates UK Address lookup rest web service

	Product URL: https://postcoder.com
	Technical Specs: https://postcoder.com/docs/address-lookup
	Example output: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/UK/NR147PZ

	This demo shows how to perform an address lookup and parse the results into php objects.

	Out of the box it uses a restricted API Key that limits the search to the postcode NR14 7PZ

	To experiment with different search terms, signup for a free evaluation API/Search key at:
	https://postcoder.com/sign-up

	Alternatively the code below can be pasted into an online interpreter such as
	http://www.compileonline.com/execute_php_online.php

    Note: This script has been developed for php version >= 5.2.0
    cURL and json_decode/json_encode functions are used.
  */

  // API/search key - MUST be supplied to unlock search,
  // if this is blank a restricted key is used which limits search to NR147PZ
  $searchKey = '';    // replace with your search key
  $searchterm  = 'NR147PZ';         // string to use for an address search

  echo 'Postcoder PHP Client Snippet

'; if(empty($searchKey)) { $searchKey = 'PCW45-12345-12345-1234X'; $searchterm = "NR14 7PZ"; echo 'No search-key: using restricted evaluation key - resets search term to NR14 7PZ
' . 'To obtain a free evaluation key, signup via' . 'https://postcoder.com/sign-up
' . '
'; } // build the URL, using the 'address' search method: $URL = 'https://ws.postcoder.com/pcw/' . $searchKey .'/address/UK/' . rawurlencode($searchterm) ; // for other uri options see https://postcoder.com/docs/address-lookup // use cURL to send the request and get the response $session = curl_init($URL); // Tell cURL to return the request data curl_setopt($session, CURLOPT_RETURNTRANSFER, true); // use application/json to specify json return values, the default is XML. $headers = array('Content-Type: application/json'); curl_setopt($session, CURLOPT_HTTPHEADER, $headers); // Execute cURL on the session handle $response = curl_exec($session); // Close the cURL session curl_close($session); // decode the response $addresses = json_decode($response); // trivial output echo 'Results for: ' . $searchterm . '

'; if (count($addresses) > 0){ foreach ($addresses as $address){ echo $address->summaryline,"
"; } } else{ echo 'No results, please try again.'; } ?>
// Postcoder C# example
// Allies Computing Ltd
//
// Demonstrates UK Address lookup rest web service
//
// Product URL: https://postcoder.com/address-lookup
// Technical Specs: https://postcoder.com/docs/address-lookup
// Example output: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/UK/NR147PZ
//
// This demo shows how to perform an address lookup and parse the results into C# objects.
//
// Out of the box it uses a restricted API Key that limits the search to the postcode NR14 7PZ
//
// To experiment with different search terms, signup for a free evaluation API/Search key at:
// https://postcoder.com/sign-up
//
//  To explore different searches, signup for an API/Search Key and assign to searchKey variable
//
// Alternatively the code below can be pasted into an online c# compiler such as
// http://www.compileonline.com/compile_csharp_online.php
//
using System;
using System.Collections.Generic;
using System.Net;
using System.Text;
using System.Xml.Serialization;

public class PCWV3Client
{

    // address class
    [Serializable]
    public class Address
    {
        public string summaryline { get; set; }
        public string organisation { get; set; }
        public string premise { get; set; }
        public string dependentstreet { get; set; }
        public string street { get; set; }
        public string doubledependentlocality { get; set; }
        public string dependentlocality { get; set; }
        public string posttown { get; set; }
        public string county { get; set; }
        public string postcode { get; set; }

        public override string ToString() { return summaryline; }
    }

    // root element of service output
    // essentially an array of addresses
    [XmlRoot("Addresses")]
    public class Addresses
    {

        [XmlElement("Address")]
        public List<Address> Address { get; set; }
    }

    // code entry point
    public static void Main(string[] args)
    {
        // API/search key - MUST be supplied to unlock search,
        // if this is blank a restricted key is used which limits search to NR147PZ
        string searchKey = "";
        // processing type - for other options see https://postcoder.com/docs
        string method = "address";
        // search string - MUST be supplied, if blank defaults to NR147PZ
        string searchTerm = "NR14 7PZ";

		Console.WriteLine("PostCoder Web V3 C# Client Snippet" + Environment.NewLine);
        try
        {
            if (String.IsNullOrEmpty(searchKey))
            {
                // no search key supplied - use the restricted evaluation key
                searchKey = "PCW45-12345-12345-1234X";
                searchTerm = "NR14 7PZ";
                Console.WriteLine(
                    "No search-key: using restricted evaluation key - resets search term to NR14 7PZ" + Environment.NewLine
                    + "To obtain a free evaluation key, signup via "
                    + "https://postcoder.com/sign-up" + Environment.NewLine);
            }

            // format the url
            string uri = String.Format("http://ws.postcoder.com/pcw/{0}/{1}/UK/{2}",
                                            searchKey,
                                            method,
                                            System.Uri.EscapeDataString(searchTerm)
                                            );
            // for other uri options see https://postcoder.com/docs/address-lookup

            // call the service
            var request = (HttpWebRequest)WebRequest.Create(uri);
            request.Method = "GET";
            request.Accept = "application/xml"; // xml or json permitted

            using (var response = (HttpWebResponse)request.GetResponse())
            {
                // check for call failure
                if (response.StatusCode != HttpStatusCode.OK) // = HTTP 200 code (OK)
                {
                    throw new ApplicationException(String.Format("Failed : HTTP error code : {0}", response.StatusCode));
                }

                // grab the response
                var addresses = (Addresses)((new XmlSerializer(typeof(Addresses))).Deserialize(response.GetResponseStream()));
                response.Close();

                // trivial output - display list of address summaries to console
                Console.WriteLine(String.Format("Results for: {0}", searchTerm));
                if (addresses.Address != null)
                {
                    foreach (var address in addresses.Address)
                    {
                        Console.WriteLine(address);
                    }
                }
            }
        }
        catch (Exception e)
        {
            Console.WriteLine(e.ToString());
        }
    }
}
' Postcoder VB.NET example
' Allies Computing Ltd
'
' Demonstrates UK Address lookup rest web service
'
' Product URL: https://postcoder.com/
' Technical Specs: https://postcoder.com/docs
' Example output: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/UK/NR147PZ
'
' This demo shows how to perform an address lookup and parse the results into VB.Net objects.
'
' Out of the box it uses a restricted API Key that limits the search to the postcode NR14 7PZ
'
' To experiment with different search terms, signup for a free evaluation API/Search key at:
' https://postcoder.com/sign-up
'
'  To explore different searches, Signup for an API/Search Key and assign to searchKey variable
'
' Alternatively the code below can be pasted into an online c# compiler such as
' http://www.compileonline.com/compile_vb.net_online.php
'
Imports System
Imports System.Collections.Generic
Imports System.Net
Imports System.Text
Imports System.Xml.Serialization

Public Class PostcoderClient


    ' address class
    Public Class Address

        Public organisation As String
        Public premise As String
        Public dependentstreet As String
        Public street As String
        Public doubledependentlocality As String
        Public dependentlocality As String
        Public posttown As String
        Public county As String
        Public postcode As String

        Public summaryline As String

        Public Overrides Function ToString() As String
            Return summaryline
        End Function

    End Class

    ' root element of service output
    ' essentially an array of addresses
    <XmlRootAttribute("Addresses")> _
    Public Class Addresses
        <XmlElementAttribute("Address")> _
        Public Address As List(Of Address)
    End Class

    ' code entry point
    Public Shared Sub Main()
        ' API/search key - MUST be supplied to unlock search,
        ' if this is blank a restricted key is used which limits search to NR147PZ
        Dim searchKey As String = ""
        ' processing type - for other options see
        Dim method As String = "address"
        ' search string - MUST be supplied, if blank defaults to NR147PZ
        Dim searchTerm As String = "NR14 7PZ"

        Console.WriteLine("Postcoder VB.Net Client Snippet" & vbNewLine)
        Try
            If (String.IsNullOrEmpty(searchKey)) Then
                ' no search key supplied - use the restricted evaluation key
                searchKey = "PCW45-12345-12345-1234X"
                searchTerm = "NR14 7PZ"
                Console.WriteLine("No search-key: using restricted evaluation key - resets search term to NR14 7PZ" & vbNewLine & _
                                    "To obtain a free evaluation key, signup via " & _
                                    "https://postcoder.com/sign-up" & vbNewLine _
                                    )
            End If

            ' format the url
            Dim uri As String = String.Format("http://ws.postcoder.com/pcw/{0}/{1}/UK/{2}", _
                searchKey, _
                method, _
                System.Uri.EscapeDataString(searchTerm) _
                )
            ' for other uri options see https://postcoder.com/docs

            ' call the service
            Dim request As HttpWebRequest = CType(WebRequest.Create(uri),HttpWebRequest)
            request.Method = "GET"
            request.Accept = "application/xml" ' xml or json permitted

            Using response As HttpWebResponse = CType(request.GetResponse(),HttpWebResponse)
                ' check for call failure
                If (response.StatusCode <> HttpStatusCode.OK) Then ' = HTTP 200 code (OK)
                    Throw New ApplicationException(String.Format("Failed : HTTP error code : {0}", response.StatusCode))
                End If

                ' grab the response
                Dim addresses As Addresses = New XmlSerializer(GetType(Addresses)).Deserialize(response.GetResponseStream())
                response.Close()

                ' trivial output - display list of address summaries to console
                Console.WriteLine(String.Format("Results for: {0}", searchTerm))
                If addresses.Address IsNot Nothing Then

                    For Each address As Address In addresses.Address
                        Console.WriteLine(address)
                    Next
                End If
            End Using

        Catch e As Exception
            Console.WriteLine(e.ToString())
        End Try
    End Sub
End Class
// Postcoder Java example
// Allies Computing Ltd
//
// Demonstrates UK Address lookup rest web service
//
// Product URL: https://postcoder.com
// Technical Specs: https://postcoder.com/docs
// Example output: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/UK/NR147PZ
//
// This demo shows how to perform an address lookup and parse the results into Java objects.
//
// Out of the box it uses a restricted API Key that limits the search to the postcode NR14 7PZ
//
// To experiment with different search terms, signup for a free evaluation API/Search key at:
// https://postcoder.com/sign-up
//
// Usage
// 1) Save file as PostcoderClient (to match the class name)
// 3) Compile, e.g. javac PostcoderClient.java
// 4) Run, e.g. java PostcoderClient
// Next steps:
//  - To explore different searches, Signup for an API/Search Key and assign to searchKey variable
//
// Alternatively the code below can be pasted into an online java compiler such as
// http://www.compileonline.com/compile_java_online.php

import java.util.*;
import java.lang.*;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.xml.bind.*;
import javax.xml.bind.annotation.*;

public class PostcoderClient {

    // address class
    private static class Address {
        public String organisation;
        public String premise;
        public String dependentstreet;
        public String street;
        public String doubledependentlocality;
        public String dependentlocality;
        public String posttown;
        public String county;
        public String postcode;
        public String summaryline;
        @Override public String toString() {
            return summaryline;
        }
    }

    // root element of service output
    // essentially an array of addresses
    // jaxb bindings
    @XmlRootElement(name="Addresses")
    @XmlAccessorType(XmlAccessType.FIELD)
    private static class Addresses {
        //
        @XmlElement(name="Address")
        public Address[] address;
    }

    // code entry point
    public static void main(String []args)
    {
        // API/search key - MUST be supplied to unlock search,
        // if this is blank a restricted key is used which limits search to NR147PZ
        String searchKey = "";
        // processing type - for other options see
        String method = "address";
        // search string - MUST be supplied, if blank defaults to NR147PZ
        String searchTerm = "NR14 7PZ";

		System.out.println("PostCoder Web V3 Java Client Snippet\n");
        try
        {
    		if(searchKey.isEmpty()) {
                // no search key supplied - use the restricted evaluation key
                searchKey = "PCW45-12345-12345-1234X";
                searchTerm = "NR14 7PZ";
                System.out.println(
                    "No search-key: using restricted evaluation key - resets search term to NR14 7PZ\n"
                    + "To obtain a free evaluation key, signup via "
                    + "https://postcoder.com/sign-up\n");
            }

			// format the url
			String uri = String.format("http://ws.postcoder.com/pcw/%s/%s/UK/%s",
                                            searchKey,
                                            method,
                                            java.net.URLEncoder.encode(searchTerm,"UTF-8"));
			// for other uri options see https://postcoder.com/docs

            // call the service
            HttpURLConnection connection = (HttpURLConnection) new URL(uri).openConnection();
            connection.setRequestMethod("GET");
            connection.setRequestProperty("Accept", "application/xml"); // xml or json permitted, jaxb requires xml

            // check for call failure
        	if (connection.getResponseCode() != HttpURLConnection.HTTP_OK) { // = HTTP 200 code (OK)
    			throw new RuntimeException("Failed : HTTP error code : " + connection.getResponseCode());
    		}

            // convert output to java array using jaxb
            Addresses addresses = (Addresses) JAXBContext.newInstance(Addresses.class)
                                                .createUnmarshaller()
                                                .unmarshal(connection.getInputStream());
            connection.disconnect();

            // trivial output - display list of address summaries to console
			System.out.println("Results for:" + searchTerm + "\n");
            if(addresses.address != null) {
                for(int i = 0; i < addresses.address.length; ++i) {
                    Address address = addresses.address[i];
                    System.out.println(String.format("%s",address));
                }
            }
        }
        catch(Exception e) {
            e.printStackTrace();
        }
     }
}
#	Postcoder Ruby example
#	Allies Computing Ltd
#
#	This demo shows how to perform an address lookup in ruby.
#
#   Note: This script has been developed for ruby >= 1.9.3
#

require 'cgi'
require 'json'
require 'net/http'

searchkey 	= 'PCW45-12345-12345-1234X';  # Test search key, repalce with yours
searchterm  = 'NR14 7PZ';   # string to use for an address search

puts "Postcoder Ruby Client Snippet\n\n"

URL = 'ws.postcoder.com'
QUERY = '/pcw/' + searchkey + '/address/UK/' + CGI::escape(searchterm).gsub("+", "%20")
# for other uri options see https://postcoder.com/docs

http = Net::HTTP.new(URL)
request = Net::HTTP::Get.new(QUERY)
response = http.request(request)
puts JSON.pretty_generate(JSON.parse(response.body))
#  Postcoder Python example
#  Allies Computing Ltd
#
#  This demo shows how to perform an address lookup in Python.
#

import json
import urllib

searchkey 	= 'PCW45-12345-12345-1234X'; # Test search key, replace with your
searchterm  = 'NR14 7PZ';   # string to use for an address search

print ("Postcoder Python Client Snippet\n\n")

url = 'http://ws.postcoder.com/pcw/' + searchkey + '/address/UK/'
# for other uri options see https://postcoder.com/docs

try:
    # For Python 3.0 and later
    from urllib.request import urlopen
    url = url + urllib.parse.quote(searchterm)
    response = urlopen(url).readall().decode('utf-8')
except ImportError:
    # Fall back to Python 2
    from urllib import urlopen
    url = url + urllib.quote(searchterm)
    response = urlopen(url).read()

structure = json.loads(response)
print(json.dumps(structure, indent=2))