Skip to content
Help

Vector query

The Vector Query API allows users to request information related to a point location from one or more Koordinates vector datasets.

URL

Section titled “URL”

The endpoint depends on the Koordinates site you’re using. On koordinates.com it’s:

GEThttps://koordinates.com/services/query/v1/vectorQuery vector features near a point

Formats

Section titled “Formats”

The vector query API returns in JSON: content-type: application/vnd.koordinates.vectorQuery+json. Results are encoded as GeoJSON-compatible Feature objects.

Formats can be specified via URL. For example: https://koordinates.com/services/query/v1/vector.json

They can also be specified using the HTTP Accept header with the appropriate content-type against the base URL. For example: application/vnd.koordinates.vectorQuery-1+json

By default, all responses use the newest format. While we try very hard to prevent backwards-incompatible breaks, please note that it may happen in future

If you’re using the URL endpoint (eg. vector.json) you can pass a &v=1 parameter to specify version 1.0. The current version is 1.1.

Compression

Section titled “Compression”

Add a request header with Accept-Encoding: gzip to get compressed results. This dramatically reduces the size of the response and will speed up your API requests.

Parameters

Section titled “Parameters”

All parameters are available for 1.0, except where noted.

  • key: Required, unless you send your key in an Authorization: key YOUR_API_KEY header instead. Your Koordinates API key.
  • layer: Required. The number of the vector layer to get results from. The layer numbers can be found in the URL for a layer (eg. https://koordinates.com/layer/743-nz-school-zones-april-2009/ is layer 743). Repeat this parameter to query more than one layer, up to a maximum of 20 layers.
  • x: Required. Longitude of the point you want to query, in decimal degrees (WGS84/EPSG:4326). The valid range is -180 to 180.
  • y: Required. Latitude of the point you want to query, in decimal degrees (WGS84/EPSG:4326). The valid range is -90 to 90.
  • max_results: Optional (default 1). Returns a maximum of this many results. The valid range is 1-100. Results are sorted by distance from the query point, so closest results will always be returned first.
  • radius: Optional (default 1000). Distance in metres to query around the specified point. The valid range is 0-100000 (100km).
  • geometry: Optional (default ‘false’). Whether to return the attributes only (false) or both the attributes and the geometry (true) for each feature result. Geometry coordinates are returned in WGS84 Lat/Long (EPSG:4326).
  • precision: Optional (default 8). The number of decimal places for GeoJSON geometry coordinates. The valid range is 0-15.
  • with_field_names: Optional (default ‘false’). Whether to include an ordered list of field names. Availability: 1.1
  • callback: Optional. 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.

Errors

Section titled “Errors”

An invalid request returns HTTP 400 with a plain-text message that names the parameter, for example max_results: Ensure this value is less than or equal to 100. A missing or invalid key returns 403. A layer that doesn’t exist is left out of the response rather than causing an error, so check that each layer you asked for is in vectorQuery.layers. If you supply callback, most errors are returned as a 200 with the message wrapped in the callback.