Raster Query

The Raster Query API allows looking up a point location and getting back information from one or more Koordinates grid or raster layers. You might want to find out the elevation or land-use at a particular point.

URL

http://api.koordinates.com/api/rasterQuery/

Formats

• json (content-type: application/vnd.koordinates.rasterQuery+json).

Formats can be specified via url (eg. http://api.koordinates.com/api/rasterQuery.json/ or by using the HTTP Accept header with the appropriate content-type against the base URL.

While we try very hard to prevent backwards-incompatible breaks, it may happen in future. By default, all responses use the newest format. To specify a specific format:

• If you're using the URL endpoint (eg. rasterQuery.json) you can pass a &v=1 parameter to specify version 1.
• Pass a more specific content type with the HTTP Accept header. eg. application/vnd.koordinates.rasterQuery.1+json.
• The current version is 1.

Add a request header with Accept-Encoding: gzip to get compressed results. Makes it faster.

HTTP Method

GET

Parameters

• key: Required. Your Koordinates API key.
• layer: Required. The layer ID to get results from. The layer numbers can be found in the URL for a layer (eg. http://koordinates.com/layer/1132-land-environments-new-zealand-len... is layer 1132). Repeat this parameter to query more than one layer.
• x: Required. Longitude of the point you want to query, in decimal degrees (WGS84/EPSG:4326).
• y: Required. Latitude of the point you want to query, in decimal degrees (WGS84/EPSG:4326).
• callback: Optional. Only available for JSON formats. If supplied, will use the JSONP format with a callback of the given name. In addition, most error responses will be returned as 200-success codes, with a string error message.

Example queries:

In the queries below, replace KEY with your own API key.

• Find which land use category the point in Auckland falls into, returning JSON-formatted results.

$ curl "http://api.koordinates.com/api/rasterQuery.json/?key=KEY&layer=1132&x=174.6964&y=-36.9246"
{
  "rasterQuery": {
    "layers": {
      "1132": {
        "status": "ok", 
        "bands": [
          {
            "value": 404
          }
        ], 
        "type": "Raster"
      }
    }, 
    "location": [
      174.69640000000001, -36.924599999999998
    ]
  }
}

Response

Things to note from the above example response:

• rasterQuery.layers.#.status can be one of 'ok', 'outside-extent' (no data to query), or 'unavailable' (temporary issue).
• rasterQuery.layers.#.bands will have an object for each band in the layer, in the order of the original data.
• rasterQuery.layers.#.bands[0].value is the numeric band value for the queried location.

Usage notes

• the response time should be fairly quick (<75ms), although there's latency on top of that.
• newly created layers may take a little while to be available via the API.
• if you want to hit it more than 10,000 times in a day, please let us know first.

Roadmap:

• Return attribute value names rather than just numeric values in results.
• Faster responses.
• XML response format.
• Queries in different projections.
• What else would you like to see? Start a discussion