Рекомендации по работе с Isochrones API

Сглаживание и точность

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

  • polygonFidelity (polygon_fidelity) – разрешение. Управляет размером ячеек пространственной сетки, используемых для расчета доступной области.

    • LOW – самые большие ячейки сетки (несколько сотен метров в поперечнике). Лучше всего подходит для покрытия больших площадей без пробелов и минимизации количества вершин, в результате чего получается обобщенная форма, которая может переоценивать доступную площадь вдоль узких дорожных коридоров.
    • MEDIUM: сбалансированная точность и размер полезной нагрузки.
    • HIGH – используются самые маленькие ячейки сетки (примерно 100–150 метров в поперечнике). В результате получается более плотное прилегание к дорожной сети с большим количеством вершин, но могут образовываться внутренние отверстия в местах, где дорожная сеть разрежена.
    • По умолчанию (POLYGON_FIDELITY_UNSPECIFIED). Если разрешение не указано, сервис выбирает его автоматически на основе способа передвижения и длительности поездки. Для коротких поездок и способа передвижения WALK используются более мелкие ячейки, а для длинных поездок – более крупные. Чтобы сравнить изохроны для разных длительностей или способов передвижения, явно задайте polygonFidelity, чтобы они использовали одинаковое разрешение.

    Размеры ячеек указаны приблизительно. Очень большие изохроны могут быть обобщены ещё больше, чтобы размер ответа оставался управляемым.

  • enableSmoothing (enable_smoothing): эстетика. Определяет, будут ли скруглены ступенчатые края ячеек сетки, заданные точностью.
    • false (необработанные данные) – возвращает границу, выровненную по сетке. Края выглядят зазубренными или ступенчатыми, отражая ячейки сетки. Лучше всего подходит для точного анализа, например для строгих проверок нахождения точки в многоугольнике.
    • true (Сглаженная). Углы скругляются, а площадь каждого кольца остается примерно такой же. Лучше всего подходит для визуального отображения на картах. Поскольку граница больше не следует за ячейками сетки, не используйте ее для строгих тестов "точка в многоугольнике".

Как они взаимодействуют. Точность задает базовый уровень детализации, который используется алгоритмом сглаживания.

  • Высокая точность + сглаживание. Создает подробную, естественно выглядящую форму, которая точно повторяет концы дорог.
  • Низкая точность + сглаживание. Создает широкую обобщенную форму.

Размер полезной нагрузки и отрисовка

Большие изохроны (особенно запросы на длительное время с точностью HIGH) могут содержать десятки тысяч координат, а несжатый ответ JSON может иметь размер в несколько сотен килобайт или больше.

  • Пропускная способность. Помните, что размер ответа JSON значителен для запросов максимальной длительности с высокой точностью.
  • Отрисовка. Отрисовка очень детализированных многоугольников влияет на производительность клиента. Чтобы уменьшить количество вершин и размер полезной нагрузки, выберите polygonFidelity: MEDIUM или LOW или упростите геометрию на клиенте перед отрисовкой, используя алгоритм упрощения линий, например Дугласа-Пекера.

Задержка и время ожидания клиента

Задержка ответа растет с размером дорожной сети: короткие маршруты и режимы WALK и BICYCLE обрабатываются быстрее всего, а длинные запросы DRIVE и TWO_WHEELER (особенно с TRAFFIC_AWARE) – дольше всего.

  • Рекомендуемое время ожидания клиента. Настройте сроки HTTP или gRPC клиента как минимум на 30 секунд, чтобы длинные запросы не прерывались раньше времени из-за короткого времени ожидания клиента.

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

Реализуйте логику повторных попыток с экспоненциальной выдержкой и джиттером для ответов об ограничении частоты запросов (429 RESOURCE_EXHAUSTED) и ошибок сервера (5xx). Не повторяйте запросы, которые привели к ошибкам 400, 403 или 404, не изменив их.

  • INVALID_ARGUMENT (400). Убедитесь, что значение атрибута travelDuration находится в диапазоне от 1s до 3600s (DRIVE/TWO_WHEELER) или 7200s (WALK/BICYCLE), атрибут location не опущен и не имеет значения (0, 0) (или place – действительный идентификатор места), а атрибут TRAFFIC_AWARE используется только с DRIVE или TWO_WHEELER. Если не указать latitude или longitude, будет использовано значение 0.0, поэтому отсутствие одного из них обычно не приводит к ошибке 400 (если только второе значение не равно 0.0). Если изохрона отображается не там, где нужно, проверьте оба значения.
  • PERMISSION_DENIED (403): убедитесь, что ключ API или токен OAuth включен и что в вашем облачном проекте Google Cloud включены Isochrones API и оплата.
  • NOT_FOUND (404). Не удалось определить местоположение по значению place или привязать пункт отправления к ближайшей дороге, подходящей для выбранного способа перемещения (в пределах 200 м или меньше для WALK и BICYCLE).
  • RESOURCE_EXHAUSTED (429): превышена квота запросов в минуту (по умолчанию 300). Повторите попытку с экспоненциальной выдержкой.