My Geocode

Руководства

Разбор поля с адресом в свободной форме на структурированные компоненты

· 3 мин чтения · My Geocode · #прямое-геокодирование#разбор-адресов#структура-данных

Одно поле адреса со свободным текстом легко собрать, но с ним трудно работать потом, особенно когда нужно фильтровать по городу или группировать по региону. Прямое геокодирование выполняет разбор за вас как побочный эффект определения координат адреса.

Отправка свободного текста

GET /v1/forward?q=1600 Pennsylvania Avenue, Washington, DC 20500&limit=1
{
  "status": "ok",
  "query": "1600 Pennsylvania Avenue, Washington, DC 20500",
  "results": [
    {
      "formatted": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
      "lat": 38.8977,
      "lon": -77.0365,
      "type": "address",
      "precision": "house",
      "confidence": 0.97,
      "place_id": "def456",
      "components": {"house_number": "1600", "street": "Pennsylvania Avenue NW", "city": "Washington", "region": "DC", "postcode": "20500", "country": "US"}
    }
  ]
}

Раздельное хранение компонентов

Получив объект components, записывайте каждое поле в отдельный столбец базы данных, а не храните только исходную строку со свободным текстом. Это позволяет фильтровать записи клиентов по городу или региону, формировать точные региональные отчёты и проверять, что почтовый индекс и город действительно соответствуют друг другу, а ничего из этого нельзя практически сделать с одной неструктурированной строкой.

Второй пример: адрес в другом формате

Структура адресов везде разная. Адрес в Великобритании может вернуться с графством вместо региона в американском стиле, а такой компонент, как house_number, может полностью отсутствовать у здания с собственным названием. Запрос того же вида работает для любой страны, но ключи компонентов, которые вы фактически получите, могут различаться, поэтому стройте схему хранения так, чтобы она допускала отсутствие компонента, а не предполагала, что каждая страна каждый раз заполняет один и тот же набор.

Распространённая ошибка, которой стоит избегать

Не закладывайте жёстко предположение, что каждый результат будет содержать все поля house_number, street, city, region и postcode, и не считайте любой адрес, в котором одного из них нет, ошибкой разбора. Совершенно правильный адрес, особенно за пределами городской сетки с нумерацией домов, вполне законно может вернуться с некоторыми пустыми полями. Строгая проверка, построенная на полном наборе компонентов, будет отклонять реальный ввод клиентов, который эндпоинт разобрал правильно.

Сохраняйте и исходный текст

Храните исходный ввод в свободной форме вместе с разобранными компонентами, а не удаляйте его. Если какой-то компонент вернётся неполным или клиенту позже понадобится что-то исправить, наличие исходного текста под рукой упрощает повторный разбор или ручное исправление.

Обработка частичного разбора

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

Обработка нескольких правдоподобных совпадений

Если увеличить limit больше 1, вы получите несколько вариантов результата, упорядоченных по тому, насколько каждый из них соответствует введённому тексту. Это полезно, когда нужно показать клиенту короткий список для выбора, а не молча принимать первый найденный вариант. Такой подход служит разумным компромиссом между полностью автоматическим разбором и полностью ручной формой ввода, особенно для адресов, которые ваш порог уверенности иначе пометил бы как сомнительные.

Сколько это стоит

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

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

Ещё в разделе «Руководства»

· 4 мин чтения

Сверка адреса с почтовым индексом

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