Using the ZIP+4 USA API

Let’s get started with the API. The API has two options, the regular address to GPS coordinates function and the reverse look-up where the input is a set of GPS coordinates which are then translated to an address. We will take you through some of the functionalities of the API step by step. If your questions aren’t answered on this site, please contact us.

In our examples, we will use Curl. If you’re on Linux or OS X, you already have it 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 applies to your specific situation.

Getting started

GET YOUR FREE API KEY

First of all, you need to get some credentials. With an API key you will be able to access the related API and if applicable your usage will be automatically tracked and billed. Just click on the “GET YOUR FREE API KEY” button above, to apply for a free trial. Your API key will be between 30 and 128 characters long.

For purchasing you can go to our pricing table, and select your preferred shirt size model and make your credit card payment via our provider Stripe.

Getting location data

Retrieving the ZIP+4 code

The XY2Zip method, for retrieving ZIP+4 codes, requires latitude and longitude coordinates as starting parameters. If you only have an address list you can use the AND Geocoder API to retrieve the ZIP+4 code including the matching latitude and longitude coordinates.

xy2zip

Specify latitude and longitude values, as input parameters, for the location for which you wish to obtain polygons in GeoJSON format.

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

The result will be:

{
    "type": "FeatureCollection",
    "totalFeatures":2,
    "features":[
        {
            "type":"Feature",
            "id":"zip_plus4_v1_0.191062913_42101",
            "geometry":{
                   "type":"MultiPolygon",
                   "coordinates":[
                          [
                                 [
                                        [-75.1447,39.9478],
                                        [-75.1454,39.9479],
                                        [-75.1461,39.948],
                                        (..rest of the object)
                                 ]
                          ]
                    ],
             },
             "geometry_name":"geom",
             "properties": {
                    "uid":"191062818_42101",
                    "zip":"19106",
                    "zip9":"191062818",
                    "fips":"42101",
                    "bbox":[-75.1462,39.9465,-75.1443,39.9486]
             }
        },
        (..rest of the object)
    ],
    "crs":{
        "type":"name",
        "properties":{"name":"urn:ogc:def:crs:EPSG::4326"}
    },
    "bbox":[39.9465,-75.1462,39.9486,-75.1443]
}

Retrieving the boundary and coordinates of a ZIP+4 code

The Zip2XY method, for retrieving the boundary and coordinates, requires a ZIP+4 code as a starting parameter, only.

zip2xy

Specify a zip+4 code, as input parameter, for the location for which you wish to obtain polygons in GeoJSON format.

curl -X GET 
  https://api.and.com/zip4v1/xy2zip?zip9={zip9_code} 
  -H 'accept: application/json' 
  -H 'x-api-key: {token}' 
  -H 'cache-control: no-cache' 
  -H 'content-type: application/json'

The result will be:

{
  "type": "FeatureCollection",
  "totalFeatures": 1,
  "features": [
    {
      "type": "Feature",
      "id": "zip_plus4_v1_0.191062818_42101",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                -75.1443,
                39.9472
              ],
              [
                -75.1444,
                39.9468
              ],
              (..rest of the object)
            ]
          ]
        ]
      },
      "geometry_name": "geom",
      "properties": {
        "uid": "191062818_42101",
        "zip": "19106",
        "zip9": "191062818",
        "fips": "42101",
        "bbox": [
          -75.1462,
          39.9465,
          -75.1443,
          39.9486
        ]
      }
    }
  ],
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:EPSG::4326"
    }
  },
  "bbox": [
    39.9465,
    -75.1462,
    39.9486,
    -75.1443
  ]
}

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

SDKS

It is also possible to access the API using our supplied SDKS for Android and iOS. Each zip file contains a readme with details how to use the resource.