Адреса

Возвращает до 20 подходящих адресов (по умолчанию 10) из ГАР/ФИАС с разбором на составляющие (components), кодами (codes: индекс, КЛАДР, ОКАТО, ОКТМО), уровнем детализации и гео-координатами.

Параметры запроса

Срез по уровню · from_bound / to_bound

Чтобы вернуть только один уровень — задайте одинаковые from_bound и to_bound. Диапазон (например street→house) вернёт улицы и дома. Если задан только from_bound, выдача включает указанный уровень и все более глубокие.

// только УЛИЦЫ
{
  "query": "иркутск ленина",
  "from_bound": { "value": "street" },
  "to_bound": { "value": "street" }
}

// только ДОМА на улицах Ленина в Иркутске
{
  "query": "ленина",
  "locations": [{ "city": "Иркутск" }],
  "from_bound": { "value": "house" },
  "to_bound": { "value": "house" }
}

Автораспознавание ввода

Тип запроса определяется по содержимому query автоматически:

"38:36:000021"      // кадастровый префикс → подсказки по кварталу
"38:36:000021:9597" // полный кадастровый номер → конкретный объект
"664003"            // 6 цифр → поиск по почтовому индексу

Форма строки value · value_style

Необязательное поле value_style задаёт форму собранной строки value. natural (по умолчанию) — читаемая: «Шолоховский р-н, Газовый пер». fias — сокращённая форма ГАР с типом перед именем: «р-н Шолоховский, пер Газовый» (по правилам сокращённого наименования адресообразующих элементов, Приказ Минфина № 171н).

Фильтрация по территории

Тело запроса: { "query": "…", "locations": [...], "locations_boost": [...] }. Оба параметра — массив записей. Поля внутри одной записи объединяются по И, записи между собой — по ИЛИ.

kladr_id — один иерархический код КЛАДР любого уровня (регион / район / город / улица); уровень определяется автоматически.

// поднять выше — один код КЛАДР любого уровня (уровень определится сам)
"locations_boost": [{ "kladr_id": "3800000300000" }] // Иркутск
"locations_boost": [{ "kladr_id": "7700000000000" }] // вся Москва

// только Иркутск ИЛИ Татарстан
"locations": [{ "city": "Иркутск" }, { "region": "Татарстан" }]

// дом в конкретном городе (поля внутри записи = И)
"locations": [{ "city": "Казань", "street": "Баумана" }]

Пример

POST /v1/suggest/address                 // native
POST /suggestions/api/4_1/rs/suggest/address // dadata-формат

// тело одинаково для обоих URL
{
  "query": "москва тверская 7",
  "count": 5,
  "locations": [{ "region": "Москва" }] // фильтр: только Москва
}

Поля ответа

Адрес по идентификатору

Возвращает один точный адрес по его идентификатору. В поле query передайте одно из: fias_id (UUID из ФИАС), кадастровый номер или код КЛАДР. Ответ — одна запись в той же структуре, что в разделе «Адреса».

find работает не только по адресу. /v1/find/{домен} находит запись справочника по её коду или идентификатору: bank (по БИК), okved, okpd2, oktmo, fms_unit, fns_unit, car_brand. Ответ — та же структура, что у подсказок этого справочника, но одна запись по точному совпадению.

POST /v1/find/address
{ "query": "cb983f95-4865-4320-bba0-ab6edc396ba5" }

Стандартизация адреса

Приводит свободную строку адреса к структуре (как в разделе «Адреса»). Для пакетной очистки выгрузок: на вход — строка source или массив строк, на выходе — один разобранный адрес на каждую входную строку.

POST /v1/clean/address
{ "source": "мск тверская 7" }

// пакетно — массив строк (ответ придёт в плоском DaData-формате):
["мск тверская 7", "спб невский 1"]

Поля ответа

Адрес по координатам

Возвращает ближайшие адреса по широте и долготе в пределах заданного радиуса.

POST /v1/geolocate/address
{ "lat": 55.7558, "lon": 37.6173, "radius_meters": 100, "count": 1 }

Параметры запроса

Ответ — массив адресов в поле suggestions, каждый в той же структуре, что в разделе «Адреса».

Пример ответа

{
  "suggestions": [{
    "value": "г Москва, ул Тверская, д 7",
    "full": "125009, Москва г, ул Тверская, д 7",
    "level": "house",
    "geo": { "lat": 55.7558, "lon": 37.6173, "precision": "exact" }
  }]
}

Город по IP

Возвращает ближайший адрес по IP-адресу. IP передаётся query-параметром?ip=… (или заголовком X-Real-IP; при их отсутствии используется IP соединения). Метод принимает и GET, и POST. В ответе поле location — адрес в той же структуре, что в разделе «Адреса» (или null, если IP не распознан). Расходует тот же пул, что и подсказки.

Параметры запроса

Дополнительно ответ содержит объект network — данные о сети IP: оператор связи, номер автономной системы (ASN), тип сети и признак хостинга/VPN. Удобно для анти-фрода: сверить регион заказа с IP и отсечь запросы из дата-центров.

Поля ответа — network

POST /v1/iplocate/address?ip=92.53.96.1