Address Auto-Complete

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

Before you do lots of work, please check our list of Address Finder Pluginsopen in new window. 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	Type	Values	Required	Default	Description
`key`	string	Your 20 digit code (case-insenstive)	✔️		Using the API requires a 20 character access token, which you should insert here. You will receive an access token when you sign up for an account.
`language`	string	`en`, `de`		`en`	Language for country names
`ip`	string			`en`	IP of end user for geolocation purposes, if using a relay/proxy.

Example of a countries query:

{
	"key": "xxxxx-xxxxx-xxxxx-xxxxx",
	"language": "en"
}

Response

The response contains the following information for each country:

Key	Description
`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
`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.

DANGER

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	Type	Values	Required	Description
`key`	string	Your 20 digit code (case-insenstive)	✔️	Using the API requires a 20 character access token, which you should insert here. You will receive an access token when you sign up for an account.
`query`	string		✔️	Search query
`country`	string		✔️	ISO 3166-1 country code (or internal country code)
`id`	string			`id` from previous find response
`extra`	object			An object that contains optional advanced settings (listed below)

Extra options

All these options are nested inside extra. None of these are required.

Key	Type	Default	Description
`exclude_pobox`	boolean	`false`	Exclude post office boxes from the search results.
`best_match_only`	boolean	`false`	If this is set to `true`, only the top search result will be returned.
`no_groupings`	boolean	`false`	If this is set to `true`, only individual addresses will be returned and the results will not be grouped.
`exclude_areas`	array	Empty array	Add options to the `exclude_areas` array to exclude those regions from search results. See the available options below

exclude_areas

This is an optional array of strings nested inside extra. Regions in this array will be excluded from the search results. Exclusions only apply to the relevant country, indicated by the ISO 3 prefix.

The valid options are:

Value	Description
`gbr_northern_ireland`	Excludes Northern Ireland from UK searches.
`gbr_isle_of_man`	Excludes Isle of Man from UK searches.
`gbr_isle_of_wight`	Excludes Isle of Wight from UK searches.
`gbr_channel_islands`	Excludes Channel Islands from UK searches.
`gbr_all_except_northern_ireland`	Excludes all areas except Northern Ireland from UK searches. Only addresses in Northern Ireland will be returned.
`usa_non_contiguous`	Excludes areas of the US that are not part of the 48 adjoining states: Alaska, American Samoa, Guam, Hawaii, Marshall Islands, Federated States of Micronesia, Northern Mariana Islands, Palau, Puerto Rico and Virgin Islands.
`usa_insular_areas`	Excludes any US area that is not a state or federal district: American Samoa, Guam, Marshall Islands, Federated States of Micronesia, Northern Mariana Islands, Palau, Puerto Rico and Virgin Islands
`usa_armed_forces`	This will exclude all Armed Forces Americas; Armed Forces Europe, Middle East, and Canada; and Armed Forces Pacific addresses.

Example of a find query:

{
	"key": "xxxxx-xxxxx-xxxxx-xxxxx",
	"query": "High Street",
	"country": "gbr",
	"id": "town=Maidenhead",
	"extra": {
		"exclude_areas": [
			"gbr_channel_islands",
			"gbr_northern_ireland",
			"usa_non_contiguous"
		],
		"exclude_pobox": true,
		"best_match_only": true,
		"no_groupings": true
	}
}

Response

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

{
	"results": [
        {
			"id": "postal_code_partial=SL6|town=Maidenhead|street=Bath Road",
			"count": 458,
			"labels": [
				"SL6",
				"Bath Road, Maidenhead"
			]
		},
		{
			"id": "address_id=SKmhsH4BXCTMv7Iepp8W",
			"count": 1,
			"labels": [
				"SL6 7RJ",
				"Fetchify, 3 Switchback Office Park, Gardner Road, Maidenhead"
			]
		}
	]
}

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

Key	Description
`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	Type	Values	Required	Description
`key`	string	Your 20 digit code (case-insenstive)	✔️	Using the API requires a 20 character access token, which you should insert here. You will receive an access token when you sign up for an account.
`country`	string		✔️	ISO 3166-1 country code (or internal country code)
`id`	string		✔️	`id` from find response with count equal to 1
`extra`	object			An object that contains additional advanced options like `gbr_ceremonial_counties`.

Example of a retrieve query:

{
	"key": "xxxxx-xxxxx-xxxxx-xxxxx",
	"country": "gbr",
	"id": "address_id=W7kPIn8BbQUp1JUKX04a",
	"extra": {
		"gbr_ceremonial_counties": true
	}
}

gbr_ceremonial_counties

Required: no
Values: true, false

This option is nested inside extra.

Instructs the API to return the ceremonial county name in the province_name field where available. This option only applies to the United Kingdom.

Response

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

{
    "result": {
        "administrative_area": "England",
        "administrative_area_latin": "",
        "alternative_administrative_area": "",
        "alternative_locality": "",
        "alternative_province": "Berkshire",
        "building_name": "",
        "building_number": "3",
        "company_name": "Fetchify",
        "country_name": "United Kingdom",
        "department_name": "",
        "dependent_locality": "",
        "dependent_street_name": "Switchback Office",
        "dependent_street_prefix": "",
        "dependent_street_suffix": "Park",
        "double_dependent_locality": "",
        "double_dependent_street_name": "",
        "double_dependent_street_prefix": "",
        "double_dependent_street_suffix": "",
        "level_name": "",
        "line_1": "3 Switchback Office Park",
        "line_2": "Gardner Road",
        "line_3": "",
        "line_4": "",
        "line_5": "",
        "locality": "Maidenhead",
        "post_office_box_number": "",
        "post_office_reference_1": "56711253",
        "post_office_reference_2": "1Y",
        "post_office_reference_3": "",
        "post_office_reference_4": "",
        "post_office_reference_5": "36473564",
        "post_office_reference_6": "04181235",
        "postal_code": "SL6 7RJ",
        "province": "",
        "province_code": "Berks",
        "province_latin": "",
        "province_name": "Berkshire",
        "street_name": "Gardner",
        "street_prefix": "",
        "street_suffix": "Road",
        "sub_building_name": "",
        "type": "Small User Organisation",
        "unit_name": "",
        "extra": {
            "geolocation": {
                "latitude": 51.53654,
                "longitude": -0.73529
            }
        }
    }
}

The response contains the following information:

Key	Description
`administrative_area`	Administrative area or district. In the UK, this field contains the country - England, Scotland, Wales or Northern Ireland.
`administrative_area_latin`	Administrative area or district in the Latin alphabet. This field will be empty if the `administrative_area` is already in the Latin alphabet.
`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`	Not currently used
`line_4`	Not currently used
`line_5`	Not currently used
`locality`	Town or city
`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)
`post_office_reference_3`	Unique Multiple Residence Reference Number (GBR only)
`post_office_reference_4`	Unique Property Reference Number (GBR only)
`post_office_reference_5`	PAF address key (GBR only)
`post_office_reference_6`	PAF organisation key (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_latin`	State, province or county name in the Latin alphabet. This field will be empty if the `province` and `province_name` fields are already in the Latin alphabet.
`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
`type`	Address type (UK only). Possible values are `Large User Organisation`, `Small User Organisation` and `Small User Residential`.
`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.

extra

If there is any additional information available for this address, it will be included within the extra object.

The extra object may contain a geolocation object with two properties - latitude and longitude. These are the WGS 84 coordinates for the address.

Note

You will not be able to use geocodes unless they have been enabled on your access token. Please contact us at support@fetchify.com and we will enable geocodes for you.

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

# Address Auto-Complete

# Countries

# HTTP(S) Request

# Query Parameters

# Response

# Find

# HTTP(S) Request

# Query Parameters

# Extra options

# exclude_areas

# Response

# Retrieve

# HTTP(S) Request

# Query Parameters

# gbr_ceremonial_counties

# Response

# extra

# Alternative formats

# JSON-P

# callback

Address Auto-Complete

Countries

HTTP(S) Request

Query Parameters

Response

Find

HTTP(S) Request

Query Parameters

Extra options

exclude_areas

Response

Retrieve

HTTP(S) Request

Query Parameters

gbr_ceremonial_counties

Response

extra

Alternative formats

JSON-P

callback