NAV Navbar
shell python
  • Introduction
  • Authentication
  • Locations
  • Errors
  • Introduction

    Welcome to the Targetlock API! You can use our API to access zip code/location related API endpoints, which can get information on all zip codes in the USA using a zip code, all the locations/zip codes for a city and state, and the distance between two zip 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 zip code.

    HTTP Request

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

    URL Parameters

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

    Get all Locations for a City 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) and state (administrative level 1), case insensitive.

    HTTP Request

    GET https://api.targetlock.io/v1/locations/<CITY>/<STATE>

    URL Parameters

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

    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 zip 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 zip code of the first location
    (US only)
    POST-CODE2 The zip 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 zip code you're looking for doesn't exist.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.