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 libraryopen in new window 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.

KeyTypeValuesRequiredDefaultDescription
keystringYour 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.
languagestringen, deenLanguage for country names
ipstringenIP 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:

KeyDescription
codeInternal three character country code for country
country_nameCommon name for country in specified language
intl_long_nameInternationally-recognised full name for country
iso_3166_1_alpha_2Official ISO 3166-1 Alpha 2 code for country, or blank
iso_3166_1_alpha_3Official ISO 3166-1 Alpha 3 code for country, or blank
iso_3166_1_numeric_3Official ISO 3166-1 Numeric 3 code for country, or blank
official_nameOfficial name for country in country’s official language
short_codeInternal two character country code for country
alternative_namesArray 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.

KeyTypeValuesRequiredDefaultDescription
keystringYour 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.
querystring✔️Search query
countrystring✔️ISO 3166-1 country code (or internal country code)
idstringid from previous find response
extraobjectAn 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:

ValueDescription
gbr_northern_irelandExcludes Northern Ireland from UK searches.
gbr_isle_of_manExcludes Isle of Man from UK searches.
gbr_isle_of_wightExcludes Isle of Wight from UK searches.
gbr_channel_islandsExcludes Channel Islands from UK searches.
gbr_all_except_northern_irelandExcludes all areas except Northern Ireland from UK searches. Only addresses in Northern Ireland will be returned.
usa_non_contiguousExcludes 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_areasExcludes 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_forcesThis 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:

KeyDescription
idAn id to be used in a subsequent find or retrieve request
countNumber of results in grouping
labelsArray 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.

KeyTypeValuesRequiredDefaultDescription
keystringYour 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.
countrystring✔️ISO 3166-1 country code (or internal country code)
idstring✔️id from find response with count equal to 1
extraobjectAn 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:

KeyDescription
administrative_areaAdministrative area or district. In the UK, this field contains the country - England, Scotland, Wales or Northern Ireland.
administrative_area_latinAdministrative area or district in the Latin alphabet. This field will be empty if the administrative_area is already in the Latin alphabet.
alternative_administrative_areaAlternative administrative area or district
alternative_provinceTraditional county (GBR only)
building_nameName of building
building_numberNumber of building
company_nameName of company (GBR only)
country_nameCountry name in local language
department_nameName of department within company (GBR only)
dependent_localitySub-locality within town or city
dependent_street_nameName of the dependent street or thoroughfare
dependent_street_prefixNot currently used
dependent_street_suffixType of dependent street or thoroughfare (e.g street, road, lane, etc.) (GBR only)
double_dependent_localityDistrict within sub-locality
double_dependent_street_nameNot currently used
double_dependent_street_prefixNot currently used
double_dependent_street_suffixNot currently used
level_nameLevel name or number
line_1Formatted address line 1
line_2Formatted address line 2
line_3Not currently used
line_4Not currently used
line_5Not currently used
localityTown or city
post_office_box_numberPO Box Number (GBR only)
post_office_reference_1Royal Mail Unique Delivery Point Reference Number (GBR only)
post_office_reference_2Royal Mail Delivery Point Suffix (GBR only)
post_office_reference_3Unique Multiple Residence Reference Number (GBR only)
post_office_reference_4Unique Property Reference Number (GBR only)
post_office_reference_5PAF address key (GBR only)
post_office_reference_6PAF organisation key (GBR only)
postal_codeFormatted postal code or ZIP code
provincePreferred name, abbreviation or acronym for state, province or county
province_codeAbbreviation or acronym for state, province or county
province_latinState, 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_nameFull name of state, province or county
street_nameName of the street or thoroughfare
street_prefixNot currently used
street_suffixType of street or thoroughfare (e.g street, road, lane, etc.) (GBR only)
sub_building_nameSub-name of building
typeAddress type (UK only). Possible values are Large User Organisation, Small User Organisation and Small User Residential.
unit_nameUnit 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