The Koordinates Query API for non-technical users

Koordinates offers an API that allows users to query data published on Koordinates powered sites. While APIs can be technical, it’s possible for non-technical users to query data using the Koordinates API—without leaving their browser or knowing anything about code.

In this guide, we’re going to cover some basic information about the Query API, and then run through some interesting examples for vector and raster data. Afterwards, we recommend you have a play with some data on your own Koordinates powered site.

Introducing the Koordinates Query API

The Koordinates Query API is just that: an API that allows you to easily query data published on a Koordinates powered site.

For our purposes, you can think of the API as a specific kind of URL. When this URL is pasted into your browser, it will provide you with answers to a specific location-related question.

For example, you might wish to ask ‘where is the nearest doctor to my place of work?’ Or, ‘how many schools are in a ten kilometre radius from my house?’ As long as the data is published on a Koordinates-powered site, the Query API can answer these questions—without requiring you to trawl through a data table.

Setting the parameters for your query

As you might expect, the response you get will depend on how your query is framed. The Koordinates API gives you several options, known as API parameters. You can find these parameters listed below.

• Layer number. All data published on a Koordinates powered site has its own unique layer number.
• The x and y coordinates of the location you are interested in querying.
• Maximum results. You can choose to receive between 1 and 100 results. Results are sorted by distance from the query point, so closest results will always be returned first
• Radius. The distance in meters around your chosen location that the API will query.

For our purposes, we’re only going to use these parameters. Once you’re comfortable with these, though, you also have the options of using three more parameters.

Geometry. Choose to receive the geometry as well as the attributes —i.e. the data—associated with your chosen location.

Field names. Choose to receive a list of all the fields in the data.

Callback. Choose a JavaScript function name to wrap the results in (JSONP), for use in web pages.

The API key

Before you can use the Query API, you will need to get an API key. To get a key, all you need to do is log in and select your avatar (your profile picture or initials) at the top of the page to open your user menu. Then, select API Keys from the options provided and create a key.

Your key is a long string of characters that you can paste into your API URL. The key is used by Koordinates to rate-limit the API according to reasonable use—but this is not something most users will need to think about.

A note about code

We’re going to set our API to get results in JSON, which can be easily viewed in the browser. Don’t worry—you won’t need to know anything about JSON to understand the results.
\

Example #1: How many campgrounds are there within 100kms of Palmerston North?

1. Find the data you need

   The first step to answering this question is finding the relevant data on a Koordinates powered site. Happily, New Zealand’s Department of Conservation have published their campground data on Koordinates.com: https://koordinates.com/layer/3936-department-of-conservation-campgrounds/

2. Select Services

   Once you’ve opened the data, select Services, which lists all available APIs and web services. Under Spatial Query API, Koordinates has automatically generated a default API URL, which you can edit to get the answer to your question.

   This default API URL looks like this:

   https://koordinates.com/services/query/v1/vector.json?key=[api_token]&layer=3936&x=[x]&y=[y]&max_results=3&radius=10000&geometry=true&with_field_names=true

   If you’re logged in, you can choose one of your API keys, and [api_token] will be replaced with your key.

   If you’d like, you can copy and paste this into a text editor to edit.

3. Edit the default parameters

   Now, all you need to do is edit some of the default parameters.

   First, replace [x] and [y] with the longitude and latitude of a point in Palmerston North, such as x=175.6082 and y=-40.3523.

   Next, delete everything from ‘geometry’ on, partly because you’re not interested in those parameters, and partly because it makes the URL easier to read.

   Because you’re interested in results within 100 kilometres, add an extra ‘0’ to the default radius. And because you want as many results as possible, increase the maximum results from 3 to 30. That gives you your API URL:

   https://koordinates.com/services/query/v1/vector.json?key=YOUR_API_KEY&layer=3936&x=175.6082&y=-40.3523&max_results=30&radius=100000

4. Paste the URL into your browser

   Now, all you need to do is paste the resulting URL into your browser.

   That gives you your result: a list of the Department of Conservation campgrounds within 100 kilometres of Palmerston North. The results are listed in order of proximity, so you also know which campgrounds are closest to Palmy (should you decide to visit).

Example #2: How deep is the middle of the Cook Strait?

For our next example, we’re going to query a raster dataset, which uses a different API - but we’re going to follow the exact same process.

1. Find the data you need

   Bathymetry data—that is, data about the depth of underwater lake or ocean floors—has been published by NIWA on Koordinates.com: https://koordinates.com/layer/8678-niwa-new-zealand-bathymetic-grid-2016/

2. Select Services

   As with the Department of Conservation campgrounds data, all you need to do is select Services to find the default URL. Because you are dealing with raster data, there are fewer parameters to deal with.

   https://koordinates.com/services/query/v1/raster.json?key=[api_token]&layer=8678&x=[x]&y=[y]

   If you’re logged in, you can choose one of your API keys, and [api_token] will be replaced with your key.

3. Edit the default parameters

   The only part of the URL you need to edit is the coordinates. Replace [x] and [y] with the longitude and latitude of a point in the middle of Cook Strait, such as x=174.3121264 and y=-41.340991.

   This gives you your API URL:

   https://koordinates.com/services/query/v1/raster.json?key=YOUR_API_KEY&layer=8678&x=174.3121264&y=-41.340991

4. Paste the URL into your browser

   Again, all you need to do now is paste the URL into a browser.

   This gives you your answer: the value at that point is -99.53348541259766, so the depth of Cook Strait at that particular point is about 99.5 metres.