Vector Query

The Vector Query API allows looking up a point location and getting back information from one or more Koordinates vector layers. You might want to find out the school zone for a point, or which meshblock or electorate its in. Or maybe just the nearest bus routes, bank ATMs, or airport.

URL

http://api.koordinates.com/api/vectorQuery/

Formats

• json (content-type: application/vnd.koordinates.vectorQuery+json). Results are encoded as GeoJSON-compatible Feature objects.
• xml (content-type: application/vnd.koordinates.vectorQuery+xml). A schema is available. Geometries are encoded as GML v3 geometry objects.
• json-gmaps (content-type: application/vnd.koordinates.vectorQuery-gmaps+json). For use with the Google Maps API, geometries are returned as arrays of geometry objects, with linestrings & polygons encoded for faster display & smaller response-size.

Formats can be specified via url (eg. http://api.koordinates.com/api/vectorQuery.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. vectorQuery.json) you can pass a &v=1 parameter to specify version 1.1
• Pass a more specific content type with the HTTP Accept header. eg. application/vnd.koordinates.vectorQuery.1+json or application/vnd.koordinates.vectorQuery.1-gmaps+json.
• The current version is 1.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 number of the vectory layer to get results from. The layer numbers can be found in the URL for a layer (eg. http://koordinates.com/layer/743-nz-school-zones-april-2009/ is layer 743). 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).
• 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 meters 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).
• with_field_names: Optional (default 'false'). Whether to include an ordered list of field names. New in version 1.1.
• 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 school zones the point in Auckland falls into, returning JSON-formatted results with no geometries.

$ curl "http://api.koordinates.com/api/vectorQuery.json/?key=KEY&layer=743&x=174.6964&y=-36.9246&radius=0"
{
  "vectorQuery": {
    "layers": {
      "743": {
        "crs": {
          "type": "name", 
          "properties": {
            "name": "EPSG:4326"
          }
        }, 
        "type": "FeatureCollection", 
        "features": [
          {
            "distance": 0, 
            "type": "Feature", 
            "properties": {
              "INSTTYPE": "Contributing", 
              "ApprovalDate": "11-02-2003", 
              "SchoolID": 1233, 
              "Office": "AK", 
              "EffectiveDate": "11-02-2003", 
              "SchoolName": "Blockhouse Bay School", 
              "chk": "Yes", 
              "Underreview": "--"
            }
          }, 
          {
            "distance": 0, 
            "type": "Feature", 
            "properties": {
              "INSTTYPE": "Intermediate", 
              "ApprovalDate": "09-09-2008", 
              "SchoolID": 1232, 
              "Office": "AK", 
              "EffectiveDate": "09-09-2008", 
              "SchoolName": "Blockhouse Bay Intermediate School", 
              "chk": "Yes", 
              "Underreview": ""
            }
          }
        ]
      }
    }
  }
}

• Find the nearest DOC campsite within 10km of my point in Auckland, returning XML-formatted results with geometries.

$ curl "http://api.koordinates.com/api/vectorQuery.xml/?key=KEY&layer=553&x=176.2537&y=-38.1432&max_results=1&radius=100000&geometry=true"
<?xml version='1.0'?>
<kx:vectorQuery xmlns:gml="http://www.opengis.net/gml" xmlns:kx="http://api.koordinates.com/schema/vectorQuery/1.0">
  <kx:layers>
    <kx:layer id="553">
      <gml:featureMember>
        <kx:feature distance="19276">
          <gml:Point srsName="EPSG:4326">
            <gml:coordinates>176.433391000096,-38.2435439998996</gml:coordinates>
          </gml:Point>
          <kx:attributes>
            <ID>1116561</ID>
            <NAME>Hot Water Beach campsite, Lake Tarawera</NAME>
            <TAGS>DOC conservation campsite. Accommodation, camping</TAGS>
            <WEBSITE>http://www.doc.govt.nz/templates/ByRegionLanding.aspx?id=37039</WEBSITE>
            <ADDRESS>Waimangu Stewardship Area, Rotorua Lakes</ADDRESS>
            <PHONE />
            <HOURS />
            <CREATED_AT>2007-07-27 15:12:44</CREATED_AT>
            <UPDATED_AT>2008-01-06 16:15:03</UPDATED_AT>
          </kx:attributes>
        </kx:feature>
      </gml:featureMember>
    </kx:layer>
  </kx:layers>
</kx:vectorQuery>

• Find the nearest road to the summit of Mt. Ngaurahoe, returning JSON-formatted results with Google Maps encoded geometries.

$ curl -H "Accept: application/vnd.koordinates.vectorQuery-gmaps+json" "http://api.koordinates.com/api/vectorQuery/?key=KEY&layer=40&x=175.6343&y=-39.1588&max_results=1&radius=100000&geometry=true"
{
  "vectorQuery": {
    "layers": {
      "40": {
        "geometryType": "GPolyline", 
        "features": [
          {
            "distance": 4800, 
            "properties": {
              "created_da": "0E-15", 
              "name": "MANGATEPOPO ROAD", 
              "road_numbe": "1.000000000000000", 
              "road_one_w": null, 
              "road_surfa": "metalled", 
              "road_name_": "1030000046167", 
              "a1084": null, 
              "road_highw": null, 
              "road_statu": null, 
              "modified_d": null
            }, 
            "geometries": [
              /* A multigeometry object will have >1 item in the geometries array */
              /* Each entry is an encoded polyline: [points, levels] */
              [ "dh|mFk_tn`@No@~@wAzDeCLVEVaDvDcA`@m@B",  "B??@????B" ]
            ]
          }
        ]
      }
    }, 
    /* these parameters are needed for correctly decoding the encoded geometries */
    "polyNumLevels": 4, 
    "polyZoomFactor": 32
  }
}

Usage notes

• the response time should be fairly quick (<75ms), although there's latency on top of that.
• adding more layers and results, and returning geometries with the response will slow it down somewhat.
• 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:

• Faster responses
• Queries and responses in other projections
• What else would you like to see? Start a discussion