RU:Imagery Offset Database/API

Сервер API сейчас находится по адресу http://offsets.textual.ru/. Поддерживает его User:Zverik, способы связи указаны на его вики-странице.

Форматы и сообщения

По умолчанию ответы возвращаются в формате XML, но можно указать ключ format=json с понятным результатом. На сервере включен CORS, однако можно использовать JSONP, указав название функции в ключе jsonp.

Сообщения об ошибках выглядят так:

<?xml version="1.0" encoding="utf-8" ?>
<imagery-offsets>
  <error>Произошло непоправимое.</error>
</imagery-offsets>

Или так:

{ "error" : "Произошло непоправимое." }

В сообщениях об успешном завершении операций вместо «error» используется тег/ключ «message».

Идентификатор подложки

Значение строки Imagery строится из адреса подложки тремя способами, в зависимости от типа подложки. Эта схема проверена на списке от основных редакторов. Референсный код — в плагине для JOSM. Сначала требуется определить тип подложки. Шаги для разных типов (кроме словаря), однако, не различаются, поскольку затрагивают разные части адреса.

TMS

Протокол и изменяемые части адреса вида /{zoom}, /{y}.jpg (да, вместе с расширением и слэшем) отбрасываются:

http://tile.openstreetmap.org/{zoom}/{x}/{y}.png
-> tile.openstreetmap.org
http://mapproxy.sosm.ch:8080/tiles/sogis2007/EPSG900913/$z/$x/$y.png?origin=nw
-> mapproxy.sosm.ch:8080/tiles/sogis2007/EPSG900913?origin=nw

Все изменяемые фрагменты адреса отбрасываются. Если они оставляют «..» или точку в начале, лишнюю точку нужно удалить.

http://oatile{switch:1,2,3,4}.mqcdn.com/tiles/1.0.0/sat/{zoom}/{x}/{y}.png
-> oatile.mqcdn.com/tiles/1.0.0/sat
http://{switch:a,b,c,d}.tile.osm-tools.org/osm_then/{zoom}/{x}/{y}.png
-> tile.osm-tools.org/osm_then

Все параметры адреса, в которых присутствуют изменяемые части, отбрасываются. Остальные параметры сортируются в алфавитном порядке, ключи переводятся в нижний регистр:

http://maps.kosmosnimki.ru/TileService.ashx?Request=gettile&layerName=19195FD1&apikey=FAIL&crs=epsg:3857&z={zoom}&x={x}&y={y}
-> maps.kosmosnimki.ru/TileService.ashx?apikey=FAIL&crs=epsg:3857&layername=19195FD1&request=gettile

Пример работы алгоритма для подложки Bing с quadtiles, но сама подложка должна идентифицироваться по ключу «bing» (см. ниже). Обращаю внимание, что в этом случае параметры остаются, поскольку неизвестно, влияют ли они на получаемые тайлы в общем случае.

http://ecn.t${0|1|2|3}.tiles.virtualearth.net/tiles/a$quadkey.jpeg?g=587&mkt=en-gb&n=z
-> ecn.t.tiles.virtualearth.net/tiles/a?g=587&mkt=en-gb&n=z

WMS

Протокол отбрасывается, также удаляются параметры srs (для базы он подразумевается равным EPSG:4326), width, height, bbox, service, request, version, format, styles, transparent. Остальные параметры пишутся в нижнем регистре по алфавиту:

http://wms.craig.fr/osm?service=wms&request=getmap&version=1.1.1&layers=auvergne&format=image/jpeg
&SRS={proj}&WIDTH={width}&HEIGHT={height}&BBOX={bbox}
-> wms.craig.fr/osm?layers=auvergne

http://sit.provincia.lodi.it/mapserver/mapserv.exe?map=ortofoto_wgs84.map&SERVICE=WMS&VERSION=1.1.1
&REQUEST=GetMap&SRS={proj}&LAYERS=Terraitaly%20Ortofoto%202007&STYLES=%2C%2C&FORMAT=image/png&TRANSPARENT=TRUE
&WIDTH={width}&HEIGHT={height}&BBOX={bbox}
-> sit.provincia.lodi.it/mapserver/mapserv.exe?layers=Terraitaly%20Ortofoto%202007&map=ortofoto_wgs84.map

Словарь

Некоторые распространённые подложки идентифицируются по ключевым словам. Такие слова могут содержать только символы [a-z0-9_], и обязательно должны документироваться на этой вики-странице.

Получение списка смещений

/get?lat=...&lon=...&imagery=...&radius=...

Обязательны только координаты: широта lat и долгота lon в градусах в СК WGS-84 (EPSG:4326). Radius означает радиус поиска в километрах: по умолчанию 10, максимум — 40 (зависит от настроек сервера). Код подложки в imagery рассчитывается по алгоритму, описанному в предыдущем разделе.

Пример возвращаемого списка:

<?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">
    <author>fserges</author>
    <description>Центр Петербурга: все острова и от Невы до Обводного канала</description>
    <date>2012-11-03</date>
    <imagery minzoom="10" maxzoom="20">bing</imagery>
    <imagery-position lat="35.1674" lon="59.93032" />
  </offset>
  <calibration id="999" lat="35.01923" lon="60.12341" deprecated="yes">
    <author>Zverik</author>
    <description>Перекрёсток с разметкой, вокруг равнина, смещение годится километров на 20-30</description>
    <date>2012-02-21</date>
    <deprecated>
      <author>Dinamik</author>
      <reason>Перекрёстка больше нет</reason>
      <date>2013-03-19</date>
    </deprecated>
    <geometry>
      <node lat="35.01923" lon="60.12341" />
    </geometry>
  </calibration>
</imagery-offsets>

Тот же список в JSON:

[
  {
    "type" : "meta",
    "timestamp" : "2013-03-21T18:21:33+0400"
  },
  {
    "type" : "offset",
    "id" : 57,
    "lat" : 35.168,
    "lon" : 59.93,
    "author" : "fserges",
    "description" : "Центр Петербурга: все острова и от Невы до Обводного канала",
    "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" : "Перекрёсток с разметкой, вокруг равнина, смещение годится километров на 20-30",
    "date" : "2012-02-21",
    "deprecated" : {
      "author" : "Dinamik",
      "reason" : "Перекрёстка больше нет",
      "date" : "2013-03-19"
    },
    "geometry" : [[60.12341, 35.01923]]
  }
]

Регистрация сдвига

/store?lat=...&lon=...&author=...&description=...&imagery=...&imlat=...&imlon=...

Параметры определяются следующим образом:

Параметр	Значение	Описание
lat, lon	десятичные градусы	Координаты точки, в которой вычислялось смещение подложки.
author	строка в utf-8 до 100 знаков	Пользователь, загружающий смещение.
description	строка в utf-8 от 3 до 200 знаков	Описание области и условий, для которых пригодно вычисленное смещение подложки.
imagery	строка в utf-8	Идентификатор подложки.
imlat, imlon	десятичные градусы	Координаты изображения точки (lat, lon) на подложке.

Регистрация калибровочной геометрии

/store?author=...&description=...&geometry=...

В параметре geometry задаётся список координат геометрии в виде lon1+lat1,lon2+lat2,lon3+lat3,lon1+lat1. Координаты пишутся через пробел (кодируемый в '+'), разделяются запятой. Для замкнутой линии последняя координата равна первой. Для точки координата только одна. Заметьте, что нет параметров lat и lon: они вычисляются как среднее арифметическое переданных координат.

Удаление смещения

/deprecate?id=...&author=...&reason=...

Идентификаторы содержатся в выдаваемых запросом /get смещениях, требования к ключу reason такие же, как к description запроса на добавление смещения.

Оповещение модераторов

/report?id=...&reason=...

Через пометку смещения можно привлечь к нему внимание модераторов. Обычные удаления -- дело пользователей, но если кто-то налепил тысячу левых записей, модераторам с ними справиться проще и быстрее.

Выгрузки

База данных целиком архивируется раз в шесть часов в каталог http://offsets.textual.ru/download/. Последние версии файлов имеют постоянный адрес: XML, JSON. Файлы сжаты программой gzip. В браузерах, поддерживающих этот формат сжатия, для получения JSON можно пользоваться ссылкой http://offsets.textual.ru/all?format=json.