Почему Google Maps Distance Matrix путает ZIP‑коды и как это починить

Почему Google Maps Distance Matrix API ошибочно геокодирует ZIP‑коды (01033 → Киев) и как исправить: добавляйте штат и страну, например «01033, MA, USA».

Иногда Distance Matrix возвращает совершенно неверные результаты, если передавать ей ZIP‑коды. Типичный случай: отправка «01033» как точки отправления порой приводит к Киеву, Украина, а не к Гранби, MA — несмотря на подсказки региона вроде region='us' и несмотря на то, что при ручном поиске Google Maps показывает нужное место. Разберёмся, почему так происходит, и как стабилизировать результаты без переделки всей интеграции.

Пример проблемы

Сценарий простой: список ZIP‑кодов Массачусетса в качестве точек отправления и адрес пункта назначения.

orig_zips = ["01033", "02108"]
dst_point = "Boston, MA, USA"

maps_client.distance_matrix(
    orig_zips,
    dst_point,
    mode="driving",
    region="us",
    traffic_model="best_guess",
)

Корневая причина

Distance Matrix не вычисляет расстояние прямо из текстовой строки. Сначала под капотом вызывается Geocoding, который превращает ваш ввод в place_id, и только потом считается дистанция. В документации сказано:

«Если вы передаёте адрес, сервис геокодирует строку и преобразует её в координаты широты/долготы для расчёта расстояния».

И раздел FAQ по Geocoding описывает тот же процесс:

«Когда в Directions API (Legacy) или Distance Matrix API (Legacy) передают строку адреса вместо place ID или latlng, эти сервисы используют тот же бэкенд, что и Geocoding API, чтобы конвертировать адрес в place ID перед расчётом маршрута».

Почтовые индексы по своей природе неоднозначны. Иногда они геокодируются в нужный населённый пункт, а иногда — нет. Поскольку Distance Matrix опирается на первый шаг геокодирования, источники, заданные только ZIP, могут распознаваться неверно. Добавление region='us' не гарантирует ожидаемого разрешения неоднозначности.

Как исправить

Не используйте голые почтовые индексы в качестве отправления и назначения. Указывайте корректно оформленные адреса, которые сужают поиск. Практичный вариант — дополнить ZIP штатом и страной, следуя формату адресов из документации Distance Matrix. Например, вместо «01033» использовать «01033, MA, USA».

orig_inputs = ["01033, MA, USA", "02108, MA, USA"]
dst_point = "Boston, MA, USA"

maps_client.distance_matrix(
    orig_inputs,
    dst_point,
    mode="driving",
    region="us",
    traffic_model="best_guess",
)

Логика программы не меняется: вы лишь передаёте более точные адресные строки для шага геокодирования, что снижает риск ошибочных совпадений вроде случая с Киевом.

Почему это важно

Точность расстояний и маршрутов зависит от исходных точек. Если геокодирование ошибается, все последующие метрики — расстояние, время, даже оценки стоимости или SLA — могут отличаться на порядки. Осознавая, что Distance Matrix сперва выполняет геокодирование, а почтовые индексы — слабые идентификаторы, вы сможете усилить входные данные и избежать тихих сбоев.

Выводы

Если вам нужно продолжать использовать Distance Matrix API (Legacy), не передавайте ZIP‑коды сами по себе. Отдавайте предпочтение полным адресным строкам вроде «01033, MA, USA». Геокодирование работает надёжнее с корректно оформленными адресами, и это небольшое изменение снимает большую часть неоднозначностей без рефакторинга интеграции.