API поиска по карте

Для поиска по карте нужно выполнить POST-запрос на URL https://waste.fantastic-game.ru/opm/search.php. В теле запроса – объект JSON с параметрами поиска:

{
 "request":[...],
 "count":16,
 "offset":0,
 "out":"info"
}

JSON-QL

Этот раздел описывает объект JSON-QL.

JSON-QL – запрос к карте в формате JSON, который описывает критерии для поиска по базе данных карты. Представляет собой JSON-объект, состоящий из одного поля (node, way или relation), которое представляет из себя вложенный JSON-объект с массивом tags, описывающим теги искомого объекта карты, либо с его числовым идентификатором id. В параметре request может быть указано несколько таких JSON-QL запросов.
Структура JSON-QL:

{
  "тип_объекта_карты":{  // node, way, relation или any
    "id": 123,
    "tags":[
      {
        "key":"railway",    // ключ тега
        "value":"station",  // значение тега
        "operator":"equal"  // описывает взаимосвязь key и value
      },
      {...}
    ]
  }
}

где тип_объекта_карты – тип данных карты. Всего их три: node, way и relation:
        node – одиночная точка на карте;
        way – линия (или полигон), состоящая из нескольких точек. Это может быть участком дороги, зданием, лесом, рекой или озером;
        relation – отношение. Состоит из множества точек, линий и других отношений. Может представлять собой автобусный маршрут, состоящий из участков дороги (way) и остановок (node) или здание сложной формы, имеющее внешний и внутренний контуры (way).
        any – поиск выполняется независимо от типа объекта карты.

Описание параметров JSON-QL:

Если необходимо вернуть объект, который содержит key1=value1 И key2=value2, то в поле tags должны быть перечислены два JSON-объекта. 

Если необходимо вернуть объект, который содержит key1=value1 ИЛИ key2=value2, то в параметре request должны быть перечислены два JSON-QL, внутри которых tags содержит только один из тегов: один JSON-QL для key1=value1, второй для key2=value2. 

ОПЕРАТОРЫ

• equal, = – эквивалентность, равенство. тег с ключом key должен иметь значение value.
• not_equal, nequal, != – тег с ключом key должен иметь любое значение, не равное value.
• like – значение тега с ключом key должно частично совпадать с value. В отличие от предыдущих, данный оператор регистронезависимый. Отлично подходит в сочетании с параметром key=name.
• exists – тег с ключом key существует. Значение тега неважно.
• regexp, rgex – позволяет использовать регулярное выражение в параметре value.
• less, < – тег объекта должен быть меньше указанного числа (например для цены [opm:price]).
• more, > – тег должен быть больше указанного числа.
• nmore, <= – значение тега должно быть меньше либо равно указанному числу.
• nlesss, >= – значение тега должно быть больше либо равно указанному числу.

РЕГУЛЯРНЫЕ ВЫРАЖЕНИЯ

Регулярные выражения можно использовать в параметре key.
Если operator=regexp, то регулярные выражения, также, можно использовать в параметре value.

Примеры регулярных выражений:

(name|description) — одно из двух: или name, или description.
Солнечн(ая|ый)  — одно из двух: или Солнечная, или Солнечный.
(.*)— любой символ или символы в любом количестве.
и т.д.

ПАРАМЕТР OFFSET

Параметр можно охарактеризовать как номер страницы. Рекомендуется ставить всегда 0. Данный параметр отлично работает, если в параметре request указан только один JSON-QL. 

Несмотря на название (offset – смещение) должен передаваться «номер страницы», где 0 – это первая страница, 1 – вторая, и т.д. Смещение как таковое будет автоматически рассчитываться исходя из параметра сount.

ОТВЕТ

Ответ приходит в формате JSON. В случае успеха ответ будет содержать параметр count – количество найденных объектов карты и поле response.

В общем случае поле respone в ответе будет содержать массив объектов карты.
В случае, если в запросе параметр out=member_of, поле respone в ответе будет представлять из себя JSON-объект, содержащий объекты участия.

Пример ответа для общего случая:

{
  "count":1,
  "response":[
    {
      "id":"356095",
      "type":"node",
      "coordinates":[1.42618323897,72.16699583768],
      "tags":{
        "name":"Приволжск",
        "place":"town"
      }
    }
  ]
}

КООРДИНАТЫ ОБЪЕКТА

В ответе координаты приходят в следующем порядке: сначала долгота, а затем широта. Формат ответа зависит от типа объекта.

node

Для точек на карте координаты в coordinates приходят в виде массива с двумя числами: долгота и широта, соответственно.

"coordinates": [123, 45]

way

Для линий координаты приходят в виде массива, содержащего координаты точек, из которых состоит линия:

"coordinates": [[1, 2], [2, 4], [3, 6]]

relation

Поскольку отношения одновременно могут содержать как точки, так и линии (например, автобусный маршрут), то координаты отдельных точек (например, остановок) приходят в виде массива в points, а координаты линий приходят в виде массива в line_points, который содержит координаты линий:

"points":[[1, 1], [2, 4]],
"line_points": [[[1, 2], [3, 4]], [[3, 4], [5, 6]], [[5, 6], [7, 8]]]

ОШИБКИ И ПРЕДУПРЕЖДЕНИЯ

В ходе выполнения могут произойти предупреждения, связанные с неправильно составленным JSON-QL запросом. Если в ходе выполнения запроса была обнаружена некритическая ошибка в JSON-QL запросе, в ответ добавляется поле warnings – массив, содержащий тексты предупреждений с описанием ошибок, допущенных в JSON-QL запросе. Поле response при этом остается в ответе и содержит результаты поиска для JSON-QL запросов, составленных без ошибок.

В ходе выполнения также могут произойти критические ошибки. В этом случае возвращается только текстовое поле error с описанием критической ошибки.

ПРИМЕР ЗАПРОСА

ПРИМЕРЫ ЗАПРОСОВ

{
    "request":[{
        "node":{
            "tags":[{
                "key":"name",
                "value":"Приволжск",
                "operator":"like"
            }]
        }
  }],
  "count":3,
  "offset":0,
  "out":"coords"
}

{
    "count":3,
    "response":[
        {
             "id":"354869",
             "type":"node",
             "coordinates":[1.39663472057,72.16805992967]
        },
        {
            "id":"356095",
            "type":"node",
            "coordinates":[1.42618323897,72.16699583768]
        },
        {
            "id":"516300",
            "type":"node",
            "coordinates":[1.36904787392,72.16951513869]
         }
    ]
}

{
    "request":[{
        "relation":{
            "id":688055
        }
    }],
    "count":1,
    "offset":0,
    "out":"info"
}

{
    "count":1,
    "response":[
        {
            "id":688055,
            "type":"relation",
            "members": [...]
            "points":[...],
            "line_points":[...],
            "tags":{
                "name":"Автобус №71",
                "public_transport:version":"2",
                "ref":"71",
                "route":"bus",
                "type":"route"
            }
        }
    ]
}

{
    "request": [{
        "node": {
            "tags": [{
                "key": "(name|description)",
                "value": "волчанск",
                "operator": "like"
            }]
        }
    },
    {
        "way": {
            "tags": [{
                "key": "(name|description)",
                "value": "волчанск",
                "operator": "like"
            }]
        }
    }],
    "count": 3,
    "offset": 0,
    "out": "coords"
}

JSON-схема объекта карты

JSON-объект с информацией об объекте карты, возвращаемый в api поиска по карте содержит следующие параметры:

БАЗОВЫЕ ПОЛЯ

ОПЦИОНАЛЬНЫЕ ПОЛЯ

Включение в ответ этих полей зависит от параметров запроса

JSON-объект участия

Возвращается в поле response в случае, если параметр запроса out=member_of.

JSON-объект состоит из трёх полей node, way и relation, которые включаются в ответ по мере надобности. Из всех запрошенных объектов карты в ответ включаются только те объекты, которые являются участниками какого-либо другого объекта.

Структура всех трёх полей одинаковая и представляет собой JSON-объект, ключами которого являются числовые идентификаторы некоторых из запрошенных объектов, при этом каждый ключ содержит массив из объектов карты, участником которых является запрошенный объект. При этом возвращаются только числовой идентификатор объекта, его тип и теги.

Поля JSON-объекта участия

{"node":{
 "id_запрошенной_точки1":[/*объекты карты, в которых участвует эта точка*/],
 "id_запрошенной_точки2": [...],
 ...
}}

<