Pay-as-you-go · платите за найденное

REST API геокодинга

Один запрос — координаты по адресу: широта и долгота, уровень точности координаты и административная иерархия из государственного реестра адресов. Адрес принимается строкой, разложенным по полям или пакетом до 1000 строк. Покрытие — Россия. Ответы «не найдено» и «найдено слишком грубо» не тарифицируются.

Открыть GUI О сервисе

Широта и долгота

Swagger + JSON

Покрытие: Россия

Быстрый старт

Начните использовать API геокодинга за три шага

Изучите эндпоинты

В Swagger ниже доступны корневой поиск, structured, batch, place и postcode — с параметрами и примерами ответов.

Протестируйте

Выполните GET /api/geocodeforward?text=Москва, Тверская 1 — получите варианты с координатами и уровнем точности.

Интегрируйте

Разбирайте precision и layer в своей логике и обязательно показывайте поле attribution.

Эндпоинты

Базовый адрес: /api/geocodeforward

GET

/api/geocodeforward

Адрес одной строкой

Свободная форма записи: text=Москва, Тверская 1. Подходит, когда адрес пришёл из формы или из чужой системы одним полем.

text — адресная строка
size — сколько вариантов вернуть
exactOnly — оставить только точные попадания в дом

GET

/api/geocodeforward/structured

Адрес по полям

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

address — улица и дом
locality — населённый пункт
region — субъект РФ
postalCode — почтовый индекс

POST

/api/geocodeforward/batch

Пакет адресов

До 1000 строк за один вызов, ответ строго в порядке запроса. Единиц работы столько, сколько адресов реально найдено.

queries — массив адресных строк
sizePerQuery — вариантов на строку
exactOnly — только точные попадания

GET

/api/geocodeforward/place

Карточка по идентификатору

Идентификатор присвоен государственным реестром и стабилен навсегда: он вернёт тот же самый объект, тогда как повторный поиск по строке со временем может дать другой вариант.

placeId — значение из поля placeId предыдущего ответа
includeBoundary — граница в GeoJSON, +1 единица работы

GET

/api/geocodeforward/postcode

Что относится к индексу

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

code — ровно шесть цифр
size — сколько объектов вернуть

ЦЕНА

по тарифам, не по вызовам

Каждый режим — свой тариф

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

Актуальные цены — на странице «Тарифы»

Возможности API

Что делает API геокодинга удобным для интеграции

REST + JSON

GET-запросы и ответы в JSON — без промежуточных слоёв.

Координаты WGS 84

Широта и долгота в той же системе, что у GPS и у карт.

Уровень точности

precision — чья это координата: дома, улицы или города.

Что именно найдено

layer: дом, улица, населённый пункт, район или регион.

Иерархия из реестра

Регион, район, населённый пункт и улица — выписка, а не вычисление.

Пакет до 1000 адресов

Один вызов вместо тысячи, порядок ответа совпадает с порядком запроса.

Swagger

Спецификация OpenAPI и примеры запросов на двух языках.

Стабильный placeId

Сохраните идентификатор — получите тот же объект позже.

Уровни точности

Поле precision — читать обязательно: координата без него неполна

Значение	Чья это координата	Практический смысл
exact	Самого дома, взята из данных.	Годится для любой задачи, включая доставку до подъезда и расчёт расстояний.
range	Вычислена между соседними домами — либо совпадение номера было неполным: спрашивали «13к2», в реестре дом заведён одной записью «13».	В нужный квартал и на нужную сторону улицы попадает, в конкретное здание — нет. Нужны только буквальные совпадения — включите `exactOnly`.
street	Центра улицы: дома в реестре нет.	Осмысленный ответ «улица найдена, дом не заведён». Самый грубый уровень, который прямой геокодинг ещё отдаёт.
locality	Центра населённого пункта: улицы в реестре нет.	Как адрес уже не читается — «где-то в этом городе». До клиента не доходит: такой запрос заканчивается ответом 404 и не тарифицируется.
area	Центра района или региона.	Самый грубый из содержательных уровней. Так же, как `locality`, до клиента не доходит.
none	Уровень неизвестен.	Координате верить нельзя. Значение существует, чтобы неизвестное не трактовалось молча как точное; наружу такие объекты не отдаются.

Уровни упорядочены от лучшего к худшему — и на это можно опираться в коде: проверка «координата не хуже центра улицы» пишется одним сравнением, без перечисления значений. Названия намеренно совпадают по смыслу с распространёнными геокодерами, чтобы переходящему клиенту не пришлось переписывать разбор ответа.

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

В каждом успешном ответе есть поле attribution: адресные данные — ГАР/ФИАС (ФНС России), координаты — © участники OpenStreetMap (ODbL). Его отображение у себя обязательно: этого требует лицензия исходных наборов данных.

Пакетный режим

До 1000 адресов за один вызов — и счёт по числу найденных, а не присланных

POST

/api/geocodeforward/batch

Запрос

{
  "queries": [
    "Казань, улица Баумана, 13",
    "Москва, Тверская 1",
    "нераспознаваемая строка из выгрузки"
  ],
  "sizePerQuery": 1
}

Пакет больше предельного размера отклоняется целиком с кодом 400: лишние строки не отбрасываются молча, иначе вы недосчитались бы результатов, не узнав об этом.

200

ответ и счёт

Что придёт

items — по одному элементу на КАЖДУЮ присланную строку, строго в порядке запроса
items[].query — исходная строка рядом с результатом: склейка по позиции остаётся возможной, но перестаёт быть единственным способом
items[].matches — пустой список у ненайденной строки; это нормальный исход, а не ошибка
requested, found, billedUnits — сверить счёт, не заглядывая в личный кабинет

В примере слева прислано 3 строки, найдено 2 — списано 2 единицы. Пакет, в котором не нашлось ничего, не тарифицируется целиком.

Нужна помощь с интеграцией?

Используйте Swagger ниже и примеры параметров. Для теста подойдут Postman, Thunder Client или curl.

Swagger документация API

Откройте спецификацию OpenAPI, чтобы проверить запросы и ответы API геокодинга.

Тарификация по результату

Списание происходит только за найденный адрес, прошедший порог качества

Код	Списание	Когда возникает
200	Да	Адрес найден, координата не грубее центра улицы. Единственный оплачиваемый исход. В пакетном режиме единиц столько, сколько строк реально найдено.
400	Нет	Некорректный ввод: пустая или слишком короткая строка, запрос без единого заполненного поля, индекс не из шести цифр, пакет больше предельного размера.
404	Нет	Адрес не найден либо найденное оказалось грубее уровня улицы. Один код на оба случая: практический исход одинаков — пригодных координат нет, а причина написана в теле ответа.
503	Нет	Сервис геокодинга временно недоступен. Сбой на нашей стороне не оплачивается.

Коды 401 (нет действительного API-ключа), 402 (недостаточно кредитов) и 429 (превышено ограничение частоты запросов) возвращаются до начала работы и также не тарифицируются.

Почему выбирают наш API

Преимущества REST API геокодинга для интеграции

Счёт предсказуем

Платите за найденные адреса, а не за обращения. Массовое геокодирование грязной базы не превращается в оплату пустых ответов.

Приблизительное помечено явно

precision и layer приходят в каждом варианте, а результаты грубее центра улицы не отдаются вовсе — и не тарифицируются. Нужны только буквальные попадания в дом — включите exactOnly.

Простая интеграция

Понятные GET-эндпоинты и параметры. Подключается любым HTTP-клиентом без SDK, форма найденного варианта одинакова во всех режимах — и в поиске по строке, и по полям, и внутри пакета.

Официальная иерархия

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

Готовы подключить геокодинг?

Используйте API для массового геокодирования базы адресов или откройте GUI, чтобы проверить пару адресов вручную.

Открыть GUI