RU:Imagery Offset Database/API

From OpenStreetMap Wiki
Jump to: navigation, search
Доступные языки — Imagery Offset Database/API
Afrikaans Alemannisch aragonés asturianu azərbaycanca Bahasa Indonesia Bahasa Melayu Bân-lâm-gú Basa Jawa Baso Minangkabau bosanski brezhoneg català čeština dansk Deutsch eesti English español Esperanto estremeñu euskara français Frysk Gaeilge Gàidhlig galego Hausa hrvatski Igbo interlingua Interlingue isiXhosa isiZulu íslenska italiano Kiswahili Kreyòl ayisyen kréyòl gwadloupéyen kurdî latviešu Lëtzebuergesch lietuvių magyar Malagasy Malti Nederlands Nedersaksies norsk norsk nynorsk occitan Oromoo oʻzbekcha/ўзбекча Plattdüütsch polski português română shqip slovenčina slovenščina Soomaaliga suomi svenska Tiếng Việt Türkçe Vahcuengh vèneto Wolof Yorùbá Zazaki српски / srpski беларуская български қазақша македонски монгол русский тоҷикӣ українська Ελληνικά Հայերեն ქართული नेपाली मराठी हिन्दी অসমীয়া বাংলা ਪੰਜਾਬੀ ગુજરાતી ଓଡ଼ିଆ தமிழ் తెలుగు ಕನ್ನಡ മലയാളം සිංහල ไทย မြန်မာဘာသာ ລາວ ភាសាខ្មែរ ⵜⴰⵎⴰⵣⵉⵖⵜ አማርኛ 한국어 日本語 中文(简体)‎ 吴语 粵語 中文(繁體)‎ ייִדיש עברית اردو العربية پښتو سنڌي فارسی ދިވެހިބަސް

Сервер 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.