Mapbox Geocoding API

Mapbox Geocoding API — сервис преобразования адресов, названий объектов и географических описаний в координаты, а также выполнения обратной операции: получения адресной информации по известным координатам.

В экосистеме Mapbox геокодирование является одним из важнейших инструментов, поскольку позволяет связывать текстовые данные пользователей с пространственными объектами на карте. Типичные сценарии применения:

  • поиск адресов;
  • автодополнение поисковой строки;
  • определение координат объектов;
  • отображение найденных мест на карте;
  • обратное геокодирование координат GPS;
  • построение интерфейсов выбора местоположения;
  • работа с каталогами объектов и POI (Points of Interest).

Mapbox GL JS отвечает за визуализацию карты, тогда как Geocoding API предоставляет информацию о географических объектах.

Прямое геокодирование (Forward Geocoding)

Прямое геокодирование представляет собой процесс преобразования текстового запроса в координаты.

Например:

Москва

Результат:

{
  "center": [37.6176, 55.7558]
}

Другие примеры запросов:

Красная площадь
1600 Pennsylvania Avenue NW
Paris
Tokyo Station

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

Текстовый запрос
        ↓
Geocoding API
        ↓
Координаты и данные объекта
        ↓
Отображение на карте

Обратное геокодирование (Reverse Geocoding)

Обратное геокодирование выполняет противоположную задачу.

Исходными данными являются координаты:

[37.6176, 55.7558]

В ответ API возвращает сведения о местоположении:

{
  "place_name": "Москва, Россия"
}

Типичные сценарии использования:

  • определение адреса по GPS-координатам;
  • отображение адреса после клика по карте;
  • заполнение адресных форм;
  • привязка фотографий к местности;
  • создание систем трекинга транспорта.

Получение Access Token

Для работы с Geocoding API необходим токен доступа.

Пример конфигурации:

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

Токен используется во всех запросах к сервисам Mapbox.

Структура запроса геокодирования

Базовый URL:

https://api.mapbox.com/geocoding/v5/mapbox.places/

Пример запроса:

https://api.mapbox.com/geocoding/v5/mapbox.places/Moscow.json?access_token=TOKEN

Структура:

/geocoding/v5/
        ↓
mapbox.places
        ↓
поисковая строка
        ↓
формат ответа
        ↓
параметры

Выполнение запроса через Fetch API

Наиболее распространённый способ работы с Geocoding API в JavaScript — использование Fetch API.

Пример:

const query = 'Moscow';

fetch(
  `https://api.mapbox.com/geocoding/v5/mapbox.places/${query}.json?access_token=${mapboxgl.accessToken}`
)
  .then(response => response.json())
  .then(data => {
    console.log(data);
  });

Использование async/await:

async function geocode(query) {
  const response = await fetch(
    `https://api.mapbox.com/geocoding/v5/mapbox.places/${query}.json?access_token=${mapboxgl.accessToken}`
  );

  return await response.json();
}

Структура ответа API

Типичный ответ:

{
  "type": "FeatureCollection",
  "query": ["moscow"],
  "features": [
    {
      "id": "place.123",
      "type": "Feature",
      "place_type": ["place"],
      "text": "Moscow",
      "place_name": "Moscow, Russia",
      "center": [37.6176, 55.7558]
    }
  ]
}

Основные поля:

Поле Описание
type Тип объекта
query Исходный запрос
features Список результатов
center Координаты
text Краткое название
place_name Полное название
place_type Тип объекта

Массив features

Поле features содержит найденные результаты.

Пример:

data.features.forEach(feature => {
  console.log(feature.place_name);
});

Вывод:

Moscow, Russia
Moscow Oblast, Russia
Moscow River

API может вернуть несколько вариантов соответствия.

Типы географических объектов

Mapbox классифицирует объекты по типам.

Наиболее распространённые:

Тип Описание
country Страна
region Регион
postcode Почтовый индекс
district Район
place Город
locality Населённый пункт
neighborhood Микрорайон
address Адрес
poi Точка интереса

Пример:

{
  "place_type": ["country"]
}

Отображение найденной точки на карте

После получения координат объект можно показать на карте.

const coordinates = data.features[0].center;

new mapboxgl.Marker()
  .setLngLat(coordinates)
  .addTo(map);

Результат:

Поиск адреса
      ↓
Получение координат
      ↓
Создание маркера
      ↓
Отображение на карте

Центрирование карты

Часто после поиска необходимо переместить карту к найденному объекту.

map.flyTo({
  center: data.features[0].center,
  zoom: 14
});

Метод flyTo() создаёт плавную анимацию перемещения.

Также можно использовать:

map.jumpTo({
  center: coordinates
});

или

map.easeTo({
  center: coordinates
});

Поиск по нажатию кнопки

Пример реализации формы поиска:

<input id="search">
<button id="find">Найти</button>
document
  .getElementById('find')
  .addEventListener('click', async () => {

    const query =
      document.getElementById('search').value;

    const response = await fetch(
      `https://api.mapbox.com/geocoding/v5/mapbox.places/${query}.json?access_token=${mapboxgl.accessToken}`
    );

    const data = await response.json();

    const feature = data.features[0];

    map.flyTo({
      center: feature.center,
      zoom: 14
    });
  });

Ограничение количества результатов

Параметр limit задаёт максимальное число результатов.

Пример:

const url =
  `https://api.mapbox.com/geocoding/v5/mapbox.places/Paris.json
  ?limit=5
  &access_token=${mapboxgl.accessToken}`;

Ответ будет содержать не более пяти объектов.

Фильтрация по типу объекта

Можно искать только определённые типы объектов.

Поиск исключительно городов:

const url =
`https://api.mapbox.com/geocoding/v5/mapbox.places/Paris.json
?types=place
&access_token=${mapboxgl.accessToken}`;

Поиск только адресов:

const url =
`https://api.mapbox.com/geocoding/v5/mapbox.places/Main.json
?types=address
&access_token=${mapboxgl.accessToken}`;

Несколько типов:

types=place,address

Ограничение по стране

Параметр country уменьшает количество нерелевантных результатов.

Поиск только в России:

const url =
`https://api.mapbox.com/geocoding/v5/mapbox.places/Moscow.json
?country=ru
&access_token=${mapboxgl.accessToken}`;

Поиск в нескольких странах:

country=ru,kz,by

Полезно для локальных сервисов.

Использование параметра proximity

Параметр proximity влияет на порядок выдачи результатов.

Пример:

proximity=37.6176,55.7558

Полный запрос:

const url =
`https://api.mapbox.com/geocoding/v5/mapbox.places/Park.json
?proximity=37.6176,55.7558
&access_token=${mapboxgl.accessToken}`;

Система отдаёт приоритет объектам, расположенным ближе к указанным координатам.

Ограничение области поиска

Параметр bbox задаёт прямоугольную область поиска.

Формат:

minLng,minLat,maxLng,maxLat

Пример:

bbox=37.4,55.5,37.8,55.9

Запрос:

const url =
`https://api.mapbox.com/geocoding/v5/mapbox.places/Street.json
?bbox=37.4,55.5,37.8,55.9
&access_token=${mapboxgl.accessToken}`;

Результаты будут ограничены указанной территорией.

Автодополнение поиска

Для поисковых строк обычно используется параметр:

autocomplete=true

Пример:

const url =
`https://api.mapbox.com/geocoding/v5/mapbox.places/Mos.json
?autocomplete=true
&access_token=${mapboxgl.accessToken}`;

По мере ввода текста сервис будет предлагать варианты завершения запроса.

Динамический поиск при вводе текста

Пример реализации:

const input =
  document.getElementById('search');

input.addEventListener('input', async e => {

  const query = e.target.value;

  if (query.length < 3) return;

  const response = await fetch(
    `https://api.mapbox.com/geocoding/v5/mapbox.places/${query}.json?autocomplete=true&access_token=${mapboxgl.accessToken}`
  );

  const data = await response.json();

  console.log(data.features);
});

Подобный подход лежит в основе большинства современных поисковых интерфейсов.

Обратное геокодирование по клику на карту

Получение адреса после выбора точки:

map.on('click', async e => {

  const { lng, lat } = e.lngLat;

  const response = await fetch(
    `https://api.mapbox.com/geocoding/v5/mapbox.places/${lng},${lat}.json?access_token=${mapboxgl.accessToken}`
  );

  const data = await response.json();

  console.log(
    data.features[0].place_name
  );
});

Сценарий работы:

Клик по карте
      ↓
Получение координат
      ↓
Reverse Geocoding
      ↓
Получение адреса
      ↓
Отображение информации

Создание всплывающей подсказки

Результат поиска можно показать через Popup.

const feature = data.features[0];

new mapboxgl.Popup()
  .setLngLat(feature.center)
  .setHTML(feature.place_name)
  .addTo(map);

Popup может содержать:

  • адрес;
  • описание;
  • координаты;
  • ссылки;
  • произвольную HTML-разметку.

Обработка ошибок

При работе с внешним API необходимо учитывать возможные ошибки.

try {

  const response = await fetch(url);

  if (!response.ok) {
    throw new Error('Request failed');
  }

  const data = await response.json();

} catch (error) {

  console.error(error);

}

Основные причины ошибок:

  • неверный Access Token;
  • превышение лимитов запросов;
  • отсутствие подключения к сети;
  • некорректный URL;
  • пустой поисковый запрос.

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

Для упрощения интеграции существует официальный плагин геокодирования.

Подключение:

<script src="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v5.0.0/mapbox-gl-geocoder.min.js"></script>

<link
href="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v5.0.0/mapbox-gl-geocoder.css"
rel="stylesheet">

Создание элемента поиска:

const geocoder =
  new MapboxGeocoder({
    accessToken: mapboxgl.accessToken,
    mapboxgl: mapboxgl
  });

map.addControl(geocoder);

После подключения автоматически появляются:

  • поле поиска;
  • выпадающий список подсказок;
  • интеграция с картой;
  • переход к найденному объекту.

Событие result

Плагин генерирует событие получения результата.

geocoder.on('result', event => {

  console.log(event.result);

});

Объект результата содержит всю информацию, возвращаемую Geocoding API.

Получение координат результата

geocoder.on('result', event => {

  const coordinates =
    event.result.center;

  console.log(coordinates);

});

Пример вывода:

[37.6176, 55.7558]

Событие очистки поиска

geocoder.on('clear', () => {

  console.log('Search cleared');

});

Обычно используется для:

  • удаления маркеров;
  • очистки панелей информации;
  • сброса фильтров;
  • возврата карты к исходному состоянию.

Оптимизация количества запросов

Частые запросы при вводе текста могут создавать избыточную нагрузку.

Для уменьшения количества обращений применяется debounce.

function debounce(callback, delay) {

  let timeout;

  return (...args) => {

    clearTimeout(timeout);

    timeout = setTimeout(() => {
      callback(...args);
    }, delay);

  };
}

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

const search = debounce(async value => {

  const response =
    await fetch(url);

}, 300);

Запрос будет выполняться только после завершения ввода пользователем.

Практическая архитектура поиска мест

Типичная схема взаимодействия компонентов выглядит следующим образом:

Поле ввода
      ↓
Debounce
      ↓
Geocoding API
      ↓
Получение результатов
      ↓
Выбор объекта
      ↓
Mapbox GL JS
      ↓
Перемещение карты
      ↓
Маркер и Popup

Такой подход используется в:

  • навигационных системах;
  • сервисах доставки;
  • картах недвижимости;
  • туристических приложениях;
  • логистических платформах;
  • системах управления транспортом;
  • корпоративных геоинформационных системах.

Глубокая интеграция Mapbox Geocoding API и Mapbox GL JS позволяет строить полнофункциональные геопоисковые интерфейсы с поддержкой адресного поиска, подсказок, обратного геокодирования, фильтрации результатов и интерактивного отображения найденных объектов на карте.

Оглавление