Using the Administrative 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 administrative 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 administrative area information

The XY2AdminInfo API requires latitude and longitude coordinates as starting parameters.

xy2admininfo

Specify latitude (y) and longitude (x) values, as input parameters, for the location for which you wish to obtain administrative level information in GeoJSON format. Furthermore, specify the administrative level to which the information returned is related.

curl -X GET
  https://api.geojunxion.com/adminv1/xy2admininfo?x={longitude}&y={latitude}&type={admin level}
  -H 'accept: application/json'
  -H 'x-api-key: {token}'
  -H 'cache-control: no-cache'
  -H 'content-type: application/json'

Where for ‘admin’ you can fill in:

  • admin0 : Admin 0 boundaries contain the highest administrative level in the hierarchy: the country
  • admin1, admin2, ... , admin7 : Admin 1-7 boundaries contain smaller administrative divisions which per layer cover the complete country
  • admin8 : Admin 8 boundaries contain the lowest administrative level in the hierarchy. In most cases, the municipalities are included at this level.

A list of all available administrative levels per country, 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: code belonging to administrative level = 900, 901, … , 908

category_name: administrative level = admin0, admin1, … , admin8

name: official name of administrative entity

The result will be:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": null,
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            …
          ]
        ]
      },
      "geometry_name": "geometry",
      "properties": {
        "boundary_id": 10000001,
        "country_code": 31,
        "country_name": "The Netherlands",
        "category_code": "900",
        "category_name": "admin0",
        "name": "Nederland;NLD",
        "bbox": [
          4.3815,
          51.5051,
          4.8555,
          52.1939
        ]
      }
    }

  ],
  "totalFeatures": 1,
  "numberMatched": 1,
  "numberReturned": 1,
  "timeStamp": "2020-03-09T01:17:00.981Z",
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:EPSG::4326"
    }
  },
  "bbox": [
    51.5051,
    4.3815,
    52.1939,
    4.8555
  ]
}

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