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.