Типы результатов геокодирования

Ответ геокодера Google Maps JavaScript API представляет собой массив объектов результатов, где каждый объект описывает одно возможное соответствие введённого адреса или координат. Основная структура включает ключевые поля:

  • formatted_address
  • geometry
  • address_components
  • types
  • place_id
  • partial_match (в некоторых случаях)
  • дополнительные служебные поля

Каждое из этих полей играет роль в определении точности и интерпретации найденного объекта на карте.

Поле formatted_address

formatted_address содержит человекочитаемое строковое представление адреса. Формат формируется системой Google и может отличаться по детализации в зависимости от региона и уровня точности результата.

Пример:

"formatted_address": "ул. Абая 10, Караганда 100000, Казахстан"

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

Поле place_id

place_id — уникальный идентификатор объекта в системе Google Places. Он остаётся стабильным даже при изменении адресной структуры или форматирования.

Основные характеристики:

  • уникален в глобальной базе Google Places
  • используется для последующих запросов Place Details
  • не зависит от языка или локализации

Пример:

"place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4"

Поле types результата геокодирования

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

Основные типы результата

  • street_address — точный адрес здания
  • route — улица
  • intersection — перекрёсток
  • political — административная единица
  • country — страна
  • administrative_area_level_1 — регион/область
  • administrative_area_level_2 — район
  • locality — населённый пункт
  • postal_code — почтовый индекс
  • premise — здание или комплекс
  • subpremise — помещение внутри здания

Пример:

"types": ["street_address"]

или

"types": ["locality", "political"]

Иерархия типов адресных компонентов

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

Пример структуры компонента:

{
  "long_name": "Караганда",
  "short_name": "Караганда",
  "types": ["locality", "political"]
}

Часто встречающиеся типы компонентов

  • country — страна
  • administrative_area_level_1 — регион первого уровня
  • administrative_area_level_2 — район
  • locality — город
  • sublocality — микрорайон
  • postal_code — индекс
  • route — улица
  • street_number — номер здания

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

Поле geometry и типы точности

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

Типы location_type

  • ROOFTOP — точная геолокация до уровня здания
  • RANGE_INTERPOLATED — интерполированное значение между известными точками
  • GEOMETRIC_CENTER — геометрический центр объекта
  • APPROXIMATE — приблизительное местоположение

Пример:

"geometry": {
  "location": {
    "lat": 49.806,
    "lng": 73.085
  },
  "location_type": "ROOFTOP"
}

location_type напрямую влияет на степень доверия к результату.

Множественные результаты геокодирования

Геокодер может возвращать несколько вариантов для одного запроса. Это массив объектов, отсортированный по релевантности.

Пример:

[
  { formatted_address: "...", types: ["street_address"] },
  { formatted_address: "...", types: ["route"] },
  { formatted_address: "...", types: ["locality"] }
]

Каждый элемент массива представляет отдельную интерпретацию введённого запроса.

Поле partial_match

partial_match указывает, что результат соответствует запросу лишь частично. Это особенно характерно для неточных или неполных адресов.

Пример:

"partial_match": true

Наличие этого флага снижает достоверность результата и требует дополнительной проверки через address_components.

Взаимосвязь types и address_components

Различие между types результата и types компонентов является принципиальным:

  • types результата описывает общий характер объекта (например, город или улица)
  • types компонентов описывает составные части адреса

Это позволяет:

  • фильтровать результаты по уровню детализации
  • строить структурированные адресные модели
  • выполнять обратное геокодирование с разбором иерархии

Пример полного объекта результата

{
  "formatted_address": "Караганда, Казахстан",
  "place_id": "ChIExample123",
  "types": ["locality", "political"],
  "partial_match": false,
  "geometry": {
    "location": {
      "lat": 49.806,
      "lng": 73.085
    },
    "location_type": "APPROXIMATE"
  },
  "address_components": [
    {
      "long_name": "Караганда",
      "short_name": "Караганда",
      "types": ["locality", "political"]
    },
    {
      "long_name": "Казахстан",
      "short_name": "KZ",
      "types": ["country", "political"]
    }
  ]
}

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

Использование типов результатов позволяет:

  • определять уровень детализации введённого адреса
  • фильтровать только здания (street_address, premise)
  • выделять административные границы (locality, administrative_area_level_*)
  • отличать улицы от точек интереса
  • контролировать точность координат через location_type

Такая система типов формирует основу семантического анализа географических данных в Google Maps API.

Оглавление