Integration

Postcode Lookup 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 Javascript 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-567833

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

Block Address

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

Line By Line

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

That Was Easy !

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"
}

Errors

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
 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 8.4 and provides an alpine.js front end 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, nodejs 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 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 in our SecureZone

Postcode Services