API: адрес по коду ФИАС, ГАР, КЛАДР или кадастровому номеру

Находит адрес по идентификатору:

кадастровый номер (stead_cadnum, house_cadnum или flat_cadnum), только для России;
ФИАС-код, он же ГАР-код (fias_id), только для России;
КЛАДР-код (kladr_id), только для России;
Идентификатор OpenStreetMap (fias_id), только для Беларуси, Казахстана и Узбекистана;
Идентификатор GeoNames (geoname_id), для всех остальных стран.

По КЛАДР-коду ищет до улицы, по ФИАС-коду — до квартиры.

ФИАС-коды домов и квартир иногда меняются, а метод ищет только по актуальным кодам. Поэтому рекомендуем помимо ФИАС-кода сохранять адрес одной строкой — иначе не получится восстановить адрес, когда код изменится.

Как вызвать

Чтобы вызвать метод, и подтвердите почту.

Пример запроса:

            
                POST http://suggestions.dadata.ru/suggestions/api/4_1/rs/findById/address
            
            
                
                    { "query": "9120b43f-2fae-4838-a144-85e43c2bfb29" }

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Token ${API_KEY}" \ 
  -d '{ "query": "9120b43f-2fae-4838-a144-85e43c2bfb29" }' \
  http://suggestions.dadata.ru/suggestions/api/4_1/rs/findById/address

// https://github.com/hflabs/dadata-csharp

var token = "${API_KEY}";
var api = new SuggestClientAsync(token);
var result = await api.FindAddress("9120b43f-2fae-4838-a144-85e43c2bfb29");

// https://github.com/ekomobile/dadata
// Использует API-ключ из переменной окружения DADATA_API_KEY

import (
    "context"
    dadata "github.com/ekomobile/dadata/v2"
    "github.com/ekomobile/dadata/v2/api/suggest"
)

func main() {
    api := dadata.NewSuggestApi()
    query := "9120b43f-2fae-4838-a144-85e43c2bfb29"
    result, err := api.AddressByID(context.Background(), query)
}

var url = "http://suggestions.dadata.ru/suggestions/api/4_1/rs/findById/address";
var token = "${API_KEY}"; 
var query = "9120b43f-2fae-4838-a144-85e43c2bfb29";

var options = {
    method: "POST",
    mode: "cors",
    headers: {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": "Token " + token 
    },
    body: JSON.stringify({query: query})
}

fetch(url, options)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log("error", error));

// https://github.com/hflabs/dadata-php

$token = "${API_KEY}";
$dadata = new \Dadata\DadataClient($token, null);
$result = $dadata->findById("address", "9120b43f-2fae-4838-a144-85e43c2bfb29", 1);

# https://github.com/hflabs/dadata-py

from dadata import Dadata
token = "${API_KEY}"
dadata = Dadata(token)
result = dadata.find_by_id("address", "9120b43f-2fae-4838-a144-85e43c2bfb29")

Укажите при вызове:

Content-Type: application/json.
Accept: application/json.
${API_KEY} — API-ключ.

Тело запроса передавайте в кодировке UTF-8.

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

Название	Тип	Обяз.?	По умолч.	Описание
query	string	✓		Текст запроса
count	number		10	Количество результатов (максимум — 20)
language	string		ru	На каком языке вернуть результат (ru / en)
division	string		ADMINISTRATIVE	Административное либо муниципальное деление

Что в ответе

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

{
    "suggestions": [{
        "value": "г Москва, ул Снежная",
        "unrestricted_value": "129323, г Москва, ул Снежная",
        "data": {
            "postal_code": "129323",
            "country": "Россия",
            "country_iso_code": "RU",
            "federal_district": "Центральный",
            "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
            "region_kladr_id": "7700000000000",
            "region_iso_code": "RU-MOW",
            "region_with_type": "г Москва",
            "region_type": "г",
            "region_type_full": "город",
            "region": "Москва",
            "area_fias_id": null,
            "area_kladr_id": null,
            "area_with_type": null,
            "area_type": null,
            "area_type_full": null,
            "area": null,
            "city_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
            "city_kladr_id": "7700000000000",
            "city_with_type": "г Москва",
            "city_type": "г",
            "city_type_full": "город",
            "city": "Москва",
            "city_area": null,
            "city_district_fias_id": null,
            "city_district_kladr_id": null,
            "city_district_with_type": null,
            "city_district_type": null,
            "city_district_type_full": null,
            "city_district": null,
            "settlement_fias_id": null,
            "settlement_kladr_id": null,
            "settlement_with_type": null,
            "settlement_type": null,
            "settlement_type_full": null,
            "settlement": null,
            "street_fias_id": "9120b43f-2fae-4838-a144-85e43c2bfb29",
            "street_kladr_id": "77000000000268400",
            "street_with_type": "ул Снежная",
            "street_type": "ул",
            "street_type_full": "улица",
            "street": "Снежная",
            "house_fias_id": null,
            "house_kladr_id": null,
            "house_flat_count": null,
            "house_type": null,
            "house_type_full": null,
            "house": null,
            "block_type": null,
            "block_type_full": null,
            "block": null,
            "flat_fias_id": null,
            "flat_type": null,
            "flat_type_full": null,
            "flat": null,
            "flat_area": null,
            "square_meter_price": null,
            "flat_price": null,
            "postal_box": null,
            "fias_id": "9120b43f-2fae-4838-a144-85e43c2bfb29",
            "fias_code": null,
            "fias_level": "7",
            "fias_actuality_state": "0",
            "kladr_id": "77000000000268400",
            "capital_marker": "0",
            "okato": "45000000000",
            "oktmo": null,
            "tax_office": "7716",
            "tax_office_legal": "7716",
            "timezone": "UTC+3",
            "geo_lat": "55.8523692",
            "geo_lon": "37.6469407",
            "beltway_hit": "IN_MKAD",
            "beltway_distance": null,
            "metro": null,
            "qc_geo": "2",
            "qc_complete": null,
            "qc_house": null,
            "history_values": null,
            "unparsed_parts": null,
            "source": "г Москва, ул Снежная",
            "qc": null
        }
    }]
}

Название	Описание
Базовые поля, заполняются для всех тарифов
value	Адрес одной строкой (как показывается в списке подсказок)
unrestricted_value	Адрес одной строкой (полный, с индексом)

data.postal_code	Индекс
data.country	Страна
data.country_iso_code	ISO-код страны (двухсимвольный)
data.federal_district	Федеральный округ

data.region_fias_id	ФИАС-код региона
data.region_kladr_id	КЛАДР-код региона
data.region_iso_code	ISO-код региона
data.region_with_type	Регион с типом
data.region_type	Тип региона (сокращенный)
data.region_type_full	Тип региона
data.region	Регион

data.area_fias_id	ФИАС-код района в регионе
data.area_kladr_id	КЛАДР-код района в регионе
data.area_with_type	Район в регионе с типом
data.area_type	Тип района в регионе (сокращенный)
data.area_type_full	Тип района в регионе
data.area	Район в регионе

data.sub_area_fias_id	ФИАС-код мун. поселения
data.sub_area_kladr_id	КЛАДР-код мун. поселения
data.sub_area_with_type	Мун. поселение с типом
data.sub_area_type	Тип мун. поселения (сокращенный)
data.sub_area_type_full	Тип мун. поселения
data.sub_area	Мун. поселение

data.city_fias_id	ФИАС-код города
data.city_kladr_id	КЛАДР-код города
data.city_with_type	Город с типом
data.city_type	Тип города (сокращенный)
data.city_type_full	Тип города
data.city	Город

data.city_district_fias_id	ФИАС-код адм. района города
data.city_district_kladr_id	не заполняется
data.city_district_with_type	Адм. район города с типом
data.city_district_type	Тип адм. района города (сокращенный)
data.city_district_type_full	Тип адм. района города
data.city_district	Адм. район города

data.settlement_fias_id	ФИАС-код нас. пункта
data.settlement_kladr_id	КЛАДР-код нас. пункта
data.settlement_with_type	Населенный пункт с типом
data.settlement_type	Тип населенного пункта (сокращенный)
data.settlement_type_full	Тип населенного пункта
data.settlement	Населенный пункт

data.street_fias_id	ФИАС-код улицы
data.street_kladr_id	КЛАДР-код улицы
data.street_with_type	Улица с типом
data.street_type	Тип улицы (сокращенный)
data.street_type_full	Тип улицы
data.street	Улица

data.stead_fias_id	ФИАС-код земельного участка
data.stead_kladr_id	КЛАДР-код земельного участка
data.stead_type	= «уч»
data.stead_type_full	= «участок»
data.stead	номер земельного участка

data.house_fias_id	ФИАС-код дома
data.house_kladr_id	КЛАДР-код дома
data.house_type	Тип дома (сокращенный)
data.house_type_full	Тип дома
data.house	Дом

data.block_type	Тип корпуса/строения (сокращенный)
data.block_type_full	Тип корпуса/строения
data.block	Корпус/строение

data.entrance	не заполняется
data.floor	не заполняется

data.flat_fias_id	ФИАС-код квартиры
data.flat_type	Тип квартиры (сокращенный)
data.flat_type_full	Тип квартиры
data.flat	Квартира

data.room_fias_id	ФИАС-код комнаты
data.room_type	Тип комнаты (сокращенный)
data.room_type_full	Тип комнаты
data.room	Комната

data.postal_box	Абонентский ящик
data.fias_id	ФИАС-код (он же код ГАР) адреса для России. Идентификатор OpenStreetMap для Беларуси, Казахстана и Узбекистана. Для остальных стран — идентификатор объекта в базе GeoNames.
data.fias_code	Не заполняется, используйте fias_id
data.fias_level	Уровень детализации, до которого адрес найден в ФИАС (ГАР): 0 — страна 1 — регион 3 — район 4 — город 5 — район города 6 — населенный пункт 7 — улица 8 — дом 9 — квартира или комната 65 — планировочная структура 75 — земельный участок -1 — иностранный или пустой
data.kladr_id	КЛАДР-код
data.geoname_id	Идентификатор объекта в базе GeoNames. Для российских адресов не заполняется.
data.capital_marker	Признак центра района или региона: 1 — центр района (Московская обл, Одинцовский р-н, г Одинцово) 2 — центр региона (Новосибирская обл, г Новосибирск) 3 — центр района и региона (Томская обл, г Томск) 4 — центральный район региона (Тюменская обл, Тюменский р-н) 0 — ничего из перечисленного (Московская обл, г Балашиха)
data.okato	Код ОКАТО
data.oktmo	Код ОКТМО
data.tax_office	Код ИФНС для физических лиц
data.tax_office_legal	Код ИФНС для организаций

data.history_values[ ]	Список исторических названий объекта нижнего уровня. Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.

Дополнительные поля, заполняются в зависимости от тарифа Заполняются при выборе конкретной подсказки. До этого они пустые.
Все тарифы
data.geo_lat	Координаты: широта
data.geo_lon	Координаты: долгота
data.qc_geo	Код точности координат: 0 — точные координаты 1 — ближайший дом 2 — улица 3 — населенный пункт 4 — город 5 — координаты не определены
data.fias_actuality_state	Признак актуальности адреса в ФИАС 0 — актуальный 1–50 — переименован 51 — переподчинен 99 — удален
data.city_area	Административный округ (только для Москвы)

«Расширенный» и «Максимальный»
data.beltway_hit	Внутри кольцевой?
data.beltway_distance	Расстояние от кольцевой в километрах

Только «Максимальный»
data.stead_cadnum	Кадастровый номер земельного участка
data.house_cadnum	Кадастровый номер дома
data.flat_cadnum	Кадастровый номер квартиры
data.room_cadnum	Кадастровый номер комнаты
data.house_flat_count	Количество квартир в доме
data.flat_area	Площадь квартиры
data.square_meter_price	Рыночная стоимость м²
data.flat_price	Рыночная стоимость квартиры
data.timezone	Часовой пояс

data.metro[ ]	Список ближайших станций метро (до трёх штук)
└ name	— название станции
└ line	— название линии
└ distance	— расстояние до станции в километрах

Зарезервированы для автоматической обработки адресов через API стандартизации
data.qc_complete	не заполняется
data.qc_house	не заполняется
data.qc	не заполняется
data.source	не заполняется
data.unparsed_parts	не заполняется

Административное и муниципальное деление

Подсказки могут возвращать адрес в административном либо в муниципальном делении. Это регулирует параметр запроса division (виджет / API):

administrative — административное;
municipal — муниципальное.

Если параметр не задан, используется административное деление.

В муниципальном делении возвращаются поля area* (муниципальный район) и sub_area* (муниципальное поселение). Поля city_district* (административный район города), напротив, скрываются.

В административном делении возвращаются поля area* (административный район региона) и city_district* (административный район города). Поля sub_area* (муниципальное поселение), напротив, скрываются.

Координаты, площадь и стоимость

Координаты есть у 97% домов в Москве, 91% в Санкт-Петербурге, 69% в других городах-миллиониках и 47% по остальной России.

Площадь и стоимость есть у 70% квартир в России.

Источники данных

Федеральная информационная адресная система (ФИАС) Налоговой службы

Справочник индексов Почты России

Gazetteer Data и Postal Code Data от GeoNames

OpenStreetMap

ISO 3166

Примеры вызова

Ограничения

Длина запроса (параметр query) — не более 300 символов.

Количество запросов в день — в соответствии с тарифным планом.

Максимальная частота запросов — 30 в секунду с одного IP-адреса.

Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.

Стоимость

Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.