Sample code

Your Search Key (also known as an API Key) must be included in each request to the API.

Make sure you replace the default Search Key in the examples below with your own Search Key.

If you haven't got a Search Key already, sign up for a free trial.

Example forms

These examples demonstrate an address lookup using the address method and the population of address fields on a form.

More examples can be downloaded from the PostCoder admin pages once signed up.

Community submitted examples and Integrations

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

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

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

Code snippets

These snippets demonstrate an address lookup using the address method.

<?php
  /*
  PostCoder Web Service V3 example
	Allies Computing Ltd 2014 
	
	Demonstrates UK Address lookup rest web service
	
	Product URL: https://www.alliescomputing.com/postcoder/address-lookup
	Technical Specs: https://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise
	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://www.alliescomputing.com/postcoder/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 Web V3 PHP Client Snippet<br><br>';
  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<br>'
  		. 'To obtain a free evaluation key, signup via'
  		. 'https://www.alliescomputing.com/postcoder/sign-up<br>'
      . '<br>';	
  }
  // build the URL, using the 'address' search method:
  $URL = 'http://ws.postcoder.com/pcw/' . $searchKey .'/address/UK/' . rawurlencode($searchterm) ;
  // for other uri options see https://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise
  
  // 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 . '<br><br>';
  if (count($addresses) > 0){  
    foreach ($addresses as $address){
      echo  $address->summaryline,"<br>";
    }
  }
  else{
    echo 'No results, please try again.';
  }
?>

Link to Gist on Github
// PostCoder Web Service V3 example
// Allies Computing Ltd 2013 
//
// Demonstrates UK Address lookup rest web service
//
// Product URL: https://www.alliescomputing.com/postcoder/address-lookup
// Technical Specs: https://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise
// 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://www.alliescomputing.com/postcoder/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 
        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://www.alliescomputing.com/postcoder/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://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise

            // 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());
        }
    }
}


Link to Gist on Github
' PostCoder Web Service V3 example
' Allies Computing Ltd 2013 
'
' Demonstrates UK Address lookup rest web service
'
' Product URL: https://www.alliescomputing.com/postcoder/address-lookup
' Technical Specs: https://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise
' 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://www.alliescomputing.com/postcoder/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 PCWV3Client


    ' 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 Web V3 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://www.alliescomputing.com/postcoder/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://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise

            ' 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


Link to Gist on Github
// PostCoder Web Service V3 example
// Allies Computing Ltd 2013 
//
// Demonstrates UK Address lookup rest web service
//
// Product URL: https://www.alliescomputing.com/postcoder/address-lookup
// Technical Specs: https://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise
// 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://www.alliescomputing.com/postcoder/sign-up
//
// Usage
// 1) Save file as PCWV3Client (to match the class name)
// 3) Compile, e.g. javac PCWV3Client.java
// 4) Run, e.g. java PCWV3Client
// 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 PCWV3Client {

    // 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://www.alliescomputing.com/postcoder/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://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise
            
            // 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();
        }
     }
}

Link to Gist on Github
#	PostCoder Web Service V3 example
#	Allies Computing Ltd 2014
#	
#	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 Web V3 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://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise
 
http = Net::HTTP.new(URL)
request = Net::HTTP::Get.new(QUERY)
response = http.request(request)
puts JSON.pretty_generate(JSON.parse(response.body))

Link to Gist on Github
#  PostCoder Web Service V3 example
#  Allies Computing Ltd 2014
#  
#  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 Web V3 Python Client Snippet\n\n")
 
url = 'http://ws.postcoder.com/pcw/' + searchkey + '/address/UK/'
# for other uri options see https://developers.alliescomputing.com/postcoder-web-api/address-lookup/premise
 
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))

Link to Gist on Github