NAV

ClickToAddress API

The ClickToAddress API speeds up postal address entry and improves the accuracy of addresses captured.

Key features:

To try all the API features, please sign up for a free trial account.

JavaScript

For most web applications, we recommend using our JavaScript library. It implements a UI layer on top of our API and greatly simplifies the integration work needed.

JSON API

For projects where no JavaScript support is available or if you want to do the integration yourself, skip to the JSON API.

JavaScript

For any integration, there are two pieces of JavaScript that you need: our JavaScript library and some configuration code. See the tutorial for more details on how to add this code to the page containing your address form.

JavaScript Library

Link to the JavaScript library:

<script src="https://cc-cdn.com/generic/scripts/v1/cc_c2a.min.js"></script>

There are two options for adding the JavaScript library:

Firstly, we host the final, compacted code on a CDN. This means that to add the JavaScript library to your page, you simply need to include this link. We recommend that you use this option, as you will automatically receive updates and bug fixes.

Alternatively, you can download the JavaScript and host it on your own server. You can download the package here from Github.

Basic Configuration Options

These are the basic configuration options that should be included as part of any integration.

Example of basic configuration options:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx', // Replace this with your access token
    dom: {
        search:     'search_field', // 'search_field' is the name of the search box element
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    domMode: 'name' // Use names to find form elements
});
Parameter Type Description Values Default
accessToken string 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. Your 20 digit code
dom object This is an object with DOM element references. By default, it finds elements by name, but this can be changed using domMode. Contains elements to which search is applied
domMode string (Optional) Specifies how the elements are passed in to the ‘dom’ object. For example, if this is set to 'id’, you would set the values in the 'dom’ object to the IDs of the form elements. Property to use to select element: 'name’, 'id’, 'class’ or 'object’ 'name’

Form Elements

Below is a list of the elements that can be included in the 'dom’ object.

The value that each option is set to will be the name, id or class of the element, or the object itself, depending on how the domMode is set. If domMode is not set, element names will be used.

Only 'search’ is required; the others are optional.

Parameter Type Description Values
search string The input box you want to use for the address search. A user can type a search query into this field and suggestions will be shown below this box as the user types. name, id or class of element, or object
line_1 string Address line 1 element
line_2 string Address line 2 element
company string Company element
town string Town/city element
postcode string Postcode/ZIP element
county string County/state element
country string Country element

Advanced Configuration Options

These are additional configuration options. None of these are required; if these options are not set then the default value will be used.

Search Box Interface

Example using the interface configuration options:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx', // Replace this with your access token
    dom: {
        search:     'search_field', // 'search_field' is the name of the search box element
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    domMode: 'name', // Use names to find form elements
    gfxMode: 1, // Display interface below search box
    style: {
        ambient: 'light', // Use white as main interface color
        accent: 'default' // Use default secondary color for interface
    },
    // Use a custom CSS file
    cssPath: 'https://yoursite.com/your_asset_folder/clicktoaddress/cc_c2a.min.css',
    placeholders: true, // Show placeholders
    texts: {
        default_placeholder: 'Start with post/zip code or street',
        country_placeholder: 'Type here to search for a country',
        country_button: 'Change Country',
        generic_error: 'An error occured. Please enter your address manually',
        no_results: 'No results found'
    },
    showLogo: true, // Show ClickToAddress logo
    historyTools: true, // Show arrows
    defaultCountry: 'gbr', // Sets the default country to the UK
    getIpLocation: true, // Sets default country based on IP
    countrySelector: true, // Country list is enabled
    enabledCountries: ['gbr', 'usa', 'can'], // Enabled countries are the UK, USA and Canada
    countryMatchWith: 'iso_3', // enabledCountries uses ISO_3 codes
    countryLanguage: 'en', // Country list displayed in English
    disableAutoSearch: false // Auto-search is enabled
});

These options are used to customise the search box interface. You can customise the appearance of the interface, change the country options and even disable the auto-search feature.

Parameter Type Description Values Default
gfxMode integer Sets the way the search interface is displayed. 1: The search interface is displayed below the address search box
2: The search interface surrounds the search box.
1
style object This object contains options for primary and secondary colors for the search interface. See the colors section for more details.
cssPath string This is the path to the main CSS file that is used for the search box interface. A file path The default CSS file on our CDN
placeholders bool Use HTML placeholders on input boxes. (set by 'texts’ object) true, false
texts object List of texts to use for placeholders and labels in the search interface See the texts section for more details.
showLogo bool Option for showing the clickToAddress logo on the search interface. true, false true
historyTools bool Show history navigation arrows. These allow a user to go 'back’ and 'forward’ through their search history, meaning the user can view previous search results from an earlier query. true, false true
defaultCountry string This option allows you to manually change the default country for the address search. This is the country that will be selected for the user at initialization. If this option is set, it overrides getIpLocation. If it is not set, the default value is overridden by getIpLocation. Any ISO_3 country code. 'gbr’
getIpLocation bool Uses the server to fetch the end-user’s country from the IP address. This country is then selected for the user at initialization. If defaultCountry is set, this option is overridden. true, false true
countrySelector bool Enable/disable the list of countries in the search interface. If this is disabled, address search will only work for the default country. true, false true
enabledCountries array This allows you to restrict the address search to only include certain countries. Only countries in the array are enabled. If the array is not set or empty, all countries are allowed. The format of the strings in the array is set by the countryMatchWith option. Array of strings All countries
countryMatchWith string How the enabledCountries are set. This sets the format of the strings in the enabledCountries array. 'iso_3’: will match countries to ISO_3 codes in enabledCountries array
'iso_2’: will match countries to ISO_2 codes in enabledCountries array
'text’: fuzzy match to any country detail in enabledCountries array
'iso_3’
countryLanguage string Set the language for the country list in the search interface. 'en’, 'de’ 'en’
disableAutoSearch bool Disables searching as the user types. This can allow the search to be performed manually (for example, by clicking on a button) after the user has entered the search query. true, false true

Example of configuration including functions executed on an event:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx', // Replace this with your access token
    dom: {
        search:     'search_field', // 'search_field' is the name of the search box element
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:        'addr_country'
    },
    domMode: 'name', // Use names to find form elements
    onResultSelected: function(c2a, elements, address){
        // Perform any action here with the available data.
        // For example, you could reveal all the form fields when the fields are filled.
    },
    onSetCounty: function(c2a, elements, county){
        // Perform any action here with the available data.
        // You may want your own function to change the county, depending on your checkout.
    },
    onError: function(code, message){
        // Perform any action here with the available data.
        // For example, you may want to reveal the form fields if there is an error.
    },
    onSearchFocus: function(c2a, elements){
        // Perform any action here with the available data.
        // For example, you may want to highlight part of the form when the search box is selected.
    }
});

Example of tag:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx',
    dom: {
        search:     'search_field',
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    tag: 'Shopify' // Tag can be used to identify the integration
});

Events

These functions are executed at certain times and can be used to override basic functionality.

Parameter Type Description Fn Parameters
onResultSelected function Executed after the results are filled in. class object, dom object, result object
onSetCounty function Executed instead of filling the county input element. class object, dom object, county object
onError function Executed on when an error occurs. code, message
onSearchFocus function Executed when the address search input field has focus. class object, dom object

Advanced

Parameter Type Description
relay string This allows the user to override the URL to the server (for relay purposes).
tag string This allows the JavaScript to send a unique value that can later be used to identify the request (in logs). We mainly use this to identify our integration packages.

Colors

Example of configuration using custom colors:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx',
    dom: {
        search:     'search_field',
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    style: {
        ambient: 'dark', // Use black as main interface color
        accent: 'deepPurple' // Use deepPurple as secondary color for interface
    }
});

The 'style’ object contains two keys, which can be used to set the main and secondary colors.

Parameter Type Description Values Default
ambient string Sets the main color scheme for the search interface. 'light’, 'dark’ 'light’
accent string Sets the secondary color for the search interface. See the list of possible colors below. 'default’

The following secondary colors are available:

Color Code Color Code Color Code
default
red
pink
purple
deepPurple
indigo
blue
lightBlue
cyan
teal
green
lightGreen
lime
yellow
amber
orange
deepOrange
brown
grey
blueGrey

Example of configuration with custom texts:

new clickToAddress({
    accessToken: 'xxxxx-xxxxx-xxxxx-xxxxx',
    dom: {
        search:     'search_field',
        line_1:     'addr_line1',
        line_2:     'addr_line2',
        company:    'company',
        town:       'addr_town',
        postcode:   'addr_postcode',
        county:     'addr_county',
        country:    'addr_country'
    },
    texts: {
        // Placeholder to be displayed in the search box
        default_placeholder: 'Start with post/zip code or street',
        // Placeholder to be displayed when searching for a country in search box
        country_placeholder: 'Type here to search for a country',
        // Text to be displayed on button to change country in search interface
        country_button: 'Change Country',
        // Text to be displayed when an error occurs
        generic_error: 'An error occured. Please enter your address manually',
        // Text to be displayed when no results are found
        no_results: 'No results found'
    }
});

Texts

The 'texts’ object can be used to customize the text that is displayed as part of the search interface.

Parameter Type Description Default
default_placeholder string Placeholder to be displayed in the search box 'Start with post/zip code or street’
country_placeholder string Placeholder to be displayed when searching for a country in search box 'Type here to search for a country’
country_button string Text to be displayed on button to change country in search interface 'Change Country’
generic_error string Text to be displayed when an error occurs 'An error occured. Please enter your address manually’
no_results string Text to be displayed when no results are found 'No results found’

Functions

Basic example of attach - using first parameter only

cc = new clickToAddress(config);
cc.attach({
    search:     'search_field',
    town:       'addr_town',
    postcode:   'addr_postcode',
    county:     'addr_county',
    line_1:     'addr_line1'
});

Advanced example of attach - using both parameters

cc = new clickToAddress(config);
cc.attach({
    search:     'search_field',
    town:       'addr_town',
    postcode:   'addr_postcode',
    county:     'addr_county',
    line_1:     'addr_line1'
},
{
    onResultSelected: function(c2a, elements, address){
        // perform action here
    },
    onSetCounty: function(c2a, elements, address){
        // perform action here
    }
});

In many cases, it’s worth storing the result of the class initialization as a variable. Functions can be executed on this variable, such as the attach function.

attach

This function attaches the search functionality to a new set of elements. This allows the developer to initialize the class once, and then apply the search functionality to multiple forms on the same page. The attach function runs by default, if the configuration includes the dom object.

Attach accepts two parameters. The first is the 'dom’ object for the new set of elements. This contains the following parameters:

Parameter Description
search Input box to use for address search
line_1 Address line 1 element
line_2 Address line 2 element
company Company element
town Town/city element
postcode Postcode/ZIP element
county County element
country Country element

The second, optional parameter is also an object, and can be used to pass in config overrides for the new “instance” of the address search. Allowed configuration options for this method are:

Error Messages

Code Message
JS500 Unknown Server Error
JS501 API server seems unreachable
JS502 API search request resulted in a JS error.
JS503 API address retrieve request resulted in a JS error.
JS505 API countrylist retrieve request resulted in a JS error.
JS401 Invalid value for countryMatchWith. Fallback to “text”

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

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.

Parameter Default Required Description
key yes Your access token
language ‘en’ no Language for country names ('en’, 'de’)
ip no IP of end user for geolocation purposes, if using a relay/proxy

Response

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": []
        }
    ]
}

The response contains the following information for each country:

Parameter 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

Find

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

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.

Parameter Default Required Description
key yes Your access token
query yes Search query
country yes ISO 3166-1 country code (or internal country code)
id no ID from previous find response
ip no IP of end user for geolocation purposes, for use with relays
coords 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:

Parameter 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

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.

Parameter Default Required Description
key yes Your access token
country yes ISO 3166-1 country code (or internal country code)
id yes ID from find response with count equal to 1
lines 2 no 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:

Parameter Description
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

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.

Parameter Required Description
callback no Name of callback function for JSON-P