Imagery Offset Database/API

From OpenStreetMap Wiki
Jump to navigation Jump to search

The Imagery Offset Database API server is located at It is managed by User:Zverik, and his contacts are listed on his wiki page.

Formats and messages

By default, responses are in XML, but you can add a parameter format=json to get data in JSON. CORS is enabled, but you can use JSONP by specifying a function name in the jsonp parameter.

Error messages look like this:

<?xml version="1.0" encoding="utf-8" ?>
  <error>The unthinkable happened.</error>

Or like this:

{ "error" : "The unthinkable happened." }

Successful operations use the "message" key in their responses instead of "error".

Imagery identifier

An imagery parameter value is constructed in three ways, depending on imagery type. This algorithm has been tested on imagery lists used by major editors. See reference implementation in JOSM plugin source. Firstly you have to determine imagery type. TMS steps apply to WMS layers, but not vice-versa.


Protocol and variable URL parts like /{zoom}, /{y}.jpg (yes, along with an extension and a forward slash) are removed:{zoom}/{x}/{y}.png

All variable URL parts are removed. If they leave ".." or a dot as a first characted, those should be also removed.


All query parameters which have variable parts are removed. Other parameters are sorted alphabetically, keys coverted to lower case:{zoom}&x={x}&y={y}

An example of processing Bing imagery quadtiles URL. Note that this imagery should be identified by a keyword "bing" (see #Dictionary). Parameters are not removed, because there is no way of knowing if they affect the tiles.



Protocol is removed, also removed are srs (it is assumed to be EPSG:4326 for the database), width, height, bbox, service, request, version, format, styles, transparent. Other parameters are included in lower case alphabetically:


Some widespread imagery, e.g. "Bing", is identified by keywords. Such words can include only symbols in [a-z0-9_] and should be documented on this wiki page.

Getting an offsets list


Only coordinates are required: latitude (lat) and longitude (lon) in decimal degrees, WGS-84 (EPSG:4326) projection. Radius specified the search radius in kilometers: 10 by default, 40 maximum (depends on server settings). Imagery parameter is described above.

An example of a response:

<?xml version="1.0" encoding="utf-8" ?>
<imagery-offsets timestamp="2013-03-21T18:21:33+0400">
  <offset id="57" lat="35.168" lon="59.93">
    <description>Saint-Petersburg city centre: every island, from Neva River to Obvodny Channel</description>
    <imagery minzoom="10" maxzoom="20">bing</imagery>
    <imagery-position lat="35.1674" lon="59.93032" />
  <calibration id="999" lat="35.01923" lon="60.12341" deprecated="yes">
    <description>An intersection with markings, flat land around, the offset works for 20-30 km</description>
      <reason>No intersection anymore</reason>
      <node lat="35.01923" lon="60.12341" />

The same in JSON:

    "type" : "meta",
    "timestamp" : "2013-03-21T18:21:33+0400"
    "type" : "offset",
    "id" : 57,
    "lat" : 35.168,
    "lon" : 59.93,
    "author" : "fserges",
    "description" : "Saint-Petersburg city centre: every island, from Neva River to Obvodny Channel",
    "date" : "2012-11-03",
    "imagery" : "bing",
    "min-zoom" : 10,
    "max-zoom" : 20,
    "imlat" : 35.1674,
    "imlon" : 59.93032
    "type" : "calibration",
    "id" : 999,
    "lat" : 35.01923,
    "lon" : 60.12341,
    "author" : "Zverik",
    "description" : "An intersection with markings, flat land around, the offset works for 20-30 km",
    "date" : "2012-02-21",
    "deprecated" : {
      "author" : "Dinamik",
      "reason" : "No intersection anymore",
      "date" : "2013-03-19"
    "geometry" : [[60.12341, 35.01923]]

Registering an imagery offset


Parameters as defined as follows:

Parameter Value Description
lat, lon decimal degrees Point coordinates, for which the imagery offset was calculated.
author string in utf-8, up to 100 characters OSM nickname of a user uploading the offset.
description string in utf-8, 3 to 100 characters Description of an area and conditions for using this offset.
imagery string in utf-8 Imagery identifier.
imlat, imlon decimal degrees Location of a (lat, lon) point on the imagery.

Registering a calibration geometry


Geometry parameter contains a comma-separated list of geometry nodes: lon1+lat1,lon2+lat2,lon3+lat3,lon1+lat1. Longitude and latitude are separated by a space (url-encoded into "+"). For a closed area the last node should be equal to the first one. For a point there's only one node. Note that there are no lat and lon parameters in the query string: those are calculated as an arithmetic mean of all coordinates.

Deprecating an offset


Offset identifiers are included in /get responses, reason parameter has the same restrictions as the description one for registering an offset.

Notifying moderators


By reporting an offset it's flagged for moderators. Usual deletions are users' business, but if someone added a thousand fake offsets, moderators can easily fix it.


The whole database is archived every six hours into directory. Latest extracts have the fixed address: XML, JSON. All files are gzipped. In browsers that support gzip transfer encoding, URL can be used in scripts to download data in JSON format.