Компоненты адреса

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

Структура address_components

Каждый элемент массива address_components содержит следующие поля:

  • long_name — полное, человекочитаемое название компонента
  • short_name — сокращённое или стандартизированное значение
  • types — массив типов, определяющих роль компонента в адресе

Пример:

{
  "long_name": "Lenin Avenue",
  "short_name": "Lenin Ave",
  "types": ["route"]
}

Компоненты не привязаны к фиксированному порядку. Их семантика определяется исключительно набором types.

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

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

Географические и административные уровни

  • country — страна
  • administrative_area_level_1 — регион, область, штат
  • administrative_area_level_2 — район или эквивалент
  • locality — населённый пункт (город)
  • sublocality, sublocality_level_1 — части города или микрорайоны

Уличный уровень

  • route — улица, проспект
  • street_number — номер дома
  • premise — здание или комплекс
  • subpremise — квартира, офис, помещение

Почтовые и служебные данные

  • postal_code — почтовый индекс
  • postal_code_suffix — дополнительный сегмент индекса

Специальные типы

  • plus_code — код Open Location Code
  • intersection — пересечение дорог
  • establishment — организация или объект (например, торговый центр)

Полная структура ответа геокодера

Результат запроса геокодирования содержит не только address_components, но и дополнительные поля, которые используются совместно для формирования адреса:

  • formatted_address — строковое представление адреса
  • geometry — координаты и границы объекта
  • place_id — уникальный идентификатор места
  • types — тип объекта геокодирования

Пример объекта:

{
  "formatted_address": "Lenin Ave 10, Karaganda 100000, Kazakhstan",
  "place_id": "ChIJ...example",
  "types": ["street_address"],
  "address_components": [
    {
      "long_name": "10",
      "short_name": "10",
      "types": ["street_number"]
    },
    {
      "long_name": "Lenin Avenue",
      "short_name": "Lenin Ave",
      "types": ["route"]
    },
    {
      "long_name": "Karaganda",
      "short_name": "Karaganda",
      "types": ["locality"]
    },
    {
      "long_name": "Karaganda Region",
      "short_name": "Karaganda Region",
      "types": ["administrative_area_level_1"]
    },
    {
      "long_name": "Kazakhstan",
      "short_name": "KZ",
      "types": ["country"]
    }
  ]
}

Извлечение компонентов адреса в JavaScript

Работа с компонентами адреса обычно выполняется через обход массива address_components и фильтрацию по types.

function getComponent(components, type) {
  const component = components.find(item =>
    item.types.includes(type)
  );

  return component ? component.long_name : null;
}

Использование:

geocoder.geocode({ address: "Lenin Ave 10 Karaganda" }, (results, status) => {
  if (status === "OK") {
    const components = results[0].address_components;

    const streetNumber = getComponent(components, "street_number");
    const route = getComponent(components, "route");
    const city = getComponent(components, "locality");
    const country = getComponent(components, "country");

    console.log(streetNumber, route, city, country);
  }
});

Сборка адреса из компонентов

Компоненты адреса используются для построения пользовательских форматов отображения, независимых от локализации formatted_address.

function formatAddress(components) {
  const number = getComponent(components, "street_number");
  const street = getComponent(components, "route");
  const city = getComponent(components, "locality");

  return [street, number, city]
    .filter(Boolean)
    .join(", ");
}

Такой подход обеспечивает контроль над отображением адреса независимо от региональных стандартов Google.

Различие между formatted_address и address_components

formatted_address формируется системой автоматически и зависит от:

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

Пример:

  • Английская локализация: Lenin Ave 10, Karaganda 100000, Kazakhstan
  • Русская локализация: проспект Ленина, 10, Караганда 100000, Казахстан

address_components остаётся стабильной структурой, не зависящей от языка отображения.

Обратное геокодирование и компоненты

При обратном геокодировании (координаты → адрес) структура address_components становится основным источником данных для построения адреса.

geocoder.geocode({ location: { lat: 49.806, lng: 73.085 } }, (results, status) => {
  if (status === "OK") {
    const components = results[0].address_components;

    const country = getComponent(components, "country");
    const region = getComponent(components, "administrative_area_level_1");

    console.log(country, region);
  }
});

Иерархия административных уровней

Компоненты с administrative_area_level_* формируют вложенную структуру:

country
 └── administrative_area_level_1
      └── administrative_area_level_2
           └── locality
                └── sublocality

Эта модель позволяет корректно агрегировать данные для аналитики, фильтрации и построения географических сегментов.

Нормализация адресов через компоненты

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

  • различия в сокращениях (St vs Street)
  • языковые вариации
  • перестановка элементов адреса
  • отсутствие отдельных частей адреса

Алгоритм нормализации обычно включает:

  1. Извлечение ключевых типов
  2. Приведение short_name или long_name к единому стандарту
  3. Формирование канонической строки

Типичные ошибки при работе с компонентами

Игнорирование множественных типов

Один компонент может содержать несколько типов:

"types": ["sublocality", "sublocality_level_1"]

Поиск должен учитывать наличие типа в массиве, а не точное совпадение строки.

Предположение о фиксированном порядке

Порядок элементов в address_components не гарантирован, поэтому доступ по индексу приводит к ошибкам.

Использование только formatted_address

Полагание исключительно на строковое представление приводит к потере структурности и невозможности анализа адреса на уровне города или региона.

Использование в формах ввода адреса

Компоненты адреса применяются для автоматического заполнения форм:

  • улица → route
  • дом → street_number
  • город → locality
  • регион → administrative_area_level_1
  • индекс → postal_code

Пример интеграции:

function fillForm(components) {
  document.querySelector("#street").value =
    getComponent(components, "route") || "";

  document.querySelector("#house").value =
    getComponent(components, "street_number") || "";

  document.querySelector("#city").value =
    getComponent(components, "locality") || "";

  document.querySelector("#zip").value =
    getComponent(components, "postal_code") || "";
}

place_id как связующий идентификатор

place_id используется для устойчивой идентификации объекта независимо от изменения адресных компонентов.

Особенности:

  • не зависит от языка
  • не меняется при редактировании адреса
  • используется для повторных запросов к Places API
  • обеспечивает стабильную ссылку на объект

Роль компонентов в маршрутизации и аналитике

Структурированные адресные данные применяются в:

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

Компонентный подход позволяет рассматривать адрес не как строку, а как набор взаимосвязанных сущностей с чёткой иерархией и типизацией.

Оглавление