Using the Geocoder

The Geocoder API has two options, the regular address to GPS coordinates function and the reverse look-up whereby GPS coordinates are translated to an address. We will take you through some of the functionalities of the API via a step by step process.  If you are already familiar with the API, you might want to jump straight to the Swagger definitions.

In our examples, we will use Curl.

If you are on Linux or OS X, you already have this installed. Windows users can get it here. You can simply copy and paste the examples, but you will need to replace certain values with information that is specific to your situation.

Getting started

Contact our support team to request an API Key. You can request an API key through the request key section. With this API key, you will be able to access the related API and if applicable your usage will be automatically tracked and billed. Your API key will be between 30 and 128 characters long. Just scroll down to our How to purchase your API section to select your preferred shirt size model and make your credit card payment via our provider Stripe

Getting location data

Let’s demonstrate the regular address to GPS look-up. Values you need to fill in yourself are located within the brackets. Geocoding responses are returned in the format indicated by the format parameter within the URL.

curl -X GET 
  https://api.and.com/zip4v1geocoder/geocoder?address={address}&format={json_or_xml} 
  -H 'accept: application/json' 
  -H 'x-api-key: {token}' 
  -H 'cache-control: no-cache' 
  -H 'content-type: application/json'

The result will be:

{
    "results": [
        {
            "address_components": [
            {
               "long_name": "Chewelah",
               "short_name": "Chewelah",
               "types": [
                  "sublocality",
                  "political"
               ]
            },
	(..rest of the object)
    ],
    "status": "OK"
}

Please note that the range can contain multiple addresses if the address supplied returns multiple hits.

Address Types and Address Component Types

The types[] range in the result indicates the address type. Examples of address types include a street address, a country, or a political entity. There is also a types[] range in the address_components[], indicating the type of component for each part of the address.

Examples include street number or country. (Below is a full list of types.) Addresses may have multiple types. The types may be considered as ‘tags’. For example, many cities are tagged with the political and the locality type.

Reverse look-up

As mentioned before our geocoder also provides a reverse look-up option. Please enter the latitude and longitude values specifying for the location you wish to obtain the closest, human-readable address.

curl -X GET 
  https://api.and.com/zip4v1geocoder/rev-geocoder?x={longitude}&y={latitude}&format={json_or_xml}
  -H 'accept: application/json' 
  -H 'x-api-key: {token}' 
  -H 'cache-control: no-cache' 
  -H 'content-type: application/json'

The result will be:

{
    "results": [
        {
            {
               "long_name": "101",
               "short_name": "101",
               "types": [
                  "street_number"
               ]
            },
            {
               "long_name": "South 3rd Street",
               "short_name": "South 3rd Street",
               "types": [
                  "route"
               ]
            },
	(..rest of the object)
    ],
    "status": "OK"
}

Note that the reverse geocoder can return more than one result. The “formatted_address” results are not just postal addresses, but also the geographic name of a specific location. For example, when geocoding a point in the city of Rotterdam or Chicago, the geocoded point may be denoted as a street address, such as the city (Rotterdam or Chicago), such as the province (Zuid Holland) or state (Illinois) or such as the country (The Netherlands or the United States). All are “addresses” in the geocoder. The reverse geocoder returns any of these types as valid results.

The reverse geocoder matches political entities (countries, provinces, cities and neighborhoods), street addresses, and postal codes.

The full list of formatted_address values returned by the previous query is shown below.

"formatted_address": "101 South 3rd Street, Philadelphia PA, 191062818, United States",

Generally, addresses are returned from most specific to least specific; the more exact address is the most prominent result, as it is in this case.

Please note that the reverse geocoding is an estimate. The geocoder will attempt to find the closest addressable location within a certain tolerance. If no match is found, the geocoder will return zero results.

Reverse Geocoding Status Codes

The "status" field within the Geocoding response object contains the status of the request, and may contain debugging information to help you track down why reverse geocoding is not working. The "status" field may contain the following values:

  • "OK" indicates that no errors occurred and at least one address was returned.
  • "ZERO_RESULTS" indicates that the reverse geocoding was successful but returned no results. This may occur if the geocoder was passed a latlng in a remote location.
  • "INVALID_REQUEST" generally indicates one of the following:
    • The query (addresscomponents or latlng) is missing.
    • An invalid result_type or location_type was given.
  • "UNKNOWN_ERROR" indicates that the request could not be processed due to a server error. The request may succeed if you try again.

If the API token is incorrect, you will receive {"message":"Forbidden"}

If your questions haven’t been addressed on this page, please contact us at support@and.com.

SDKS

will be uploaded soon

How to Purchase our API Service

AND offers a new and unique T-shirt size pricing model. It is both very simple and cost effective. Shirt sizes provide you with a “flat fee model”, which means that you can consume as many API calls during the month up to the limit of your selected shirt size.

Each subscription starts with a 14 day trial period. You will then be able to cancel your subscription without your account being charged. To cancel please contact our support desk. Payments will go through our payment provider Stripe. Subscriptions will renew automatically if they are not cancelled.

2XS for up to 50,000 requests/month
XS for up to 100,000 requests/month
M for up to 500,000 requests/month
L for up to 1,000,000 requests/month
XL for up to 2,500,000 requests/month
For 2,500,000+ requests/month Please contact our Sales Department