Documentation

Initial setup

If you're already here, then we assume you have already signed up to one of our postcode lookup plans and you can skip ahead to authorise sites. However, if not, then the first thing you will need to do, is head over to plans and signup. This is a very quick and simple process, simply login into paypal after choosing your plan, and accept the billing agreement (don't worry, you won't be charged for 3 months if signing up to our trial), and you will then be directed to, and logged into, your account where you can get your API key, and setup your authorised sites.

Authorise sites
Once you have subscribed to a plan, if you're not already logged in, login using the details that were emailed to you. On your account screen, you will see your API key. Below this, is the section for authorising your sites. You will need to add your sites to the authorised list before you can make a call, as these work in conjuction with your API key. Failure to do this will result in an "unauthorised" error response.

Making a call

To make a call to the postcode lookup API, you will need your API key, and a method of calling a url with GET parameters, as well as passing custom headers. You'll find your API key near the top of your account page

The format for calling the url and looking up a postcode is...

https://findaddress.io/API/{House number or name}/{postcode}

If you do not wish to pass over a house number, simply replace this part of the call url with NULL, and our system will pass you back the address data and geocode data without the house number embedded.

The custom headers you will need to pass across are your authorised site as "referer" your API key as "x-api-key" and a "content-type" of "application/json". Your complete call in cURL format would look like the following;

curl -X GET \
https://findaddress.io/API/10/SW1A 2AA \
-H 'Connection: keep-alive' \
-H 'Host: findaddress.io' \
-H 'cache-control: no-cache,no-cache' \
-H 'content-type: application/json' \
-H 'referer: findaddress.io' \
-H 'x-api-key: e214ec14968151e0f4bfbefdcc6be9f4582a0fae1454bdb2291149fc4a5b77cc'

Call responses

Once you have made a request to the API, there are a number of responses you may receive. We have worked hard to make the API as simplistic as possible to use, so you should only receive the addresses for the postcodes have looked up, however, we also have some simple error messages for if anything does go wrong. All of our responses are sent as JSON data and include your remianing calls that day, and remaining credits for your current month, as well as a Success/Failure response, and releated http code (this also gets sent as a http header).

Successful response

                        {
                             "result": "Success",
                             "callsRemaining": 2928,
                             "creditsRemaining": 74928,
                             "latitude": "51.503540",
                             "longitude": "-0.127695",
                             "expandedAddress": {
                                  "house": "10",
                                  "street": "Downing street",
                                  "locality": "",
                                  "town": "London",
                                  "district": "Greater london",
                                  "county": "London",
                                  "pCode": "SW1A 2AA"
                             },
                             "csvAddress": "10,Downing street,,London,Greater london,London,SW1A 2AA",
                             "statusCode": "200"
                        }

Partial Match
Partial matches are a new addition to the API (Aug 31 2024), and are returned when we have no direct match in our database or redundancies, but our redunancies have a partial match for the address you are looking up. This could be due to a street name being missing, or the postcode being part of a new development. We will always return the most accurate data we have, and if we have a partial match, we will return the data we have, and the data we are missing will be blank.
Note: Approximate geocodes are currently being considered as an addition to the data we return, but this is not yet available.

                        {
                             "result": "Partial match",
                             "callsRemaining": 2928,
                             "creditsRemaining": 74928,
                             "latitude": "",
                             "longitude": "",
                             "expandedAddress": {
                                  "house": "10",
                                  "street": "",
                                  "locality": "",
                                  "town": "London",
                                  "district": "Greater london",
                                  "county": "London",
                                  "pCode": "SW1A"
                             },
                             "csvAddress": "10,Downing street,,London,Greater london,London,SW1A",
                             "statusCode": "200"
                        }

Invalid postcode
This is the response you would get if you enter a postcode that is invalid. We cross reference numerous databases for validity of a postcode, and even have defunct postcodes within our database, as well as redundancies for any postcodes we may be missing, so if you are receiving this during an address lookup, please check the postcode is correct. It is strongly recommended to remove spaces from the house and postcode strings, however using a "+" is also allowed. Failure to remove spaces or replace them with a "+" will result in a server side 403 error due to our servers security configuration.

                        {
                              "result": "Failure",
                              "callsRemaining": "2913",
                              "creditsRemaining": "74913",
                              "errorMsg": "Postal Code Not Valid",
                              "statusCode": "400"
                        }

Unauthorised access
This the response you will receive if you are missing or have incorrect information in your API key or user agent information, or if you do not have a subcription.

                        {
                             "result": "Failure",
                             "errorMsg": "Unauthorised access",
                             "statusCode": "401"
                        }

Exceeded limit responses
These are the two responses you may receive if you have exceeded your subscription daily or monthly limits.

                        {
                             "result": "Failure",
                             "errorMsg": "You have exceeded your daily limit",
                             "statusCode": "429"
                        }

                        {
                             "result": "Failure",
                             "errorMsg": "You have exceeded your monthly limit",
                             "statusCode": "429"
                        }

Subscription lapsed
If you have not cancelled, or not renewed your subscription, it will continue until your current months end date, after that, you will receive the follwing message when trying to make a call to the API.

                        {
                             "result": "Failure",
                             "errorMsg": "Your subscription ended on 21-11-2024",
                             "statusCode": "401"
                        }

Database error
If you receive this response, something has gone wrong at our end. Most likely we are already correcting something, or updating something to make your experience better. But it's best to contact us to check!

                        {
                             "result": "Failure",
                             "errorMsg": "Database Error #errNo. - Please contact support @ findaddress.io",
                             "statusCode": "500"
                        }

Code examples

Below you will find a few examples of how you could potentially implement a call to the API. We are working on a simple javascript snippet you can also use, and, if you're already a customer, will update you once this becomes available.

PHP cURL

                            $curl = curl_init();
                            
                            curl_setopt_array($curl, array(
                               CURLOPT_URL => "https://findaddress.io/API/".urlencode($house)."/".urlencode($postcode).",
                               CURLOPT_RETURNTRANSFER => true,
                               CURLOPT_MAXREDIRS => 10,
                               CURLOPT_TIMEOUT => 30,
                               CURLOPT_CUSTOMREQUEST => "GET",
                               CURLOPT_HTTPHEADER => array(
                                 "cache-control: no-cache,no-cache",
                                 "content-type: application/json",
                                 "referer: findaddress.io",
                                 "x-api-key: e214ec14968151kud6sdjdhfgw5363h54bdb22jhs65sfeww6c"
                              ),
                            ));
                            
                            $response = curl_exec($curl);
                            $err = curl_error($curl);
                            curl_close($curl);                           
                            if ($err) {
                               echo "cURL Error #:" . $err;
                            } else {
                               echo $response;
                            }

Javascript JQuery

                            var settings = {
                               "async": true,
                               "crossDomain": true,
                               "url": "https://findaddress.io/API/[house variable]/[postcode variable],
                               "method": "GET",
                               "headers": {
                                  "cache-control": "no-cache,no-cache",
                                  "content-type": "application/json",
                                  "referer": "findaddress.io",
                                  "x-api-key": "e214ec14968151kud6sdjdhfgw5363h54bdb22jhs65sfeww6c",
                               }
                            }
                            
                            $.ajax(settings).done(function (response) {
                               console.log(response);
                            });

Node JS Native

                            var http = require("https");

                            var options = {
                               "method": "GET",
                               "hostname": [
                                  "findaddress",
                                 "io"
                               ],
                               "path": [
                                  "API",
                                  "10",
                                  "SW1A%202AA"
                               ],
                               "headers": {
                                  "cache-control": "no-cache,no-cache",
                                  "content-type": "application/json",
                                  "referer": "findaddress.io",
                                  "x-api-key": "e214ec14968151kud6sdjdhfgw5363h54bdb22jhs65sfeww6c",
                               }
                            };
                            
                            var req = http.request(options, function (res) {
                               var chunks = [];
                            
                              res.on("data", function (chunk) {
                                 chunks.push(chunk);
                              });
                            
                              res.on("end", function () {
                                 var body = Buffer.concat(chunks);
                                 console.log(body.toString());
                              });
                            });
                            
                            req.end();