RU:Xapi

This page describes a historic artifact in the history of OpenStreetMap. It does not reflect the current situation, but instead documents the historical concepts, issues, or ideas.

---

Эта статья отмечена как русскоязычная версия статьи на другом языке, но отличается от неё по содержанию (обычно основная статья на английском или немецком языках). Пожалуйста, обновите перевод если считаете возможным.

Расширенный API OSM или XAPI (eXtended API, произносится как "заппи") представляет собой протокол API только для чтения на основе модифицированной версии OSM main API, которое обеспечивает расширенные возможности поиска и запросов. Xapi предлагает поисковые запросы, для некоторых простых случаев, чтобы снизить нагрузку на OSM main API. В частности xapi переопределяет стандартный запрос карты, так что она может быть выполнена намного быстрее. Xapi использует REST интерфейс с X-path добавкой. Более сложные запросы могут быть обработаны другими read-only зеркалами, такими как Overpass API, которые поддерживают более мощный но более сложный синтаксис.

Xapi подходит когда нужно иметь дело с элементами текущей версии. Xapi не работает с историей и удаленными элементами. Исходная БД является зеркалом основной БД OSM и обновляется через ежеминутный diff дамп. Данные обновляются, как правило, не более чем через 10 минут после основной БД.

Все ответы имеют тот же формат, что и стандартный протокол, но с добавлением некоторых пространств имен и расширений. Tag запросы используют X-path подобный синтаксис для указания условий поиска. Видимый атрибут исключен из ответа, так как всегда имеет значение true

Реализация

Есть несколько code/database идей для реализации xapi, а так же для деплоя. Они перечислены ниже. Так же вы можете увидеть различные варианты базовых URL на XAPI URL Builder (source code).

jXAPI

В января 2011 года Ian Dees создал новую Java версию бэкенда XAPI на postGIS. Смотрите Дневник пользователя iandees. Несколько человек в настоящее время использует это на разных серверах:

• http://jxapi.openstreetmap.org/xapi/api/0.6/... JXAPI by Ian Dees (status: (status: No data returned ?)
• http://open.mapquestapi.com/xapi/api/0.6/... provided by Open Mapquest (status: Out of date: Dataset is from march 2012, stats page). (See MapQuest XAPI service)
• http://jxapi.osm.rambler.ru/xapi/api/0.6/... provided by Rambler (status: Error on all requests, stats page). relations not fully supported

Note that bbox queries have a maximum of 10 square degrees.

Paul's Blog|установка jXAPI содержит некоторую информацию о настройке PostgreSQL для большого набора данных и ускорения начальной загрузки.

Overpass API

Overpass API теперь имеет слой XAPI совместимости. Он поддерживает большинство XAPI запросов, а также свой ​​собственный, более расширенный язык запросов.

• Known public instances :

• http://overpass.osm.rambler.ru/cgi/xapi_meta?... More info at Overpass API (status: Running normally)
• http://www.overpass-api.de/api/xapi_meta?... More info at Overpass API (status: Running normally)
• http://api.openstreetmap.fr/xapi?... Provided by OpenStreetMap_France more info at Servers/api.openstreetmap.fr (status: Running normally)

jXAPI

Xappy.js - переписанная OSM XAPI в node.js (JavaScript). В настоящее время использует Postgres с расширением PostGIS, с опцией реализации другого бэкенда.

Оригинальное XAPI

Оригинальное XAPI было создано User:80n при помощи GT.M. Было несколько XAPI сервисов, работающих на нескольких разных серверах. Каждый сервер мог быть доступен напрямую или через редирект, который использовался чтобы направить запрос к подходящему серверу.

Query Map

Запрос карты идентичен запросу карты основного API и возвращает:

• Все узлы, находящиеся внутри ограничительной рамки и их зависимости.

GET /api/0.6/map?bbox=left,bottom,right,top

где:

• left - долгота, левая(западная) сторона ограничительной рамки.
• bottom - широта, нижняя(южная) сторона ограничительной рамки.
• right - долгота, правая(восточная) сторона ограничительной рамки.
• top - широта, верхняя(северная) сторона ограничительной рамки.

Пример

http://www.informationfreeway.org/api/0.6/map?bbox=11.54,48.14,11.543,48.145

Примечание

• В отличие от основного API, которое ограничивает запросы до 0.25 градусов в квадрате, XAPI позволяет делать запросы вплоть до 10.000.000 элементов (это по-прежнему меньше трети Калифорнии или 100 градусов в квадрате).
• Запрос карты функционально идентичен с запросом Tag запросом

/api/0.6/*[bbox=''left,bottom,right,top'']

• Там не должно быть пустых значений, определяющих ограничительную рамку.

Query Tags

XAPI реализует запросы для всех трех видов элементов: узлов, путей и отношений.

Узлы

Запрос узлов вернет XML-документ, содержащий узлы и связанные с ними теги. URL для запроса узла имеет следующий вид:

http://www.informationfreeway.org/api/0.6/node[...]

Вернет стандартный ответ OSM API, содержащий узлы и теги. Например:

  <?xml version='1.0' standalone='no'?>
  <osm version='0.6' generator='xapi: OSM Extended API' 
   xmlns:xapi='http://www.informationfreeway.org/xapi/0.6'
   xapi:uri='/api/0.6/node[amenity=hospital]'
   xapi:planetDate='200803150826' 
   xapi:copyright='2008 OpenStreetMap contributors' 
   xapi:instance='zappy2'>
    <node id='672180' lat='48.2111685091189' lon='16.3035366605548' timestamp='2006-09-11T16:28:25+01:00' version='1' changeset='10968'>
      <tag  k='amenity' v='hospital'/>
      <tag  k='name' v='Wilhelminenspital'/>
    </node>
    <node id='3596186' lat='53.4633699598014' lon='-2.22667910006381' timestamp='2007-06-21T17:10:58+01:00' version='2' changeset='2213'>
      <tag  k='amenity' v='hospital'/>
      <tag  k='name' v='Manchester Royal Infirmary'/>
    </node>
    ...
  </osm>

Пути

URL для запроса пути имеет следующий вид:

http://www.informationfreeway.org/api/0.6/way[...]

Вернет XML-документ, содержащий пути, соответствующие условиям поиска. Так же возвращаются зависимые узлы. Пример ответа выглядит следующим образом:

  <?xml version='1.0' standalone='no'?>
  <osm version='0.6' generator='xapi: OSM Extended API' 
   xmlns:xapi='http://www.informationfreeway.org/xapi/0.6'
   xapi:uri='/api/0.6/way[landuse=residential]'
   xapi:planetDate='200803150826' 
   xapi:copyright='2008 OpenStreetMap contributors' 
   xapi:instance='zappy2'>
    <node id='218963' lat='52.5611324692581' lon='-1.79024812573334' timestamp='2006-03-22T16:47:48+00:00' version='1' changeset='2211'>
    </node>
    <node id='331193' lat='53.7091237972264' lon='-1.50282510180841' timestamp='2007-03-31T00:09:22+01:00' version='1' changeset='2211'>
      <tag  k='highway' v='traffic_signals'/>
      <tag  k='source' v='Yahoo'/>
    </node>
    ...
    <way id='4958218' timestamp='2007-07-25T01:55:35+01:00' version='3' changeset='2211'>
      <nd ref='218963'/>
      <nd ref='331193'/>
      ...
      <tag  k='landuse' v='residential'/>
      <tag  k='source' v='landsat'/>
    </way>
  </osm>

Отношения

URL для запроса отношения имеет следующий вид:

http://www.informationfreeway.org/api/0.6/relation[...]

Вернет XML-документ, содержащий отношения, соответствующие условиям поиска. Так же возвращаются зависимые пути и узлы. Пример ответа выглядит следующим образом:

  <?xml version='1.0' standalone='no'?>
  <osm version='0.6' generator='xapi: OSM Extended API' 
   xmlns:xapi='http://www.informationfreeway.org/xapi/0.6'
   xapi:uri='/api/0.6/way[landuse=residential]'
   xapi:planetDate='200803150826' 
   xapi:copyright='2008 OpenStreetMap contributors' 
   xapi:instance='zappy2'>
    <node ...
    <way ...
    <relation id='2670' timestamp='2007-10-25T03:05:34Z' version='32' changeset='2211'>
      <member type='way' ref='3992472' role=''/>
      <member type='way' ref='3992524' role=''/>
      <member type='way' ref='4253050' role=''/>
      <member type='way' ref='4253053' role=''/>
      <member type='way' ref='4266813' role=''/>
      <member type='way' ref='10285106' role=''/>
      <tag k='name' v='Fonnereau Way'/>
      <tag k='network' v='Ipswich footpaths'/>
      <tag k='type' v='route'/>
    </relation>    
  </osm>

Все элементы

Все элементы (узлы, пути и отношения), подходящие под определенный фильтр могут быть запрошены с помощью следующего URL:

http://www.informationfreeway.org/api/0.6/*[...]

Вернет все элементы, подходящие под условия фильтра, а так же зависимости для всех элементов. Пример ответа:

  <?xml version='1.0' standalone='no'?>
  <osm version='0.6' generator='xapi: OSM Extended API' 
   xmlns:xapi='http://www.informationfreeway.org/xapi/0.6'
   xapi:uri='/api/0.6/*[amenity=hotel]'
   xapi:planetDate='200803150826' 
   xapi:copyright='2008 OpenStreetMap contributors' 
   xapi:instance='zappy2'>
    <node id='218963' lat='52.5611324692581' lon='-1.79024812573334' timestamp='2006-03-22T16:47:48+00:00' version='1' changeset='2211'>
    </node>
    <node id='331193' lat='53.7091237972264' lon='-1.50282510180841' timestamp='2007-03-31T00:09:22+01:00' version='1' changeset='2211'>
      <tag k='amenity' v='hotel'/>
    </node>
    ... 
    <way id='4958218' timestamp='2007-07-25T01:55:35+01:00' version='1' changeset='2211'>
      <nd ref='218963'/>
      <nd ref='331193'/>
      ...
      <tag k='amenity' v='hotel'/>
      <tag k='building' v='hotel'/>
    </way>
    <relation id='123456' timestamp='2007-10-25T03:05:34Z' version='32' changeset='2211'>
      <member type='node' ref='331193' role=''/>
      <member type='node' ref='331194' role=''/>
      ...
      <tag k='amenity' v='hotel'/>
      <tag k='operator' v='Premier Inns'/>
      <tag k='type' v='operators'/>
    </relation>    
  </osm>

Предикаты

Каждый запрос API может заканчиваться предикатом, который определяет какие элементы нужно выбрать. Например: [amenity=hospital] будут выбраны все элементы, у которых тег amenity имеет значение hospital. Полный URL, чтобы выбрать все узлы, помеченные как больницы выглядит следующим образом:

http://www.informationfreeway.org/api/0.6/node[amenity=hospital]

Запрос может содержать несколько предикатов, каждый из которых ограничивает выборку предыдущего (в настоящее время ограничивается одним предикатом тега и одним bbox предикатом, хотя jXAPI и Overpass поддерживают несколько предикатов тегов. Например:

http://www.informationfreeway.org/api/0.6/node[amenity=hospital][bbox=-6,50,2,61]

Этот запрос вернет все узлы, у которых тег amenity имеет значение hospital и входят в ограничительную рамку, которая описывает всю территорию Англии, Уэльса и Шотландии.

Предикаты тегов

Предикат выбора должен иметь вид [ключ=значение]. Например node[amenity=hospital] будет соответствовать любой узел, имеющий ключ amenity со значением hospital, то есть:

<tag k="amenity" v="hospital"/>

.

Оператор "|" может быть использован для выбора нескольких значений, Например выделим все основные дороги:

• way[highway=motorway|motorway_link|trunk|primary]

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

• node[amenity|leisure=golf_course]

Можно воспользоваться маской, но только для значения (не для ключа):

• way[construction=*]
• way[highway=*]

Примечание: URL должен быть в кодировке UTF-8. Кодируется в случае не-ASCII символов.

Предикаты ограничительной рамки

[bbox=left,bottom,right,top] устанавливает ограничительную рамку, которая используется чтобы в результирующий документ были включены только элементы внутри рамки.

В отличие от стандартного OSM API, предикат ограничительной рамки не ограничен в размерах. Если он используется без тегов предиката, то размеры будут ограничены 100 градусами в квадрате.

Если предикат ограничительной рамки не задан, то по умолчанию это вся планета, что эквивалентно [bbox=-180,-90,180,90].

Предикаты дочерних элементов

Элементы можно выбирать в зависимости от того, имеют ли они дочерние элементы. Например, пути могут быть выбраны, если не имеют никаких тегов или узлов. Это достигается использованием XPath-подобного тестового элемента. Например реализованы следующие случаи:

• /api/0.6/way[nd] - выбирает пути, имеющие хотя бы 1 узел
• /api/0.6/way[tag] - выбирает пути, имеющие хотя бы 1 тэг
• /api/0.6/way[not(nd)] - выбирает пути, не имеющие узлов
• /api/0.6/way[not(tag)] - выбирает пути, не имеющие тегов
• /api/0.6/node[way] - выбирает узлы, входящие хотя бы в 1 путь
• /api/0.6/node[not(way)] - выбирает узлы, не входящие ни в 1 путь
• /api/0.6/node[not(tag)] - выбирает узлы, не имеющие тегов
• /api/0.6/relation[node] - выбирает отношения, имеющие хотя бы 1 узел
• /api/0.6/relation[way] - выбирает отношения, имеющие хотя бы 1 путь
• /api/0.6/relation[relation] - выбирает отношения, имеющие хотя бы 1 отношение
• /api/0.6/relation[node] - выбирает отношения, не имеющие узлов
• /api/0.6/relation[way] - выбирает отношения, не имеющие тегов
• /api/0.6/relation[relation] - выбирает отношения, не имеющие отношений

Примечание:

1. При использовании wget символы скобок должны быть экранированы, используйте [not\(way\)] вместо [not(way)].
2. В схеме узлов OSM XML на самом деле нет путей как дочерних элементов. Однако есть отношения многие-ко-многим между узлами и путями и так XAPI реализует отношение и включает узлы, которые будут отобраны на основе того, являются ли они членами пути. Конечно на выходе XML такой же как обычный и не включает элемент пути внутри элемент узла.

Экранирование

Если, например, значение тега содержит специальный символ "|" ([route=46|46A]), использующийся для обозначения трассы, то его следует экранировать символом "\" ([route=46\|46A]).

Таки образом могут быть экранированы следующие символы: |[]*/=()\ и пробел.

Пробел в значении тега обычно экранировать не нужно, но если в зависимости от клиента это необходимо то следует использовать URL, где каждый пробельный символ заменен на "%20". Таким образом [route=46 46A] станет [route=46%2046A].

Теги

Основным методом запроса к XAPI является использование сочетания тег/значение в предикате. В дополнение к обычным тегам, которые вы ожидаете найти, следующие атрибуты так же можно запросить с помощью /api/0.6/*[@attribute=value]

• @user - юзернейм последнего пользователя, изменившего элемент
• @uid - id последнего пользователя, изменившего элемент
• @changeset - набор изменений, в котором был изменен элемент

Использование

XAPI может быть использован из любого браузера, однако простой запрос может вернуть несколько мегабайт данных, что может повесить некоторые браузеры. Рекомендуется чтобы такие инструменты как wget или curl записывали ответ сервера в файл. Например, следующая команда использует wget, чтобы выбрать все больницы и сохранить результат в файл с именем data.osm. Обратите внимание что по умолчанию wget имеет тайм аут 15 минут, чего может не хватить для некоторых запросов, так что не забудьте добавить --timeout=0.

wget --timeout=0 http://www.informationfreeway.org/api/0.6/node[amenity=hospital] -O data.osm

Примечание: Если вы используете curl, он будет обрабатывать редиректы автоматически, вам нужно сделать запрос непосредственно к серверу или использовать опцию --location, а так же необходимо использовать опцию --globoff, в противном случае он будет пытаться интерпретировать скобки "[" и "]" как часть командной строки.

curl --location --globoff "http://www.informationfreeway.org/api/0.6/node[amenity=hospital]" -o data.osm

Если вы регулярно используете скрипт для получения данных из XAPI, было бы полезно установить в user agent строку что-то осмысленное. Это поможет нам больше понять о том, как используются XAPI.

Недостатки

• Предикаты. В настоящее время каждый запрос может содержать лишь один предикат ограничительной рамки. Надеемся, что в будущем будет возможность выполнить более сложные условия. Было бы здорово в 1 запросе использовать несколько предикатов ограничительной рамки для приложений похожих на GpsMid - они уже реализовали поиск данных по XAPI в Osm2GpsMid для отдельных регионов, что очень полезно.

• Грамматика запроса. Формально грамматика запроса не установлена и не обрабатывается специальным парсером, тем самым - неправильно сформулированные запросы могут привести к непредсказуемым результатам.

Предложения будущих расширений

• "Поиск по регионам" - возможность ограничивать запрос не прямоугольной рамкой, а регионом, например Страной, Графством, Континентом. Предложение от января 2011.
• "Выходные данные в формате JSON" - у на есть эта плюшка в xappy.js, она может быть использована посредством установки заголовка HTTP Content-type в "application/json". Здесь некоторая информация о формате: Xappy.js#JSON output

Альтернативы

• Osmosis Tag Filter.
• Taginfo/API
• Overpass API
• http://blog.nogago.com/poi-api

Смотрите также

• http://open.mapquestapi.com/xapi/
• API v0.6
• Xapi source code uses GT.M a high-performance schemaless database. (up again Jan 2011)
• xappy.js a reimplementation in Java Script
• XAPI Viewer