# 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