Следите за использованием ключа, пока не упёрлись в лимит
Наблюдение за заголовками квоты по ходу работы показывает приближение к лимиту задолго до того, как запрос будет отклонён.
Почтовый индекс вместе со страной для более быстрых запросов
Прямое геокодирование рассчитано на неаккуратный свободный текст, а значит, выполняет скрытую работу, чтобы понять, какие входные данные перед ним. Если вы уже знаете, что у вас чистый почтовый индекс и страна, есть более прямой путь.
Сразу к эндпоинту postcode
Вместо того чтобы собирать строку свободного текста и отправлять её в /v1/forward, отправьте индекс и страну напрямую в /v1/postcode.
GET /v1/postcode?code=90210&country=US{
"status": "ok",
"postcode": "90210",
"country_code": "US",
"results": [
{"lat": 34.0901, "lon": -118.4065, "components": {"city": "Beverly Hills", "region": "CA", "country": "US"}}
]
}Почему это подходит лучше
Пара «почтовый индекс и страна» уже является полностью структурированными входными данными, поэтому эндпоинту не нужно разрешать неоднозначность, как это бывает со строкой свободного текста, которая может совпасть с несколькими похоже названными местами. Эндпоинт, созданный именно для такой формы входных данных, даёт более чистое совпадение с меньшим риском неожиданного результата.
Второй пример: буквенно-цифровой почтовый индекс
Тот же вызов работает точно так же для страны, где в индексах используются и буквы, и цифры, а не только цифры.
GET /v1/postcode?code=K1A 0B1&country=CAНадёжность обеспечивает именно параметр country: сама строка индекса не всегда уникальна для разных стран, а параметр country сообщает эндпоинту, в рамках какой почтовой системы её интерпретировать.
Когда прямое геокодирование всё же нужно
Если вам нужно конкретное совпадение на уровне улицы, а не общая область, которую покрывает почтовый индекс, правильным инструментом остаётся прямое геокодирование по полному адресу, поскольку поиск по почтовому индексу возвращает область, которую покрывает индекс, а не конкретное здание в ней. Используйте /v1/postcode для поиска на уровне области, например для проверки зоны доставки, и /v1/forward, когда нужна точность до дома.
Распространённая ошибка, которой стоит избегать
Не думайте, что почтовый индекс всегда соответствует ровно одной точке, которая точно представляет каждый адрес внутри него. Координаты, возвращаемые /v1/postcode, представляют область, которую покрывает индекс, а это может быть один городской квартал или, в некоторых странах, гораздо более крупная зона. Если считать возвращённую точку точным местоположением здания конкретного клиента, а не репрезентативной точкой для всего индекса, в любую чувствительную к расстоянию логику, построенную на её основе, попадёт ошибка.
Сочетание обоих в одном процессе
Распространённый подход: сначала проверить пару «почтовый индекс и страна» через /v1/postcode, а затем, если проверка пройдена, отправить полный адрес в /v1/forward, чтобы получить точные координаты. Это два запроса на одну отправку формы, по одному на каждый этап, вместо попытки заставить один эндпоинт делать обе работы.
Пограничный случай: индекс, для которого нет результатов
Пустой массив results означает, что индекс не распознан для указанной страны, и это другая ситуация, чем ответ с ошибкой. Обрабатывайте его так же, как любые другие нераспознанные входные данные: попросите клиента перепроверить введённое, а не показывайте это как системную ошибку.
Сколько это стоит
Каждый поиск по индексу считается одним запросом, так же как поиск через прямое геокодирование. Выбор правильного эндпоинта для структурированных данных не меняет стоимость, он меняет то, насколько прямо вы получаете правильный результат.
Если у вас уже есть чистые структурированные данные, обращение к эндпоинту postcode избавляет от лишней неоднозначности, которая возникает, когда вы собираете строку свободного текста только для того, чтобы её снова разобрали на части. Все подробности в документации по поиску почтовых индексов.