JSON API

The JSON API gives access to postal address data for over 240 countries. It supports CORS and can return data as JSON or JSONP.

Before you do lots of work, please check our list of Address Finder Plugins. You might find something suitable there.

We also have a JavaScript library which implements a full web UI on top of the API.

The typical use scenario of the API can be summarised as follows:

  • Countries call to get a full list of available countries.
  • A sequence of Find calls each returning a set of results for the search query
  • A final Retrieve call to get the full address

Countries

Firstly, we perform a Countries call to get a list of the available countries.

HTTP(S) Request

GET/POST https://api.craftyclicks.co.uk/address/1.1/countries

Query Parameters

Pass parameters either as GET or POST in JSON.

key

  • Required: yes

Your access token.

language

  • Required: no
  • Default: ‘en’

Language for country names ('en’, 'de’).

ip

  • Required: no

IP of end user for geolocation purposes, if using a relay/proxy.

Response

The response contains the following information for each country:

code

Internal three character country code for country

country_name

Common name for country in specified language

intl_long_name

Internationally-recognised full name for country

iso_3166_1_alpha_2

Official ISO 3166-1 Alpha 2 code for country, or blank

iso_3166_1_alpha_3

Official ISO 3166-1 Alpha 3 code for country, or blank

iso_3166_1_numeric_3

Official ISO 3166-1 Numeric 3 code for country, or blank

official_name

Official name for country in country’s official language

short_code

Internal two character country code for country’s

alternative_names

Array of other common alternative names for country

The API will respond to the request with the following structure.

{
    "countries": [
        {
            "code": "usa",
            "country_name": "United States",
            "intl_long_name": "America, United States of",
            "iso_3166_1_alpha_2": "US",
            "iso_3166_1_alpha_3": "USA",
            "iso_3166_1_numeric_3": 840,
            "official_name": "United States of America",
            "short_code": "us",
            "alternative_names": []
        }
    ]
}

Find

A Find call returns a set of results for a search query.

WARNING

The Find endpoint is meant to be used in combination with the Retrieve endpoint. (see below) Please note that Find requests without a succeeding Retrieve request are considered an improper use of the service, and can result in account suspension.

HTTP(S) Request

GET/POST https://api.craftyclicks.co.uk/address/1.1/find

Query Parameters

Pass parameters either as GET or POST in JSON.

key

  • Required: yes

Your access token

query

  • Required: yes

Search query

country

  • Required: yes

ISO 3166-1 country code (or internal country code)

id

  • Required: no

ID from previous find response

ip

  • Required: no

IP of end user for geolocation purposes, for use with relays

coords

  • Required: no

Two-element array of co-ordinates (latitude and longitude) of end user for geolocation purposes (e.g. from HTML5 geolocation)

Response

The API will respond to the request with the following structure.

{
    "results": [
        {
            "id": "||20002|87",
            "count": 36,
            "labels": [
                "SL",
                "High Street, Slough"
            ]
        }
    ]
}

The response contains the following information, per address or grouping:

id

An ID to be used in a subsequent find or retrieve request

count

Number of results in grouping

labels

Array containing one or two strings describing the address or grouping

TIP

If the count is equal to 1, the ID can be used in a retrieve request to get the full address. Otherwise, groupings can be expanded by passing the ID to the API in another find request.

Retrieve

A Retrieve call returns the full address data for a search result.

HTTP(S) Request

GET/POST https://api.craftyclicks.co.uk/address/1.1/retrieve

Query Parameters

Pass parameters either as GET or POST in JSON.

key

  • Require: yes

Your access token

country

  • Require: yes

ISO 3166-1 country code (or internal country code)

id

  • Require: yes

ID from find response with count equal to 1

lines

  • Require: no
  • Default: 2

Number of lines required

Response

The API will respond to the request with the following structure.

{
    "result": {
        "administrative_area": "",
        "alternative_administrative_area": "",
        "alternative_locality": "",
        "alternative_province": "Berkshire",
        "building_name": "St. Andrews House",
        "building_number": "",
        "company_name": "Crafty Clicks Ltd",
        "country_name": "United Kingdom",
        "department_name": "",
        "dependent_locality": "",
        "dependent_street_name": "",
        "dependent_street_prefix": "",
        "dependent_street_suffix": "",
        "double_dependent_locality": "",
        "double_dependent_street_name": "",
        "double_dependent_street_prefix": "",
        "double_dependent_street_suffix": "",
        "level_name": "",
        "line_1": "St. Andrews House",
        "line_2": "St. Marys Walk",
        "line_3": "",
        "line_4": "",
        "line_5": "",
        "locality": "Maidenhead",
        "post_office_box_number": "",
        "post_office_reference_1": "53875002",
        "post_office_reference_2": "4N",
        "postal_code": "SL6 1QZ",
        "province": "Berkshire",
        "province_code": "Berks",
        "province_name": "Berkshire",
        "street_name": "St. Marys",
        "street_prefix": "",
        "street_suffix": "Walk",
        "sub_building_name": "",
        "unit_name": ""
    }
}

The response contains the following information:

administrative_area

Administrative area or district

alternative_administrative_area

Alternative administrative area or district

alternative_province

Traditional county (GBR only)

building_name

Name of building

building_number

Number of building

company_name

Name of company (GBR only)

country_name

Country name in local language

department_name

Name of department within company (GBR only)

dependent_locality

Sub-locality within town or city

dependent_street_name

Name of the dependent street or thoroughfare

dependent_street_prefix

Not currently used

dependent_street_suffix

Type of dependent street or thoroughfare (e.g street, road, lane, etc.) (GBR only)

double_dependent_locality

District within sub-locality

double_dependent_street_name

Not currently used

double_dependent_street_prefix

Not currently used

double_dependent_street_suffix

Not currently used

level_name

Level name or number

line_1

Formatted address line 1

line_2

Formatted address line 2

line_3

Formatted address line 3

line_4

Formatted address line 4

line_5

Formatted address line 5

locality

Town or city

metropolitan_area

Metropolitan postal district (IRL and HUN only)

post_office_box_number

PO Box Number (GBR only)

post_office_reference_1

Royal Mail Unique Delivery Point Reference Number (GBR only)

post_office_reference_2

Royal Mail Delivery Point Suffix (GBR only)

postal_code

Formatted postal code or ZIP code

province

Preferred name, abbreviation or acronym for state, province or county

province_code

Abbreviation or acronym for state, province or county

province_name

Full name of state, province or county

street_name

Name of the street or thoroughfare

street_prefix

Not currently used

street_suffix

Type of street or thoroughfare (e.g street, road, lane, etc.) (GBR only)

sub_building_name

Sub-name of building

unit_name

Unit name or number

TIP

For the majority of use cases, the company_name field (GBR only), any non-blank formatted address lines, along with the locality, province and country_name fields are all that you are likely to need. The province field is not officially required in the UK.

Alternative formats

JSON-P

To get a response as JSON-P, set the Accept header to text/javascript and pass parameter either as GET or POST in JSON.

callback

  • Required: no

Name of callback function for JSON-P

Last Updated: 9/4/2018, 12:45:44 PM