Fetchify Documentation

# 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

WARNING

All API parameters should be in lowercase.

# Countries

First, 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 (case-insenstive).

# 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 (case-insenstive).

# 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

Important

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

  • Required: yes

Your access token (case-insenstive).

# 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

← Postcode Lookup API →