Postcode address lookups in the UK - Developer instructions

Integration

Firstly, if you are reading this and you are not the developer of your website, we recommend getting your developer to read this page. The instructions for integration are really easy, however they are only easy for people who build web sites.

Requirements

As long as you can create the appropriate HTTP 'GET' request to our system, you can use any language you like. There are no technical requirements such as SOAP or XML etc. You will likely be developing the lookup service using a combination of Javascrpt for the front end integration and then a PHP or ASP or Java type solution for the back end. The need for a "back end" solution is firstly to ensure that your "access token" is kept private (otherwise anyone could access your postcode lookups), but also to handle the "cross domain" issue that would happen if your domain tried to talk to our domain directly in a browser. The API is designed to be run over https for privacy although because there is no financial or personal data being transacted between the systems, you can access it via http if you have a need to do it but as this integration will be via a server based process, we would recommend using https.

The API

The postcode lookup service uses a REST API over a simple GET HTTP request. You simply send a message to our system, specifying a particular header in the request details so that we know who is making the request and you make 2 calls to the system. The first will request summary details of each address at that postcode provided, and the second will request the full address details for the address the user selected. ITS THAT SIMPLE!

Example

Using your choice of tools (such as Curl with PHP), send a message with

X-Postcode-Auth: [Your Postcode Key]

such as

X-Postcode-Auth: 36272-56783

in the HTTP Header as part of a GET request to

https://api.mobunti.net/postcodes/summary/ZE3+9JU

If your supplied key is valid, this will return a JSON string of results

{
   "data":[
      {
         "id":"27478064",
         "summary":"1a, Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478065",
         "summary":"1b, Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478075",
         "summary":"2a, Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478076",
         "summary":"2b, Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478077",
         "summary":"3 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478078",
         "summary":"4 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478079",
         "summary":"5 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478080",
         "summary":"6 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478081",
         "summary":"7 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478082",
         "summary":"8 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478083",
         "summary":"9 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478066",
         "summary":"10 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478067",
         "summary":"11a, Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478068",
         "summary":"11b, Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478069",
         "summary":"12a, Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478070",
         "summary":"12b, Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478071",
         "summary":"13 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478072",
         "summary":"14 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478073",
         "summary":"15 Horseshoe Close, Virkie, SHETLAND"
      },
      {
         "id":"27478074",
         "summary":"16 Horseshoe Close, Virkie, SHETLAND"
      }
   ],
   "command":"summary"
}

The data is pre sorted into the correct numeric order (where a number is available). You will see from the example that the 11a and 11b appear before 12a and 12b etc. This data is then managed by your system to show in a manner in which you want to show it - drop down select box, radio box, etc etc, and when a user has selected an address, simply pass the same Postcode Authorisation Key into a new header where the GET request goes to

 https://api.mobunti.net/postcodes/detail/27478069

Where 27478069 is the id that was passed back to you in the earlier JSON code. You will then receive a second JSON response

{  
   "data":{  
      "elements":{  
         "building_number":"",
         "building_name":"12a",
         "subbuilding_name":"",
         "thoroughfare":"Horseshoe Close",
         "dependent_thoroughfare":"",
         "dependent_locality":"Virkie",
         "town":"SHETLAND",
         "po_box":"",
         "department":"",
         "organisation":"",
         "postcode_type":"S",
         "premise":"12a",
         "country":"Scotland",
         "postcode_inward":"9JU",
         "postcode_outward":"ZE3",
         "udprn":27478069,
         "delivery_point_suffix":"2A",
         "county":"Shetland Islands",
         "administrative_county":"",
         "postal_county":"Shetland Islands",
         "traditional_county":"Shetland",
         "district":"Shetland Islands",
         "ward":"Shetland South",
         "longitude":-1.3072059985,
         "latitude":59.8895464723,
         "eastings":438872,
         "northings":1111807,
         "su_organisation_indicator":""
      },
      "excluding_town_and_postcode":[  
         "12a Horseshoe Close",
         "Virkie"
      ],
      "line_one_no_thoroughfare":[  
         "12a",
         "Horseshoe Close",
         "Virkie"
      ],
      "town":"SHETLAND",
      "postcode":"ZE3 9JU",
      "blockaddress":"12a Horseshoe Close\nVirkie\nSHETLAND\nShetland Islands\nZE3 9JU",
      "id":27478069,
      "linebyline":[  
         "12a Horseshoe Close",
         "Virkie",
         "SHETLAND",
         "Shetland Islands",
         "ZE3 9JU"
      ]
   },
   "command":"detail"
}

that you can then use to fill the data in on your web based order / enquiry form.

The JSON response is split into distinct areas that you can use

elements

These are the Royal Mail data elements that we work with. They are the component parts of the address. You will notice that if the address belongs to a company, you have the organisation name and optionally a department name stored within the elements. These names can be added to the address in your code to create a full address for addressing purposes

excluding_town_and_postcode

This contains the address elements up to but not including the town and postcode. Some customers have a block of text to hold the main part of the address and then a secondary input box to hold the town and then a final one to hold the postcode.

line_one_no_thoroughfare

Where an address is 12a Horseshoe Close for example, some input systems require the 12a on one line and the Horseshoe Close on the next line. Many addresses can have multiple parts to the address prior to the name of the street and so in these cases there is no difference between this and the 'excluding_town_and_postcode' block but as you can see in the "home" type address such as 12a Horseshoe Close, this ensures that this part of the address is split over 2 lines. Wherever possible, this area will ensure there are at least 2 lines of address without the town and postcode

town

The town is self explanatory. This can be added to either of the 2 previous blocks or output into another text input box

postcode

Regardless of whether the user typed in a correctly formatted postcode - i.e. they might have typed A B 10 1H W but the postcode will be correctly formatted here

blockaddress

Simply the entire address, ideal for "textarea" type input boxes to hold the entire address

linebyline

Exactly the same as block address but returned as an array for easy use

See, we told you it was simple !

There is in fact a third request so that you can programmatically identify how many lookups you have got left

 https://api.mobunti.net/postcodes/available

and this will simply return an array of all purchased packages, with the quantity purchased, the quantity used, when it was purchased, and if the package has been completed, what date it was completed. You can periodically retrieve these details to ascertain usage of the system. We will automatically drop an email notification to you when a package is 10% away from finishing and 2% away from finishing (unless you already have another package active) and also at the point you run out completely

{

   "data":[
      {
         "date_purchased":"2015-08-24 20:34:12",
         "quantity":"500",
         "quantity_used":"67",
         "date_completed":null
      }
   ],
   "command":"available"
}

And finally, there is an additional option on the initial summary request that you can make use of. After the postcode, you can pass a unique identifier of the user - whether that be their IP address, their login username, their user id, etc. Anything up to 60 characters. This will allow you to implement a user limit on lookups per day, or possibly for reporting purposes. For example

https://api.mobunti.net/postcodes/summary/ZE3+9JU/1.2.3.4   (for an ip address)


or

https://api.mobunti.net/postcodes/summary/ZE3+9JU/56287234    (for a user id)

With this second option, for example, you can limit the number of lookups that user id 56287234 can perform within a 24 hour period in case you have a user who places one order per day but uses your screen to carry out 200 address lookups for their own purposes. You want them to continue placing orders but you can limit a maximum user usage to maybe 20 or 30 per day if required.

If you pass through an invalid token in the header, you will receive a HTTP 403 Access denied response with a JSON response detailing the reason

{

   "data":
      {
         "error":"INVALID-TOKEN",
         "description":"Provided token was not valid"
      }
}

The coded responses are


 INVALID-TOKEN     - The provided authentication token could not be found
 EXCEEDED          - You have used more than the "max per day" specified on the access point for that user
 NONELEFT          - No purchased packs are available to use
 INVALID-ID        - The full address ID was not provided in the correct format
 NOTFOUND-ID       - The full address ID was not found
 NOTFOUND-POSTCODE - The postcode provided was not found
 BLOCKED           - If you were to misuse the system your account may be blocked (see below)

If your service is ever blocked, it would be, for example, for excessive requests to see how many lookups have been used several hundred times per day - we would notify you before this happens so that you can rectify a rogue program, but if we dont get any response to the problem, we reserve the right to protect the integrity of our systems for our users

When you download the sample code, it is written for PHP 5.3+ and provides a Javascript / jQuery front end service and a small PHP script which is used to hide the token being submitted and also to solve the cross domain restrictions in modern browsers. You simply pass your request to your small stub proxy file - whether that is PHP, ASP, Java etc, and this proxy script talks from your server to ours to interact and get the data and then you simply output the results on screen so that your javascript/jQuery can handle the response. All you need to do is open the file called postcode.php and at the top of the file, put the token details that are visible within the Postcode Control Panel

Download Sample Code Now

Postcode Lookup, Developer Notes