Introduction

Welcome to the Targetlock API! You can use our API to access post code/location related API endpoints, which can get information on:

A location based on a post code
All the locations/post codes for a city or county (admin_level_2) and state
Autocomplete to find locations based on the a substring or full string for a post code, city or county
The distance between two post codes

We have examples in Shell, and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

Targetlock uses an authorization token to allow access to the API for all paid tier requests. You can sign up for a new Targetlock authorization token on our pricing page.

Targetlock the authorization token to be included for all paid tier API requests in a header that looks like the following:

Authorization: Token targetlockAuthToken

If you do not add this header, the request will be counted as a non-paying user and will be rate limited after 10 requests/hour.

Locations

Get a Location by Post Code

import requests

r = requests.get(
        'https://api.targetlock.io/v1/post-code/02110',
        headers={'Authorization': 'Token <targetlockAuthToken>'}
    )

curl "https://api.targetlock.io/v1/post-code/02110"
  -H "Authorization: Token targetlockAuthToken"

The above request returns the following JSON response:

{
    "post_code": "02110",
    "post_code_type": "Standard",
    "locality": "Boston",
    "admin_level_1_long": "Massachusetts",
    "admin_level_1_short": "MA",
    "admin_level_2": "Suffolk",
    "country": "United States Of America",
    "country_iso2": "US",
    "country_iso3": "USA",
    "latitude": "42.352847",
    "longitude": "-71.051466"
}

This endpoint retrieves location information for a provided post code.

HTTP Request

GET https://api.targetlock.io/v1/post-code/<POST-CODE>

URL Parameters

Parameter	Description
POST-CODE	The post code of the location (US only)

Get all Locations for a City/County and State

import requests

r = requests.get(
        'https://api.targetlock.io/v1/locations/Boston/MA',
        headers={'Authorization': 'Token <targetlockAuthToken>'}
    )

curl "https://api.targetlock.io/v1/locations/Boston/MA"
  -H "Authorization: Token targetlockAuthToken"

The above request returns the following JSON response:

[
    {
        "post_code": "02101",
        "post_code_type": "Standard",
        "locality": "Boston",
        "admin_level_1_long": "Massachusetts",
        "admin_level_1_short": "MA",
        "admin_level_2": "Suffolk",
        "country": "United States Of America",
        "country_iso2": "US",
        "country_iso3": "USA",
        "latitude": "42.370567",
        "longitude": "-71.026964"
    },
    {
        "post_code": "02102",
        "post_code_type": "Standard",
        "locality": "Boston",
        "admin_level_1_long": "Massachusetts",
        "admin_level_1_short": "MA",
        "admin_level_2": "Suffolk",
        "country": "United States Of America",
        "country_iso2": "US",
        "country_iso3": "USA",
        "latitude": "42.338947",
        "longitude": "-70.919635"
    },
    ...
]

This endpoint retrieves all locations for a given city (locality) or county (administrative level 2) and state (administrative level 1), case insensitive.

HTTP Request

GET https://api.targetlock.io/v1/locations/<CITY/COUNTY>/<STATE>
GET https://api.targetlock.io/v1/locations/<CITY/COUNTY>/<STATE>?field=locality

URL Parameters

Parameter	Description
CITY	The city/locality of the location (case insensitive)
COUNTY	The county/administrative level 2 of the location (case insensitive)
STATE	The state/administrative level 1 of the location (case insensitive. 2 character abbreviation or full name)

Query Parameters

Parameter	Default	Options	Description
field	locality	locality admin_level_2	If set to admin_level_2, locations will be searched by county/administrative level 2

Autocomplete Incremental Search by Post Code, City or County

import requests

r = requests.get(
        'https://api.targetlock.io/v1/autocomplete/bost/',
        headers={'Authorization': 'Token <targetlockAuthToken>'}
    )

curl "https://api.targetlock.io/v1/autocomplete/bost/"
  -H "Authorization: Token targetlockAuthToken"

The above request returns the following JSON response:

[
    {
        "locality": "Bostic",
        "admin_level_1_long": "North Carolina",
        "admin_level_1_short": "NC",
        "admin_level_2": "Rutherford",
        "country": "United States Of America",
        "country_iso2": "US",
        "country_iso3": "USA"
    },
    {
        "locality": "Boston",
        "admin_level_1_long": "Georgia",
        "admin_level_1_short": "GA",
        "admin_level_2": "Thomas",
        "country": "United States Of America",
        "country_iso2": "US",
        "country_iso3": "USA"
    },
    ...
]

This endpoint retrieves unique locations for a given search query (city/locality, post code, county/administrative level 2) and optional state (administrative level 1), case insensitive.

HTTP Request

GET https://api.targetlock.io/v1/autocomplete/<CITY/POST-CODE/COUNTY>/
GET https://api.targetlock.io/v1/autocomplete/<CITY/POST-CODE/COUNTY>/?field=post_code
GET https://api.targetlock.io/v1/autocomplete/<CITY/POST-CODE/COUNTY>/<STATE>
GET https://api.targetlock.io/v1/autocomplete/<CITY/POST-CODE/COUNTY>/<STATE>?field=admin_level_2

URL Parameters

Parameter	Description
CITY	The city/locality of the location (case insensitive)
POST-CODE	The post code of the location
COUNTY	The county/administrative level 2 of the location (case insensitive)
STATE (optional)	The state/administrative level 1 of the location (case insensitive. 2 character abbreviation or full name)

Query Parameters

Parameter	Default	Options	Description
field	locality	locality post_code admin_level_2	If set to admin_level_2, locations will be searched by county/administrative level 2

Get Distance Between Two Post Codes

import requests

r = requests.get(
        'https://api.targetlock.io/v1/distance/02110/90210/miles',
        headers={'Authorization': 'Token <targetlockAuthToken>'}
    )

curl "https://api.targetlock.io/v1/distance/02110/90210/miles"
  -H "Authorization: Token targetlockAuthToken"

The above request returns the following JSON response:

{
    "distance": "2608.1410851585474"
}

This endpoint returns the distance between two post codes using the given unit. If the unit is not specified, it will default to miles.

HTTP Request

GET https://api.targetlock.io/v1/distance/<POST-CODE1>/<POST-CODE2>/<UNIT>

URL Parameters

Parameter	Description
POST-CODE1	The post code of the first location (US only)
POST-CODE2	The post code of the second location (US only)
UNIT	The unit in which you would like the distance

Supported Distance Units

Unit	Valid Values (case insensitive)
Miles	`miles`, `mi`
Kilometers	`kilometers`, `km`
Meters	`meters`, `m`
Feet	`feet`, `ft`
Nautical Miles	`nautical`, `nmi`, `nm`

Errors

The Targetlock API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your Authorization Token is incorrect.
404	Not Found -- The endpoint you're looking for doesn't exist.
429	Too Many Requests -- You're making too many requests! The "detail" key in the response will contain how long until you can start making requests again. The waiting period starts from when the last successful request was received.
500	Internal Server Error -- The post code you're looking for doesn't exist.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.