ГАР/ФИАС API — подсказки и нормализация адресов России

Русский · English

Готовые примеры работы с API ФИАС (ГАР — Государственный адресный реестр) на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP. Автодополнение адреса по мере ввода, полный поиск по справочнику адресов России, нормализация адреса до кода ФИАС, получение ОКТМО по адресу, ОКАТО, кода КЛАДР по адресу, почтового индекса и кода ИФНС.

Сервис работает по локальной копии базы ГАР — без обращения к внешним источникам, отсюда время ответа в единицы миллисекунд.

Каждый пример запускается сразу — без регистрации, без ключа, без карты. В коде зашит публичный демо-ключ.

git clone https://github.com/atlorium-api/gar-fias-address-api-client
cd gar-fias-address-api-client/python && pip install -r requirements.txt && python main.py

Демо-ключ: ответы сгенерированы (моки), не реальные данные.

Ввод пользователя: «москва тверская»

Подсказки (выпадающий список под полем ввода):
  > 1. Новосибирская обл, г Новосибирск, ул Пролетарская пр., д. 139  [дом]
    2. Республика Татарстан, г Пенза, ул пр. Железнодорожная, д. 126  [дом]
    3. Новосибирская обл, г Оренбург, ул ул. Первомайская, д. 54  [дом]
    4. Республика Татарстан, г Краснодар, ул Лесной площадь, д. 50  [дом]
    5. Республика Татарстан, г Ярославль, ул Коммунальная площадь, д. 25  [дом]
    6. Новосибирская обл, г Новокузнецк, ул Пионерская пл., д. 141  [дом]
    7. Республика Татарстан, г Пермь, ул пл. Садовая, д. 10  [дом]

Всего подсказок: 7 · 7 мс

── Карточка для сохранения в БД ──────────────────────────────
  objectGuid (код ФИАС): b82c94b5-5415-4c02-b7cb-7e1ab189636e   ← первичный ключ адреса
  objectId:              41200010
  Полный адрес:          Новосибирская обл, г Рязань, ул ул. Садовый, д. 186
  Тип объекта:           дом
  Код региона:           54

  Иерархия (регион → город → улица → дом):
    1. Новосибирская обл
    2. г Рязань
    3. ул ул. Садовый
    4. д. 186

  Коды (хранить денормализованно рядом с GUID):
    Почтовый индекс    328391
    ОКТМО              83736741
    ОКАТО              51222794
    Код ИФНС           6016
    Код КЛАДР          74847877663722792

Адрес нормализован. В БД уходит objectGuid, а не строка пользователя:
«ул. Лесная», «улица Лесная» и «Лесная ул.» — это один и тот же objectGuid.

Демо-ключ отвечает правдоподобными моками, а не реальными данными ГАР. Именно поэтому на запрос «москва тверская» выше приезжает Новосибирск. Подробно и честно про странности песочницы — ниже отдельным разделом. Подставьте боевой ключ — тот же код начнёт возвращать настоящий ГАР/ФИАС.

Зачем это нужно

Форма заказа, доставки или регистрации, где пользователь вводит адрес. Чистка адресов в CRM. Заполнение госформ и налоговой отчётности, где нужны ОКТМО и код ИФНС. Логистика, где нужен почтовый индекс. Везде, где адрес — не просто строка, а сущность, которую надо сопоставить с государственным реестром.

Примеры не просто печатают JSON, а применяют данные: в каждом есть функция suggestAddress(), которая доводит автодополнение до конца — в два шага, ровно как это делает связка «фронтенд + бэкенд» в реальном приложении:

Что видит пользователь. По префиксу, который он набрал, дёргаем /api/Gar/suggest и печатаем пронумерованный список подсказок — это выпадашка под полем ввода.
Что сохраняет бэкенд. У выбранной подсказки берём objectGuid и дёргаем /api/Gar/object/{guid} — получаем канонический адрес, иерархию и коды.

Главное: в БД нельзя хранить строку, которую набрал пользователь

Хранить надо objectGuid — код ФИАС, стабильный идентификатор адресного объекта. А рядом денормализованно: fullAddress, почтовый индекс, ОКТМО, ОКАТО, код ИФНС, код КЛАДР. Что это даёт:

Адреса в базе не расходятся. «ул. Лесная», «улица Лесная» и «Лесная ул.» — это один objectGuid, а не три разные записи. Дедупликация клиентов, складов и точек доставки перестаёт быть археологией.
Индекс и ОКТМО не надо спрашивать у пользователя — они приезжают вместе с адресом. Меньше полей в форме — выше конверсия.
Код ИФНС и ОКТМО нужны для налоговой отчётности и госформ. Руками их никто правильно не заполнит, а из ГАР они приходят сами.

Что именно не так с песочницей (читайте до того, как удивиться)

Демо-ключ — это генератор правдоподобных данных, а не копия реальной базы. Мы не подгоняли пример под красивый вывод, поэтому вы увидите ровно то, что видим мы:

Что происходит	Почему
Подсказки не релевантны запросу — на «москва тверская» приезжают адреса из Новосибирска	Мок не ищет по строке, а генерирует правдоподобные адреса по seed от запроса
Регион и город в одной строке не совпадают («Республика Татарстан, г Пенза»)	Компоненты адреса генерируются независимо друг от друга
Параметр `limit` игнорируется — просишь 3, приходит 7	Мок отдаёт фиксированное количество элементов
`object/{guid}` возвращает другой `objectId` и адрес, чем те, что пришли из `suggest`	Карточка тоже генерируется, а не поднимается по GUID из хранилища

Что при этом работает и полезно:

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

Чего на песочнице делать нельзя: проверять качество поиска и релевантность подсказок. Для этого нужен боевой ключ — с ним всё это настоящий ГАР/ФИАС.

Быстрый старт за 60 секунд

Проверить API вообще без клонирования:

curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
     "https://atlorium.com/api/Gar/suggest?query=москва%20тверская&limit=5"

Язык	Запуск	Требуется
Python	`pip install -r requirements.txt && python main.py`	Python 3.10+
TypeScript / Node.js	`npm install && npm start`	Node.js 20+
Go	`go run .`	Go 1.22+
Java	`java Main.java`	JDK 17+ (без зависимостей)
C#	`dotnet run`	.NET 8+
PHP	`php main.php`	PHP 8.1+

Передать свой адрес аргументом, вторым аргументом — номер выбранной подсказки:

python main.py "санкт-петербург невский" 2

Аутентификация

Ключ передаётся в заголовке Authorization:

Authorization: Bearer ВАШ_КЛЮЧ

Ключ	Что делает
`ak_sandbox_demo_mockdata_v1`	Демо-ключ. Публичный, один на всех. Возвращает моки, денег не списывает, регистрации не требует. Ответы детерминированы — на них можно писать стабильные тесты.
Боевой ключ	Реальные данные ГАР/ФИАС. Получить в личном кабинете: atlorium.com

Переход на боевой ключ не требует правок в коде — все примеры читают переменную окружения:

export ATLORIUM_API_KEY="ak_ваш_боевой_ключ"

Каждый ответ песочницы помечен заголовком X-Atlorium-Sandbox: true — перепутать мок с реальными данными невозможно.

Эндпоинты

Базовый адрес: https://atlorium.com

Метод	Путь	Назначение
`GET`	`/api/Gar/suggest`	Автодополнение: быстрые подсказки по префиксу для выпадашки под полем ввода
`GET`	`/api/Gar/search`	Полный поиск: то же, но с ОКТМО, ОКАТО, почтовым индексом и кодом региона
`GET`	`/api/Gar/object/{guid}`	Карточка адресного объекта по GUID ФИАС
`GET`	`/api/Gar/object/id/{objectId}`	Карточка адресного объекта по числовому `objectId`
`GET`	`/api/Gar/hierarchy/{objectId}`	Иерархия (путь) объекта: регион → город → улица → дом
`GET`	`/api/Gar/children/{parentObjectId}`	Дочерние объекты: улицы города, дома улицы
`GET`	`/api/Gar/regions`	Список регионов РФ
`GET`	`/api/Gar/stats`	Статистика адресной базы
`GET`	`/api/Gar/region/{regionCode}/stats`	Статистика по конкретному региону

`GET /api/Gar/suggest`

Быстрые подсказки для автодополнения. Отдаёт минимум полей — ровно то, что нужно показать в выпадающем списке.

Параметр	Где	Тип	Описание
`query`	query	string	Префикс адреса, который набирает пользователь. Например, `москва тверская`. Минимум 2 символа, иначе `400`
`limit`	query	int	Сколько подсказок вернуть. По умолчанию `7`

`GET /api/Gar/search`

Полный поиск. В отличие от suggest, каждый результат сразу содержит regionCode, postalCode, oktmo и okato — второй запрос за кодами не нужен.

Параметр	Где	Тип	Описание
`query`	query	string	Поисковая строка. Например, `Тверская`
`limit`	query	int	Максимум результатов. По умолчанию `10`

`GET /api/Gar/object/{guid}`

Карточка объекта по GUID ФИАС — то, чем заканчивается автодополнение.

Параметр	Где	Тип	Описание
`guid`	путь	string (uuid)	GUID ФИАС адресного объекта. Берётся из `objectGuid` подсказки или результата поиска

`GET /api/Gar/object/id/{objectId}`

То же самое, но по внутреннему числовому идентификатору ГАР.

Параметр	Где	Тип	Описание
`objectId`	путь	int	Числовой `objectId` адресного объекта

`GET /api/Gar/hierarchy/{objectId}`

Путь объекта вверх по дереву: от дома до региона. Нужен, чтобы разложить адрес на компоненты.

Параметр	Где	Тип	Описание
`objectId`	путь	int	Числовой `objectId` адресного объекта

`GET /api/Gar/children/{parentObjectId}`

Дочерние объекты: улицы указанного города, дома указанной улицы. Пригодно для каскадных выпадающих списков «регион → город → улица».

Параметр	Где	Тип	Описание
`parentObjectId`	путь	int	`objectId` родительского объекта
`limit`	query	int	Максимум дочерних объектов. По умолчанию `50`

`GET /api/Gar/regions`

Список регионов РФ. Параметров нет.

`GET /api/Gar/stats`

Статистика адресной базы: объём загруженного среза ГАР. Параметров нет.

`GET /api/Gar/region/{regionCode}/stats`

Статистика по одному региону.

Параметр	Где	Тип	Описание
`regionCode`	путь	string	Код региона РФ. Например, `54` — Новосибирская область, `77` — Москва

Поля ответа

Ниже — поля, снятые с живых ответов API. Полная схема всех эндпоинтов — в Swagger и OpenAPI-спеке.

Обратите внимание на асимметрию: у suggest элементы лежат в items, у search — в results. Это не опечатка, это разные ответы.

`suggest`

Поле	Тип	Что содержит
`query`	string	Исходная строка запроса
`items`	array	Подсказки (см. ниже)
`count`	int	Сколько подсказок нашлось
`elapsedMs`	int	Время поиска по локальной базе, мс

Элемент items[]:

Поле	Тип	Что содержит
`text`	string	Готовая к показу строка адреса
`objectId`	int	Внутренний числовой идентификатор ГАР
`objectGuid`	string (uuid)	Код ФИАС. Именно это значение хранится в вашей БД
`objectType`	string	Тип объекта: `дом`, `улица`, `город` и т.д.

`search`

Поле	Тип	Что содержит
`query`	string	Исходная строка запроса
`results`	array	Результаты (см. ниже)
`count`	int	Сколько результатов нашлось
`elapsedMs`	int	Время поиска, мс

Элемент results[]:

Поле	Тип	Что содержит
`fullAddress`	string	Полный адрес одной строкой
`objectType`	string	Тип объекта
`objectGuid`	string (uuid)	Код ФИАС
`objectId`	int	Числовой идентификатор ГАР
`regionCode`	string	Код региона РФ
`postalCode`	string	Почтовый индекс
`oktmo`	string	ОКТМО — код муниципального образования
`okato`	string	ОКАТО — код административно-территориального деления

`object/{guid}` и `object/id/{objectId}`

Поле	Тип	Что содержит
`objectId`	int	Числовой идентификатор ГАР
`objectGuid`	string (uuid)	Код ФИАС
`fullAddress`	string	Канонический полный адрес
`objectType`	string	Тип объекта
`regionCode`	string	Код региона РФ
`hierarchy`	array	Разложение адреса по уровням (см. ниже)
`parameters`	array	Коды адреса (см. ниже)
`elapsedMs`	int	Время выборки, мс

Элемент hierarchy[] — уровень от региона к дому:

Поле	Тип	Что содержит
`objectId`	int	Идентификатор объекта этого уровня
`displayName`	string	Название: `Новосибирская обл`, `г Рязань`, `ул ул. Садовый`, `д. 186`

Элемент parameters[] — это и есть «нормализованный адрес для БД»: пары «тип — значение».

`typeId`	`typeName`	Пример `value`
`5`	Почтовый индекс	`328391`
`6`	ОКТМО	`83736741`
`7`	ОКАТО	`51222794`
`8`	Код ИФНС	`6016`
`10`	Код КЛАДР	`74847877663722792`

`hierarchy/{objectId}`

Поле	Тип	Что содержит
`objectId`	int	Идентификатор запрошенного объекта
`path`	array	Путь от региона до объекта: элементы `{ objectId, displayName }`
`elapsedMs`	int	Время выборки, мс

Заметьте: у карточки объекта разложение лежит в hierarchy, а у отдельного эндпоинта /hierarchy/{objectId} — в path.

Обработка ошибок

Код	Причина	Что делать
`400`	Неверный запрос: пустая строка поиска, некорректный GUID или `objectId`	Проверьте параметры запроса
`401`	Ключ отсутствует, просрочен или недействителен	Проверьте заголовок `Authorization`
`402`	Недостаточно кредитов на балансе	Пополнить на atlorium.com
`404`	Адресный объект не найден	GUID корректен, но такого объекта в ГАР нет. Выборка по базе уже выполнена, поэтому запрос тарифицируется
`429`	Превышен rate-limit	Повторить с задержкой. Для автодополнения — обязательно ставьте debounce на поле ввода
`500`	Внутренняя ошибка при обращении к адресной базе	Повторить позже. За сбой на нашей стороне деньги не списываются

Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.

Цены и лимиты

Оплата pay-as-you-go, без подписки: платите за выполненные запросы. Обратите внимание: запрос карточки объекта тарифицируется и тогда, когда объект не нашёлся (404) — выборка по базе уже сделана. Некорректный ввод (400) и внутренняя ошибка (500) не списываются.

Практический совет по автодополнению: ставьте debounce 250–300 мс на поле ввода и не дёргайте suggest на каждое нажатие клавиши. Иначе один введённый адрес превратится в десяток запросов вместо двух-трёх.

Актуальные цены и лимиты: atlorium.com/pricing

Частые вопросы

Что такое ГАР и чем он отличается от ФИАС? ГАР (Государственный адресный реестр) — это система, которая с 2021 года пришла на смену ФИАС. Идентификаторы (GUID) при этом остались прежними, поэтому в обиходе «код ФИАС» и «GUID ГАР» — одно и то же, и мы используем оба названия.

Почему нельзя просто хранить адрес строкой? Потому что «ул. Лесная», «улица Лесная» и «Лесная ул.» — это одна улица и три разные строки. Через полгода в базе будет три клиента вместо одного, а сверка с чьей-то ещё базой станет невозможна. objectGuid решает это радикально: он один на объект и не меняется.

Как получить ОКТМО по адресу? Найдите объект через suggest или search, затем запросите /api/Gar/object/{guid} — ОКТМО придёт в массиве parameters (typeId: 6). У search ОКТМО есть прямо в результате, без второго запроса.

Как получить код КЛАДР по адресу? Так же — parameters, typeId: 10. КЛАДР — устаревший классификатор, но его до сих пор требуют многие учётные системы и госформы, поэтому ГАР продолжает его отдавать.

Чем suggest отличается от search? suggest — для выпадашки: минимум полей, максимум скорости, элементы в items. search — для серверной обработки: те же адреса плюс ОКТМО, ОКАТО, индекс и код региона сразу в ответе, элементы в results.

Данные приходят из интернета? Нет. Сервис работает по локальной копии базы ГАР, поэтому отвечает за единицы миллисекунд и не зависит от доступности внешних сервисов.

Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но возвращает моки, а не реальные адреса (см. раздел про песочницу выше).

Другие API Atlorium

Адрес редко живёт сам по себе — обычно рядом лежат телефон, почта и реквизиты. Из того же аккаунта и тем же ключом доступны:

Стандартизация адреса — разбор строки на компоненты и оценка качества
Погодные данные — текущие условия по координатам
Валидация телефона — формат, тип номера, оператор диапазона
Разбор cron-выражений — валидация расписания и ближайшие запуски с учётом таймзоны
Проверка почты — синтаксис, MX-записи, одноразовые адреса
Проверка SSL-сертификата — срок действия, SAN, цепочка доверия

Полный каталог — atlorium.com

Ссылки

Документация API (Swagger): atlorium.com/garAPI
Описание сервиса: atlorium.com/garDescription
Веб-интерфейс: atlorium.com/garGUI
OpenAPI-спецификация: gar_ru.json
Поддержка: support@atlorium.com

Лицензия

MIT — берите код и используйте как хотите, в том числе в коммерческих проектах.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
csharp		csharp
go		go
java		java
node		node
php		php
python		python
.gitignore		.gitignore
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md

Navigation Menu

Uh oh!

Repository files navigation

ГАР/ФИАС API — подсказки и нормализация адресов России

Зачем это нужно

Главное: в БД нельзя хранить строку, которую набрал пользователь

Что именно не так с песочницей (читайте до того, как удивиться)

Быстрый старт за 60 секунд

Аутентификация

Эндпоинты

`GET /api/Gar/suggest`

`GET /api/Gar/search`

`GET /api/Gar/object/{guid}`

`GET /api/Gar/object/id/{objectId}`

`GET /api/Gar/hierarchy/{objectId}`

`GET /api/Gar/children/{parentObjectId}`

`GET /api/Gar/regions`

`GET /api/Gar/stats`

`GET /api/Gar/region/{regionCode}/stats`

Поля ответа

`suggest`

`search`

`object/{guid}` и `object/id/{objectId}`

`hierarchy/{objectId}`

Обработка ошибок

Цены и лимиты

Частые вопросы

Другие API Atlorium

Ссылки

Лицензия

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ГАР/ФИАС API — подсказки и нормализация адресов России

Зачем это нужно

Главное: в БД нельзя хранить строку, которую набрал пользователь

Что именно не так с песочницей (читайте до того, как удивиться)

Быстрый старт за 60 секунд

Аутентификация

Эндпоинты

GET /api/Gar/suggest

GET /api/Gar/search

GET /api/Gar/object/{guid}

GET /api/Gar/object/id/{objectId}

GET /api/Gar/hierarchy/{objectId}

GET /api/Gar/children/{parentObjectId}

GET /api/Gar/regions

GET /api/Gar/stats

GET /api/Gar/region/{regionCode}/stats

Поля ответа

suggest

search

object/{guid} и object/id/{objectId}

hierarchy/{objectId}

Обработка ошибок

Цены и лимиты

Частые вопросы

Другие API Atlorium

Ссылки

Лицензия

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`GET /api/Gar/suggest`

`GET /api/Gar/search`

`GET /api/Gar/object/{guid}`

`GET /api/Gar/object/id/{objectId}`

`GET /api/Gar/hierarchy/{objectId}`

`GET /api/Gar/children/{parentObjectId}`

`GET /api/Gar/regions`

`GET /api/Gar/stats`

`GET /api/Gar/region/{regionCode}/stats`

`suggest`

`search`

`object/{guid}` и `object/id/{objectId}`

`hierarchy/{objectId}`