Geocoda API

Introduction

 

The Geocoda API is organized into two major feature groups: Location and Storage. The Location API allows callers to discover detailed information about places. The Storage API allows you to store and query geospatial data.

The API endpoints are designed to have predictable names. Authentication is performed using HTTP basic authentication. All API calls are stateless, and can be easily tested with in a browser or a command line HTTP client such as cURL.

All responses from the API will be JSON.

Authentication

All requests to the Geocoda API must be authenticated with HTTP basic authentication. To use your API key, provide it as the username and "x" as the password when authenticating for an API request. All requests must be made via HTTPS; requests sent via HTTP will be rejected.

Please keep in mind that all API calls using your API key will count toward your quotas and billing, so be sure to protect their secrecy.

Locations

 

The Locations service allows the caller to specify a location and responds with geographic coordinates and other background information about that location.

Base URL

https://api.geocoda.com/v1/loc

Geocoding

The geocoding endpoint finds geographic coordinates (latitude and longitude) for a specified address. In addition to coordinates, successful requests also return background information about the location itself. This will include the political jurisdictions (city, county, state, census data) and more. To geocode an address, provide the address to the Geocoding endpoint. Addresses should be formatted as follows:

123 Main Street, Anycity, ST, 01010

Please note that addresses should be properly encoded for inclusion in the requesting URL.

Endpoint URL

GET https://api.geocoda.com/v1/loc/geocode/{ADDRESS}

Example Request

$ curl --u 15678ce5b0fae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/loc/geocode/77%20Massachusetts%20Avenue%20Cambridge%20MA%2002139


Example Response

{
  "timestamp": 1333063456.08152,
  "query": {
    "address": "77 Massachusetts Ave,Cambridge,MA 02139",
    "longitude": -71.094265,
    "latitude": 42.359739,
    "precision": 1.0,
    "confidence": "range"
  },
  "address": {
    "type": "Feature",
    "properties": {
      "country": "US",
      "city": "Cambridge",
      "postcode": "02139",
      "county": "Middlesex",
      "distance": 0,
      "province": "MA"
    },
    "geometry": {
      "type": "Point",
      "coordinates": [
        -71.094265,
        42.359739
      ]
    }
  },
  "features": [
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "Neighborhood",
          "subcategory": ""
        }
      ],
      "abbr": "",
      "name": "Mit"
    },
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "US Census",
          "subcategory": "Tract"
        }
      ],
      "abbr": "",
      "name": "353102"
    },
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "Administrative",
          "subcategory": "County"
        }
      ],
      "abbr": "",
      "name": "Middlesex"
    },
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "Urban Area",
          "subcategory": ""
        }
      ],
      "abbr": "",
      "name": "Cambridge"
    },
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "Subnational",
          "subcategory": "State"
        }
      ],
      "abbr": "MA",
      "name": "Massachusetts"
    }
  ]
}

Coordinate Lookup

The coordinate endpoint finds background information for a specified latitude/longitude coordinate. The information provided include the political jurisdictions (county, state, census data) and more. To perform a coordinate lookup, simply provide the latitude and longitude of the desired point to the coordinate lookup endpoint.

Endpoint URL

GET https://api.geocoda.com/v1/loc/coord/{LATITUDE},{LONGITUDE}

Example Request

$ curl --u 15678ce5b0fae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/loc/coord/33.756907,-84.388116


Example Response

{
  "timestamp": 1333062096.9151807,
  "query": {
    "latitude": "33.756907",
    "longitude": "-84.388116"
  },
  "features": [
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "Neighborhood",
          "subcategory": ""
        }
      ],
      "abbr": "",
      "name": "Five Points"
    },
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "US Census",
          "subcategory": "Tract"
        }
      ],
      "abbr": "",
      "name": "011900"
    },
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "Administrative",
          "subcategory": "County"
        }
      ],
      "abbr": "",
      "name": "Fulton"
    },
    {
      "classifiers": [
        {
          "type": "Region",
          "category": "Subnational",
          "subcategory": "State"
        }
      ],
      "abbr": "GA",
      "name": "Georgia"
    }
  ]
}

Storage

 

The Storage service allows the caller to store any GeoJSON feature as a record in a database. Features can be points (a latitude and a longitude), polygons, or any other shape supported by GeoJSON. Records are grouped into layers, and users can add new layers to store different sets of points at any time.

Throughout the documentation, wherever you see reference to a point, assume that reference applies to other geometry shapes as well.

Base URL

https://api.geocoda.com/v1/storage

Get Layers

The layers endpoint retrieves all of the layers currently associated with the given user. You can retrieve up to 100 layers at a time.

Properties (Query String)

  • limit - The maximum number of layers to retrieve in this request, not to exceed 100. It will retrieve all layers if there are fewer than the limit. Default is 100.
  • offset - The number of layers to skip before starting. Callers can use offset and limit to manage paging. Default is 0.

Endpoint URL

GET https://api.geocoda.com/v1/storage/layers

Example Request

$ curl --user 156759f5b1aef0fae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/storage/layers?limit=100&offset=0


Example Response

"layers": [
  {
    "name": "Store Locations",
    "description": "All of our stores"
    "created_at": 1332521772.3066306,
    "updated_at": 1335773823.2883984
  },
  {
    "name": "Future Store Sites",
    "description": "Where we're thinking about expanding"
    "created_at": 1338282838.3066306,
    "updated_at": 1339283838.2891737
  },
  {
    "name": "Competitors Locations",
    "description": "Our competitor's sites"
    "created_at": 1338282733.2342348,
    "updated_at": 1339287555.8889947
  }
],
"offset": 0

Get Single Layer

The layer endpoint gets details about a particular layer.

Endpoint URL

GET https://api.geocoda.com/v1/storage/layers/{layer}

Example Request

$ curl --user 156759f5b1aef0fae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/storage/layers/Store%20Locations


Example Response

  {
    "name": "Store Locations",
    "description": "All of our stores"
    "created_at": 1332521772.3066306,
    "updated_at": 1335773823.2883984
  }

Create/Update Layer

This endpoint will create or update a layer. If the layer name does not exist, a new layer is created. If the layer name exists, the description is updated.

The POST method is officially supported, but the PUT method is also supported for create or update.

Endpoint URL

POST https://api.geocoda.com/v1/storage/layers/{layer}

Example Request

$ curl -X POST --user 156759f51aef0fae058311c428cb634dbb64bc32743:x \ https://api.geocoda.com/v1/storage/layers/New%20Layer -d '{"description":"Details about this layer"}'

Example Response

{
  "name": "New Layer",
  "description": "Details about this layer"
  "created_at": 1332521772.3066306,
  "updated_at": 1335773823.2883984
}

Delete Layer

This endpoint deletes a layer from the system and all associated records and record history. The call returns the layer that was just deleted.

This operation is not recoverable, and once a layer is deleted, its records are no longer stored in the system.

Endpoint URL

DELETE https://api.geocoda.com/v1/storage/layers/{layer}

Example Request

$ curl -X DELETE --user 156759f5b01aeffae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/storage/layers/Layer%20To%20Delete 


Example Response

{
  "name": "Layer To Delete",
  "description": "Layer that I deleted."
  "created_at": 1332521772.3066306,
  "updated_at": 1335773823.2883984
}

Get Records

The records endpoint retrieves all of the records currently associated with a particular layer as an array of GeoJSON Feature objects. You can retrieve up to 100 records at a time.

Properties (Query String)

  • limit - The maximum number of records to retrieve in this request, not to exceed 100. It will retrieve all records if there are fewer than the limit. Default is 100.
  • offset - The number of records to skip before starting. Callers can use offset and limit to manage paging. Default is 0.

Endpoint URL

GET https://api.geocoda.com/v1/storage/records/{layer}

Example Request

$ curl --user 156759f5b01aeffae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/storage/records/Store%20Locations?limit=100&offset=0


Example Response

{
  "records": [
  {
      "id": "Store%20Atlanta",
    "geometry": {
      "type": "Point",
      "coordinates": [
        -82.11234,
        44.16168
      ],
    "properties" {
    "created_at": "1333075904.1958458",
    "updated_at": "1333238475.7372982",
        "layer": "Store Locations"
    }
  },      
  {
      "id": "Store%20Decatur",
    "geometry": {
      "type": "Point",
      "coordinates": [
         -66.287474,
          19.283745
      ],
    "properties" {
      "created_at": "1332175823.2789284",
      "updated_at": "1335823285.9348793",      
        "layer": "Store Locations",
    }
  }      
  ],
  "offset": 0
}

Get Record

This endpoint retrieves a single record by name as a GeoJSON Feature. Please note that due to the nature of the underlying geographic coordinate system, that the first coordinate returned is longitude and the second is latitude.

Endpoint URL

GET https://api.geocoda.com/v1/storage/records/{layer}/{record}

Example Request

$ curl --user 156759f5b01aeffae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/storage/records/Store%20Locations/Store%20Decatur


Example Response

{
    "id": "Store%20Decatur",
  "geometry": {
    "type": "Point",
    "coordinates": [
       -66.287474,
        19.283745
    ],
  "properties" {
    "created_at": "1332175823.2789284",
    "updated_at": "1335823285.9348793",      
      "layer": "Store Locations",
  }
}      

Create/Update Record

This endpoint will create or update a record. If the record name does not exist, a new record is created. If the record name exists, the details are updated.

The POST method is officially supported, but the PUT method is also supported for create or update.

At this time, we do not support the setting of properties.

Endpoint URL

POST https://api.geocoda.com/v1/storage/records/{layer}/{record}

Example Request

$ curl --user 156759f5b01aeffae058311c428cb634dbb64bc32743:x \ 
https://api.geocoda.com/v1/storage/records/Store%20Locations/Store%20Decatur -d '{"type":"Feature","geometry": {"type": "Point","coordinates": [-66.287474,19.283745]}'


Example Response

{
    "id": "Store%20Decatur",
  "geometry": {
    "type": "Point",
    "coordinates": [
       -66.287474,
        19.283745
    ],
  "properties" {
    "created_at": "1332175823.2789284",
    "updated_at": "1335823285.9348793",      
      "layer": "Store Locations",
  }
}

Create/Update Multiple Records

This endpoint will create or update a set of records from a GeoJSON FeatureCollection. If the record name does not exist, a new record is created. If the record name exists, the description is updated.

At this time, we do not support the setting of properties.

Endpoint URL

POST https://api.geocoda.com/v1/storage/records/{layer}

Example Request

$ curl --user 156759f5b01aeffae058311c428cb634dbb64bc32743:x \ 
https://api.geocoda.com/v1/storage/records/Store%20Locations -d '["features":[{"id": "Store%20Atlanta", "type":"Feature","geometry": {"type": "Point","coordinates": [-65.791233,20.283825]},{"id": "Store%20Decatur", "type":"Feature","geometry": {"type": "Point","coordinates": [-66.287474,19.283745]}]]'


Example Response

2 records updated.

Delete Record

This endpoint deletes a record and associated history and properties from the system.

This operation is not recoverable, and once a record is deleted, its information no longer stored in the system.

Endpoint URL

DELETE https://api.geocoda.com/v1/storage/records/{layer}/{record}

Example Request

$ curl --user 156759f5b01aeffae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/storage/records/Store%20Locations/Store%20Decatur


Example Response

{
    "id": "Store%20Decatur",
  "geometry": {
    "type": "Point",
    "coordinates": [
       -66.287474,
        19.283745
    ],
  "properties" {
    "created_at": "1332175823.2789284",
    "updated_at": "1335823285.9348793",      
      "layer": "Store Locations",
  }
}

Get Record History

This endpoint returns the historical list of locations associated with this record. Each time a record's coordinates or properties are updated, an entry is added to the record history. Up to 100 history entries can be retrieved per record.

History is retrieved as a GeoJSON GeometryCollection of past geographic locations.

Properties (Query String)

  • limit - The maximum number of history points to retrieve in this request, not to exceed 100. It will retrieve all history if there are fewer points than the limit. Default is 100.
  • offset - The number of historical points to skip before starting. Callers can use offset and limit to manage paging. Default is 0.

Endpoint URL

GET https://api.geocoda.com/v1/storage/records/{layer}/{record}/history

Example Request

$ curl --user 156759f5b01aeffae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/storage/records/Store%20Locations/Store%20Decatur/history


Example Response

{
        "type":"GeometryCollection",
        "geometries": [
  {
    "type": "Point",
    "coordinates": [
      -66.287474,
      19.283745
    ],
    "created_at": 1333076158.175508
  },
  {
    "type": "Point",
    "coordinates": [
      -65.263822,
      18.981879
    ],
    "created_at": 1332283828.278372
  }
  {
    "type": "Point",
    "coordinates": [
      -42.191733,
      28.328793
    ],
    "created_at": 1332038828.127277
  }
]

Get Nearby Records

This endpoint retrieves all the records within range of the specified point.

Properties (Query String)

  • limit - The maximum number of records to retrieve in this request, not to exceed 100. It will retrieve all records if there are fewer than the limit. Default is 100.
  • offset - The number of records to skip before starting. Callers can use offset and limit to manage paging. Default is 0.
  • radius - The distance from the specified point, in meters. Default is 1000.
  • bounding_box - A set of coordinates specifying the lower left and upper right corners of a box within which you wish to search. If boundingbox is set, radius is ignored. Example: if your latitude/longitude point is 19.455216,-66.287201, a valid bounding box might be: boundingbox=18.455216,-67.287201,20.455216,-65.287201.

Endpoint URL

GET https://api.geocoda.com/v1/storage/records/{layer}/nearby/{lat},{lon}.json

Example Request

$ curl --user 156759f5b01aeffae058311c428cb634dbb64bc32743:x \ 
    https://api.geocoda.com/v1/storage/records/Store%20Locations/nearby/19.455216,-66.287201


Example Response

{
  "records": [
  {
      "id": "Store%20Atlanta",
    "geometry": {
      "type": "Point",
      "coordinates": [
        -82.11234,
        44.16168
      ],
    "properties" {
    "created_at": "1333075904.1958458",
    "updated_at": "1333238475.7372982",
        "layer": "Store Locations"
    }
  },      
  {
      "id": "Store%20Decatur",
    "geometry": {
      "type": "Point",
      "coordinates": [
         -66.287474,
          19.283745
      ],
    "properties" {
      "created_at": "1332175823.2789284",
      "updated_at": "1335823285.9348793",      
        "layer": "Store Locations",
    }
  }      
  ],
  "offset": 0
}