Tilequery API

Общая концепция Tilequery API

Tilequery API представляет собой инструмент для выполнения запросов к векторным тайлам в реальном времени с целью получения объектов (features), находящихся в заданной географической области. В отличие от классических пространственных запросов к серверной базе данных, Tilequery работает поверх предварительно отрендеренных векторных тайлов, что обеспечивает высокую скорость ответа и масштабируемость.

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

Архитектура и принцип работы

Tilequery API использует следующий принцип обработки запросов:

  1. На вход подаётся географическая точка (или линия/полигон через расширенные параметры).
  2. Указывается радиус поиска в метрах.
  3. Определяются слои векторного tileset’а.
  4. Сервис вычисляет, какие тайлы пересекают заданную область.
  5. Из этих тайлов извлекаются объекты, удовлетворяющие условиям запроса.

Ключевое отличие от классических GIS-запросов — отсутствие необходимости выполнять пространственные операции над полной базой данных.

Endpoint и базовая структура запроса

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

https://api.mapbox.com/v4/{tileset_id}/tilequery/{lon},{lat}.json

Обязательные параметры:

  • tileset_id — идентификатор векторного набора данных
  • lon,lat — координаты центра запроса

Дополнительные параметры:

  • radius — радиус поиска в метрах
  • limit — максимальное количество возвращаемых объектов
  • layers — фильтрация по слоям tileset’а
  • dedupe — устранение дубликатов объектов
  • geometry — тип возвращаемой геометрии (point, linestring, polygon)

Пример:

https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/37.6173,55.7558.json?radius=100&limit=10&access_token=YOUR_TOKEN

Параметры запроса и их особенности

radius

Радиус определяет область поиска вокруг точки. Значение задаётся в метрах и напрямую влияет на количество тайлов, которые будут обработаны.

Особенности:

  • малые значения (<50 м) подходят для точечных объектов
  • большие значения увеличивают нагрузку и время ответа

limit

Ограничивает количество возвращаемых объектов. Полезен при работе с плотными городскими слоями.

layers

Позволяет сузить область поиска до конкретных слоёв tileset’а:

layers=building,road,poi

Это особенно важно для оптимизации запросов.

dedupe

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

geometry

Управляет тем, как возвращается геометрия объекта:

  • point — только координаты
  • linestring — для линейных объектов
  • polygon — для площадных объектов

Интеграция с Mapbox GL JS

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

Пример использования при клике по карте:

map.on('click', async (e) => {
  const url = `https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/${e.lngLat.lng},${e.lngLat.lat}.json` +
    `?radius=50&limit=5&access_token=YOUR_TOKEN`;

  const response = await fetch(url);
  const data = await response.json();

  console.log(data);
});

Отображение результатов на карте

Результаты Tilequery можно преобразовать в GeoJSON и отобразить через слой источника:

map.on('click', async (e) => {
  const query = await fetch(
    `https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/` +
    `${e.lngLat.lng},${e.lngLat.lat}.json?radius=100&access_token=YOUR_TOKEN`
  );

  const data = await query.json();

  const geojson = {
    type: 'FeatureCollection',
    features: data.features
  };

  if (map.getSource('query-results')) {
    map.getSource('query-results').setData(geojson);
  } else {
    map.addSource('query-results', {
      type: 'geojson',
      data: geojson
    });

    map.addLayer({
      id: 'query-points',
      type: 'circle',
      source: 'query-results',
      paint: {
        'circle-radius': 6,
        'circle-color': '#ff5200'
      }
    });
  }
});

Фильтрация и работа с properties

Каждый объект, возвращаемый Tilequery API, содержит:

  • geometry
  • properties
  • id
  • layer

Пример фильтрации:

const buildings = data.features.filter(f =>
  f.properties.class === 'building'
);

Это позволяет реализовывать сложные сценарии анализа городской среды.

Использование в аналитике и геопространственных задачах

Tilequery API применяется в следующих сценариях:

  • поиск ближайших объектов инфраструктуры
  • анализ плотности городской застройки
  • определение объектов в радиусе события (например, ДТП)
  • интерактивные справочные системы на карте
  • построение UI для геолокационных сервисов

Производительность и ограничения

Несмотря на высокую скорость работы, Tilequery имеет ряд ограничений:

  • ограничение на глубину анализа тайловой структуры
  • зависимость от качества tileset’а
  • возможные задержки при больших радиусах
  • ограничение на количество возвращаемых объектов

Оптимизация достигается через:

  • уменьшение радиуса
  • использование layers
  • ограничение limit
  • предварительную фильтрацию данных в tileset

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

Типовые ошибки:

  • 400 Bad Request — неверные координаты или параметры
  • 401 Unauthorized — отсутствует или неверный access token
  • 404 Not Found — неверный tileset
  • 422 Unprocessable Entity — некорректный radius или limit

Пример обработки:

try {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
} catch (err) {
  console.error('Tilequery error:', err);
}

Комбинация с пользовательскими слоями

Tilequery API часто используется вместе с кастомными слоями Mapbox GL JS:

  • выделение объектов при наведении
  • синхронизация с UI-фильтрами
  • динамическое обновление данных на основе viewport

Пример синхронизации с картой:

map.on('moveend', async () => {
  const center = map.getCenter();

  const url = `https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/` +
    `${center.lng},${center.lat}.json?radius=200&limit=20&access_token=YOUR_TOKEN`;

  const res = await fetch(url);
  const data = await res.json();

  map.getSource('query-results').setData({
    type: 'FeatureCollection',
    features: data.features
  });
});

Работа с плотными городскими данными

В городских районах Tilequery может возвращать большое количество объектов. Для корректной работы применяются стратегии:

  • агрегация объектов по типу
  • группировка по слоям
  • визуальное кластеризование через Mapbox GL JS
  • ограничение радиуса до 50–150 метров

Геометрические особенности результата

Tilequery возвращает геометрию в формате GeoJSON, но точность зависит от исходного tileset’а. Важно учитывать:

  • упрощение геометрии на уровне тайлов
  • возможное смещение при масштабировании
  • ограничение детализации на низких зумах

Практические сценарии использования

  • определение ближайших станций транспорта
  • поиск POI вокруг пользователя
  • интерактивные городские карты
  • анализ инфраструктуры в радиусе события
  • динамическая фильтрация объектов на карте в реальном времени
Оглавление