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.
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 login into your Koordinates ID and click on your name in the top menu. Then, select APIs and Web Services from the options provided and request 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
Click Services
Once we’ve navigated the data, we need click on Services, which will list all available APIs and Web Services. Under Query API, Koordinates have automatically generated a default API, which we can edit to get the answer to our question.
This default API looks like this.
https://koordinates.com/services/query/v1/vector.json?key=KEY&layer=3936&x=174.50021005517078&y=-41.316928049910814&max_results=3&radius=10000&geometry=true&with_field_names=true
Note that, if you’re logged in and have an API key, KEY will be automatically replaced with your key.
If you’d like, you can cut and paste this into a notepad to edit.
3
Edit the default parameters
Now, all we need to do is edit some of the default parameters
First, we’ll need to add the coordinates of a point in Palmerston North. To do this, we can simply cut and paste the coordinates into the API URL. If we don’t know the coordinates of Palmerston North, though, we can simply zoom to Palmerston North in the Koordinates.com map, and Koordinates will update the API automatically (you don’t even need to refresh the browser).
Once we’ve done that, we’re going to delete everything from ‘geometry’ on, partly because we’re not interested in those parameters, and partly because it makes the URL easier to read.
Because we’re interested in results within 100 kilometres, we’ll add an extra ‘0’ to the default radius. And because we want as many results as possible, we’ll up the maximum results from 3 to 30. That gives us our API URL.
4
Paste the URL into your browser
Now, all we need to do now is paste the resulting URL into our browser.
And that gives us our result: there are ten Department of Conservation campgrounds within a 100k radius of Palmerston North! The results are listed in order of proximity, so I also know which campgrounds are closest to Palmy (should I 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
Click Services
As with the Department of Conservation Campsites data, all we need to do is click Services to find our default URL. Because we are dealing with raster data, we have fewer parameters to deal with.
https://koordinates.com/services/query/v1/raster.json?key=KEY&layer=8678&x=175.60821450000003&y=-40.3523065
Note that, if you’re logged in and have an API key, KEY will be automatically replaced with your key.
3
Edit the default parameters
The only part of the URL we need to edit is the coordinates. Again, rather than cut and paste the coordinates into the URL, we are going to zoom into the area of the map we are interested in querying.
Because the cook strait is quite large, we’ll let Koordinates decide on the location by typing ‘Cook Strait’ into the location search bar in the preview map.
This gives us our API URL:
https://koordinates.com/services/query/v1/raster.json?key=KEY&layer=8678&x=174.3121264&y=-41.340991
https://koordinates.com/services/query/v1/raster.json?key=KEY&layer=8678&x=174.3121264&y=-41.340991
4
Paste the URL into your browser
Again, all we need to do now is paste the URL into a browser.
This gives us our answer: the depth of the Cook Strait at that particular point is 99 metres. Or, more precisely, 99.53348541259766 metres.