Этот раздел предназначен для разработчиков приложений и серверов, использующих платформу геокодирования PickPoint. Перед началом работы с API необходимо создать учётную запись. Для быстрого ознакомления с нашим сервисом, пожалуйста, обратитесь к разделу «Начало работы».

Всё, что вам нужно для начала экспериментов, — это любая утилита для отправки HTTP-запросов, или вы можете использовать адресную строку браузера. Также можно использовать GEO LAB, доступный в личном кабинете.

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

Чтобы начать работать с нашим сервисом, вам необходимо сначала скопировать свой API-ключ, который доступен в разделе подписки вашего аккаунта:

Обратите внимание, что все функции PickPoint доступны только при наличии ключа доступа

https://api.pickpoint.io/v1/?key=YOUR-API-KEY

Откройте полученный URL в адресной строке браузера. Вы увидите сообщение «Добро пожаловать в PickPoint API». Это означает, что вы успешно авторизованы и подключены к нашему API. В противном случае вы увидите сообщение «Не авторизовано».

Чтобы использовать функции PickPoint API, вам необходимо добавить свой API-ключ ко всем запросам:

Теперь вы можете сделать свой первый запрос к API PickPoint. Для этого создайте URL-адрес в следующем формате:

?key=YOUR-API-KEY

Прямое геокодирование — это функция преобразования географических адресов в координаты в формате «широта-долгота». Например, указав адрес «221b Baker St, London NW1 6XE», вы получите его координаты «51.524259, -0.1584738» и отобразите его на карте.

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

Если вы хотите сузить запрос по типу искомого элемента, например, искать только города или страны, используйте следующие параметры:

country — поиск по стране
state — поиск по штатам county — поиск по районам/областям
city — поиск по названиям городов street — поиск по названиям улиц.

Необходимо указать в следующем формате: <номер_дома> <название_улицы>

postalcode — ограничить результаты указанным почтовым индексом. Обратите внимание, что эти параметры не применимы с параметром q. Рассмотрим поиск городов с названием Санкт-Петербург:

GET https://api.pickpoint.io/v1/forward

Основным параметром функции геокодирования является поисковый запрос, отправляемый с ключом q.

Обычно поисковым запросом является географический адрес объекта, например: 221b Baker St, London NW1 6XE

Обратите внимание, что строка запроса должна быть преобразована в формат URL-кодирования. Параметра q также достаточно для создания простого запроса:

Функции прямого геокодирования выполняются с использованием следующих запросов:

GET /forward/?key=YOUR-API-KEY&q=21b%20Baker%20St,%20London%20NW1%206XE

ТОЧКА ВХОДА

ЗАПРОС

GET /forward/?key=YOUR-API-KEY&city=Saint-Petersburg

По разным причинам вам может потребоваться ограничить результаты поиска. Ниже представлено несколько полезных параметров, которые можно использовать для этого. Параметр countrycodes используется для ограничения области поиска по стране или списку стран. Значением параметра должен быть двухбуквенный код страны (или коды стран) в формате ISO 3166 alpha-2.
Вот пример:
Польша - pl
Новая Зеландия - nz
Китай - cn
Возможно, вы знаете, что географическое название Лондон относится не только к столице Великобритании, но и к нескольким городам в США. Чтобы исключить результаты за пределами Великобритании, сформулируйте запрос следующим образом:

GET /forward/?key=YOUR-API-KEY&q=London&countrycodes=gb

ГРАНИЦЫ

Полный список кодов стран в формате ISO 3166 alpha-2 можно найти здесь.
Существует большое количество различных геообъектов с одинаковым названием. Но если ограничить область поиска геометрически, сформировав прямоугольную область на координатной сетке, вы, вероятно, получите лучшие результаты. Здесь вступает в игру параметр viewbox. Например, вы хотите найти координаты объектов, в названиях которых есть слово «парк». Более конкретно, ваш поиск осуществляется только в Лондоне. Используя результаты предыдущего запроса, укажите:

GET /forward/?key=YOUR-API-KEY&q=park&viewbox=0.0,52.0,1.0,53.0&bounded=1

Обратите внимание, что помимо viewbox запрос включает параметр bounded. Использование этого параметра гарантирует, что будут показаны только результаты из указанной области (viewbox). Чтобы исключить заведомо нерелевантные результаты, используйте параметр exclude_place_ids с идентификаторами OSM (place_id) для нежелательных географических объектов. Например, вы хотите найти все объекты с именем «London», за исключением столицы Великобритании. Используя place_id, полученный в результате одного из наших предыдущих запросов, получаем:

GET /forward/?key=YOUR-API-KEY&q=London&exclude_place_ids=158415464

Чтобы ограничить количество результирующих вариантов, используйте параметр limit:

GET /forward/?key=YOUR-API-KEY&q=London&limit=1

Обратное геокодирование — это функция, преобразующая координаты в формате «широта – долгота» в географические адреса. Например, указав координаты «51.524259, -0.1584738», вы получите географический адрес этой точки.

Результаты функции обратного геокодирования можно масштабировать, изменяя параметр масштабирования от 0 (самый широкий параметр – страны) до 18 (самый узкий параметр – здания). Пример:

https://api.pickpoint.io/v1/reverse

Для выполнения простой функции обратного геокодирования необходимо использовать два параметра: lat – широта и lon – долгота. Эти параметры должны быть указаны в градусах. Пример:

Функции обратного геокодирования доступны по следующему адресу:

GET /reverse/?key=YOUR-API-KEY&lat=48.85881005&lon=2.32003101155031

ТОЧКА ВХОДА

ЗАПРОС

GET /reverse/?key=YOUR-API-KEY&lat=52.183430&lon=-106.2707519&zoom=0

Функция поиска адреса (Address Lookup) преобразует идентификаторы OSM в географические адреса с соответствующими координатами. Например, в базе данных OSM есть путь с идентификатором 3996986, который сохраняется в результате геокодирования. С помощью поиска можно получить географический адрес: «Baker Street, Marylebone, Westminster, London, Greater London, England, NW1 6XE».

https://api.pickpoint.io/v1/lookup

Входными данными этой функции является параметр osm_ids. Он должен содержать список объектов (от одного до 50), разделенных запятыми. Для каждого объекта необходимо указать, к какому типу OSM он принадлежит, а рядом с ним должен быть указан идентификатор объекта. Существует три основных типа объектов OSM:

• R — отношение
• W — путь
• N — узел

Вот примеры для каждого типа объекта:

Это точка входа для функции поиска адреса:

GET /lookup/?key=YOUR-API-KEY&osm_ids=W481027013,N1809771508,R568660

ТОЧКА ВХОДА

QUERY

Наша платформа геокодирования поддерживает два наиболее распространённых формата ответа: JSON и XML. Вы можете изменить их, указав нужный формат (json или xml) в параметре формата запроса, например:

GET /forward/?key=YOUR-API-KEY&q=Tokyo&format=json

С помощью параметра accept-language можно указать предпочитаемый язык результата геокодирования. Значение этого параметра должно быть указано в формате ab-XY, где:

• «ab» — ​​двухбуквенный код языка в формате ISO 639-1. Например, «en» — английский, «fr» — французский, «ru» — русский. Чтобы увидеть полный список кодов языков, нажмите здесь.
• «XY» — двухбуквенный код страны в формате ISO-3166. Например, «ES» — Испания, «DE» — Германия, «CN» — Китай. Чтобы увидеть полный список кодов стран, нажмите здесь.

Пример:

GET /forward/?key=YOUR-API-KEY&q=Tokyo&accept-language=en

Каждый тип запроса геокодирования может возвращать адреса в структурированном формате. Для этого следует использовать параметр addressdetails=1. В результате в теле ответа появится новый атрибут addressparts (для запросов поиска адреса подробный адрес является частью тела ответа), который подробно описывает каждую часть найденного адреса.

Пример запроса с подробным адресом:

GET /reverse/?key=YOUR-API-KEY&lat=48.8698899&lon=2.3084521&zoom=18&addressdetails=1

Если вам нужно просмотреть список названий геообъектов на других языках или найти возможные альтернативные названия, используйте параметр namedetails=1. В ответе будет добавлен новый атрибут namedetails со списком всех возможных названий, как в следующем примере:

GET /lookup/?key=YOUR-API-KEY&osm_ids=R2360164&namedetails=1

В некоторых случаях может потребоваться знать границы геообъектов, например, для отображения их на карте или визуализации каким-либо другим способом. В настоящее время эта возможность доступна только для запросов прямого и обратного геокодирования. Вы можете получить эти координаты в четырёх различных форматах:

GeoJSON — при установке параметра polygon_geojson в значение 1 результат будет получен в атрибуте geojson строки ответа.
KML — отправьте polygon_kml=1, чтобы получить координаты в качестве значения атрибута geokml.
SVG — данные в этом формате следует запрашивать с параметром polygon_svg=1. Результат будет получен в атрибуте geosvg.
Text — для получения координат в виде текста используйте параметр polygon_text=1. Результат будет получен в атрибуте geotext.

Пример получения границ Лондона:

GET /forward/?key=YOUR-API-KEY&q=Tokyo&format=json