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

Все, что вам нужно для старта – это любая утилита для отправки HTTP-запросов, или вы можете использовать адресную строку вашего веб-браузера. Вы также можете использовать ГЕОЛАБОРАТОРИЮ, которая доступна в вашем личном кабинете.

ОБЗОР

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

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

AУТЕНТИФИКАЦИЯ

Обратите внимание, что все функции PickPoint доступны только с ключом доступа.
https://api.pickpoint.io/v1/?key=YOUR-API-KEY
Откройте полученный URL-адрес в адресной строке вашего браузера. Вы увидите сообщение "Welcome to PickPoint API" (Добро пожаловать в PickPoint API). Это означает, что вы успешно авторизованы и подключены к нашему API. В противном случае вы увидите сообщение "Unauthorized".

Чтобы использовать функции API PickPoint, вам необходимо добавить свой ключ API ко всем вашим запросам:
Теперь вы можете сделать свой первый запрос к API PickPoint. Для этого создайте URL-адрес в следующем формате:
?key=YOUR-API-KEY
Прямое геокодирование - это функция преобразования географических адресов в координаты в формате Широта-Долгота. Например, указав адрес "221b Baker St, London NW1 6XE", вы получите его координаты - "51.524259, -0.1584738", и он будет отображен на карте.

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

ПРЯМОЕ ГЕОКОДИРОВАНИЕ

Если вы хотите сузить свой запрос по типу запрашиваемого адреса, например, осуществить поиск только города или страны, вы должны использовать следующие параметры:
country (страна) - поиск по стране
state (штат)- поиск по штатам
county (округ)- поиск по районам / провинциям
city (город)- поиск по названиям городов
street (улица)- поиск по названиям улиц должен быть указан в следующем формате <house_number> <street_name>
postalcode (почтовый индекс) - ограничить результаты указанным почтовым индексом. Обратите внимание, что эти параметры не могут использоваться совместно с параметром q. Рассмотрим поиск города с названием Санкт – Петербург:
GET https://api.pickpoint.io/v1/forward
Основным параметром функции геокодирования является поисковый запрос, который отправляется с ключом q. Обычно географический адрес объекта является параметром поискового запроса, например:

221b Baker St, Лондон NW1 6XE

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

Параметр 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) для нежелательных географических объектов. Например, вы хотите найти все объекты с именем "Лондон", за исключением столицы Великобритании. Используя 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, который вы получаете в результате функции геокодирования. Используя поиск, вы можете получить географический адрес: "Бейкер-стрит, Мэрилебон, Вестминстер, Лондон, Большой Лондон, Англия, NW1 6XE".

ИЗВЛЕЧЕНИЕ АДРЕСА

https://api.pickpoint.io/v1/lookup
Входные данные этой функции – параметр osm_ids. В нем должны быть перечислены объекты (от 1 до 50), разделенные запятыми. Для каждого объекта необходимо указать, к какому типу OSM он принадлежит, и рядом с ним должен быть идентификатор объекта. Существует три основных типа объектов OSM:
R - relation
W - way
N - node
Вот примеры для каждого типа объектов:
Это точка входа для функции извлечения адреса:
GET /lookup/?key=YOUR-API-KEY&osm_ids=W481027013,N1809771508,R568660
ТОЧКА ВХОДА
ЗАПРОС
Наша платформа геокодирования поддерживает два наиболее распространенных формата ответов: JSON и XML. Вы можете изменить их, включив нужный формат (json или xml) в параметр запроса format, например:

ФОРМАТ ОТВЕТА

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