Using the Geo-Boundaries API

Let’s get started with the API. The API has one option, the reverse look-up where the input is a set of GPS coordinates which are then translated to information regarding the area that these inputted coordinates are within. 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.

 

 

Getting geo-boundary information

The XY2BoundData API requires latitude and longitude coordinates as starting parameters. Next to these, the boundary category is an optional parameter.

xy2bounddata

Specify latitude (y) and longitude (x) values, as input parameters, for the location for which you wish to obtain area information in GeoJSON format. Optionally, specify the boundary category (geo_boundary) to which the information returned needs to be related.

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

Where for ‘geo_boundary’ you can specify the category in which the search needs to be done. This is an optional parameter, and therefore when not specified, the information of all geo-boundaries matching the request will be returned. When specified, only the geo boundaries of a given category are considered.

A list of all available geo-boundary categories, can be found here.

 

The result contains info regarding the administrative boundaries that were found:

boundary_id: id of the boundary found

country_code: code belonging to the country

country_name: official name of the country

category_code: category code belonging to geo-boundary , see list

category_name: category name, see list

geo_boundary_name: name of the geo-boundary, when available.

When no geo_boundary is specified, the result will be:

{
  "boundaries": [
    {
      "boundary_id": 369789,
      "country_code": 31,
      "country_name": "The Netherlands;NLD",
      "category_code": 109,
      "category_name": "Industrial area",
      "geo_boundary_name": "Rotterdam Noord-West",
      "sub_category_code": null,
      "sub_category_name": null
    },
    {
      "boundary_id": 4297300,
      "country_code": 31,
      "country_name": "The Netherlands;NLD",
      "category_code": 95,
      "category_name": "Capital or Metropolis",
      "geo_boundary_name": "Rotterdam",
      "sub_category_code": null,
      "sub_category_name": null
    }
  ]
}

When geo_boundary is specified (per example: 109), the result will be:

{
  "boundaries": [
    {
      "boundary_id": 369789,
      "country_code": 31,
      "country_name": "The Netherlands;NLD",
      "category_code": 109,
      "category_name": "Industrial area",
      "geo_boundary_name": "Rotterdam Noord-West",
      "sub_category_code": null,
      "sub_category_name": null
    }
  ]
}

 

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