Taginfo/API

Taginfo has an API that lets you access the contents of its databases in several ways. The API is used internally for the web user interface and can also be used by anybody who wants to integrate taginfo data into their websites or applications.

The API is intended for the use of the OpenStreetMap community. Do not use it for other services. If you are not sure, ask on the mailing list (see below).

Always use a sensible User-agent header with enough information that we can contact you if there is a problem.

The server running the taginfo API does not have unlimited resources. Please use the API responsibly. Do not create huge amounts of requests to get the whole database or large chunks of it, instead use the database downloads provided. If you are using the API and you find it is slow, you are probably overusing it.

If you are using the taginfo API it is recommended that you join the taginfo-dev mailing list. Updates to the API will be announced there and this is also the right place for your questions.

Basics

The API is a RESTful HTTP API. All requests are done through URLs beginning with https://taginfo.openstreetmap.org/api/VERSION . API Version 4 is current.

All API calls are read-only and use the HTTP GET request, all parameters are given in the URL as usual.

All API results are in JSON format (except a few calls which return a PNG). You must ignore unknown names (keys) in JSON objects, new versions of the API might add new names to any object without incrementing the version number.

Paging

Many API calls return their data "page by page", so you can get, say, the first 20 results in one request, then the next 20 and so on. You can decide how many results you want and which "page" or you can just get everything at once.

If you want paging add the parameters page and rp (results per page) to the URL. The first page has the number 1. So the URL will look like

https://taginfo.openstreetmap.org/api/VERSION/some/thing?rp=20&page=1&foo=bar

The results of the API call will look like this:

{
  "total": 587,   // the total number of results
  "page":  7,     // the page number (same as in your request)
  "rp":    20,    // the number of results per page (same as in your request)
  "url":   "https://taginfo.openstreetmap.org/api..."  // the full URL used to get this result
  "data":  [...]  // the data
}

The data array will contain the actual results from item rp * (page-1) to rp * page - 1.

If you do not want paging, don't add the page and rp parameters, in the result those fields will then be 0.

Sorting

Many API calls support sorting of the results. To get something else than the default sort, you can add the sortname and sortorder parameters to the URL. Each API request has different options for sortname. The sort order can be either asc for ascending or desc for descending.

Filters

Some API calls have a special filter parameter that allows you to filter the results. You can use multiple filters like this: filter=FILTER1,FILTER2.

See the "Filter" descriptions in the API Documentation for information about which calls take which filters.

Example Code

The simple tapi tool (https://github.com/joto/taginfo/blob/master/examples/tapi) can be used to create API requests and might help you in developing your own API access code.

API Calls

Generally there is an API call for each table in the web user interface (that's because those tables are populated from the API calls). Sometimes the API calls return more data fields than are shown in the user interface.

See https://taginfo.openstreetmap.org/taginfo/apidoc for a list of API calls.

XSS Issues

Please be aware that OSM tag keys and values can contain any valid UTF-8 character, so can wiki pages. When you use the taginfo API there is always a chance that it returns data containing special characters. Please make sure in your application that those characters are handled properly.

Pretty JSON

You can add the parameter format=json_pretty to get pretty-printed JSON output with spaces and newlines. The default is to pack the JSON as tightly as possible.

CORS and JSONP

Taginfo supports Cross-Origin Resource Sharing (CORS) by setting the header Access-Control-Allow-Origin: * on all API call results. This is the preferred method of using the taginfo API from other web pages.

Taginfo also supports the older JSONP technique. You can add the parameter callback to any API call returning JSON and it will return the result packed inside a function call to the callback parameter.

Example: ...&callback=foo

will return foo(...some json...).