Документация API Adresly

Adresly — один API для трёх задач: подсказки адресов и индексов, геокодирование в обе стороны и расчёт маршрутов. Запросы — HTTP POST с JSON-телом, ответы — JSON. Один токен открывает все эндпоинты. Объект адреса содержит полный набор полей — от региона до дома, с кодами ФИАС и координатами.

Частота — до 240 запросов в минуту с одного IP на ключ, объём — суточный лимит единиц тарифа, у организаций ещё суточный потолок обновлений сведений (см. тарифы и лимиты).

Базовый URL
https://api.adresly.ru

Хотите попробовать запросы без регистрации? Откройте песочницу — там можно дёргать живой API с предзаполненными примерами.

Подключение к Tilda, WordPress, 1С-Битрикс, Битрикс24 и Google Таблицам — готовый код и инструкции на странице «Интеграции».

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

Каждый запрос требует заголовок Authorization: Token <ваш токен>. Выпустить и посмотреть токен — в ЛК. Заголовок Bearer <токен> тоже поддерживается.

bash
curl -s "https://api.adresly.ru/v1/rs/suggest/address" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{"query":"мск тверс"}'

Ошибки

Все ошибки возвращаются как JSON { "error": "...", "message": "..." } с подходящим HTTP-кодом.

HTTPerrorКогда
400bad_requestНевалидный JSON или параметры запроса (подробности — в message).
400matrix_too_largesources × destinations превышает 10 000 пар.
401missing_tokenНе передан заголовок Authorization.
401invalid_tokenТокен не найден или отозван.
402insufficient_balanceПакетная обработка: на рублёвом балансе не хватает денег на весь пакет (need_kopecks, balance_kopecks). Ничего не списано.
403endpoint_not_publicСервис недоступен публичному ключу виджета (маршруты, матрица, пакетная обработка, стандартизация ФИО, организации) — вызывайте секретным ключом со своего сервера.
429limit_exceededДостигнут суточный лимит тарифа (поле scope: total — суммарный в единицах, routing — число маршрутов и матриц). На платном тарифе первое превышение в сроке тарифа включает разовый овердрафт +20 % до конца суток (поле overdraft: active — уже действует и исчерпан, used — в этом сроке уже был). Восстанавливается в 00:00 по МСК.
429rate_limitedСлишком часто: больше 240 запросов в минуту с одного IP для этого ключа. Повторите через retry_after секунд (также в заголовке Retry-After).
429party_fetch_limitОрганизации: исчерпан потолок обновлений сведений в сутки по тарифу, а этой организации нет в сохранённых. Единицы не списываются; восстанавливается в 00:00 по МСК.
422unresolved_pointНе удалось геокодировать одну из точек маршрута (point_index — её номер).
422unresolved_sourceНе удалось геокодировать один из sources матрицы.
422unresolved_destinationНе удалось геокодировать одно из destinations матрицы.
500internal_errorВнутренняя ошибка сервиса. Повторите запрос позже.
502osrm_errorОшибка маршрутизатора OSRM (точка вне поддерживаемой страны и т. п.).
503overloadedСервис перегружен. Повторите запрос через Retry-After секунд.
503party_unavailableОрганизации: реестр временно недоступен (сбой, исчерпана квота или закончились средства у поставщика сведений — 402 эти ручки не отдают), а сохранённой копии сведений нет. Единицы не списываются. Повторите через Retry-After секунд.

Объект адреса (data)

Подсказки адресов, подсказки индексов, геокодирование и обратное геокодирование возвращают элементы suggestions[].data одного формата — ниже описано каждое поле. Поля, для которых пока нет источника данных, всегда возвращаются со значением null (это отмечено в описании) — по мере подключения справочников они начнут заполняться без изменения формата.

ПолеТипОписание
postal_codestringПочтовый индекс. Берётся у дома (у длинной улицы индексов несколько); если у дома его в ГАР нет — null.
countrystringСтрана. Всегда «Россия».
country_iso_codestringКод страны по ISO 3166-1: «RU».
federal_districtstringФедеральный округ («Центральный», «Уральский», …).
region_fias_idstringКод ФИАС региона. Заполняется, когда сама подсказка уровня региона.
region_kladr_idstringКод КЛАДР региона. Заполняется из полного ГАР.
region_iso_codestringКод региона по ISO 3166-2 («RU-MOW», «RU-SVE»).
region_with_typestringРегион с типом («Московская обл», «г Москва»).
region_typestringТип региона, кратко («обл», «респ», «край», «г»).
region_type_fullstringТип региона полностью («область», «республика», «город»).
regionstringРегион без типа («Московская», «Татарстан»).
area_fias_idstringКод ФИАС района в регионе. Заполняется из полного ГАР.
area_kladr_idstringКод КЛАДР района в регионе. Заполняется из полного ГАР.
area_with_typestringРайон в регионе с типом («Динской р-н»). Заполняется из полного ГАР.
area_typestringТип района, кратко («р-н»). Заполняется из полного ГАР.
area_type_fullstringТип района полностью («район»). Заполняется из полного ГАР.
areastringРайон в регионе без типа. Заполняется из полного ГАР.
sub_area_fias_idstringКод ФИАС поселения (муниципальное деление). Заполняется из полного ГАР при division=municipal.
sub_area_kladr_idstringКод КЛАДР поселения. Заполняется из полного ГАР при division=municipal.
sub_area_with_typestringПоселение с типом. Заполняется из полного ГАР при division=municipal.
sub_area_typestringТип поселения, кратко. Заполняется из полного ГАР при division=municipal.
sub_area_type_fullstringТип поселения полностью. Заполняется из полного ГАР при division=municipal.
sub_areastringПоселение без типа. Заполняется из полного ГАР при division=municipal.
city_fias_idstringКод ФИАС города. Заполняется, когда сама подсказка уровня города; у Москвы, Санкт-Петербурга и Севастополя — код региона.
city_kladr_idstringКод КЛАДР города. Заполняется из полного ГАР; у Москвы, Санкт-Петербурга и Севастополя — код региона.
city_with_typestringГород с типом («г Москва»).
city_typestringТип города, кратко («г»).
city_type_fullstringТип города полностью («город»).
citystringГород без типа («Москва»).
city_areastringАдминистративный округ Москвы («Центральный», «Зеленоградский», «Троицкий»); в других городах — null.
city_district_fias_idstringКод ФИАС района города. Заполняется из полного ГАР. Если объект есть в реестре.
city_district_kladr_idstringКод КЛАДР района города. Заполняется из полного ГАР. Если объект есть в реестре.
city_district_with_typestringРайон города с типом («Центральный р-н»). Заполняется из полного ГАР. Если объект есть в реестре.
city_district_typestringТип района города, кратко. Заполняется из полного ГАР. Если объект есть в реестре.
city_district_type_fullstringТип района города полностью. Заполняется из полного ГАР. Если объект есть в реестре.
city_districtstringРайон города без типа. Заполняется из полного ГАР. Если объект есть в реестре.
settlement_fias_idstringКод ФИАС населённого пункта. Заполняется из полного ГАР.
settlement_kladr_idstringКод КЛАДР населённого пункта. Заполняется из полного ГАР.
settlement_with_typestringНаселённый пункт с типом («д Иваново»). Заполняется из полного ГАР.
settlement_typestringТип населённого пункта, кратко («д», «п», «с»). Заполняется из полного ГАР.
settlement_type_fullstringТип населённого пункта полностью. Заполняется из полного ГАР.
settlementstringНаселённый пункт без типа. Заполняется из полного ГАР.
street_fias_idstringКод ФИАС улицы.
street_kladr_idstringКод КЛАДР улицы (параметр ГАР). У домов кода КЛАДР в ГАР нет — house_kladr_id всегда null.
street_with_typestringУлица с типом («ул Тверская»).
street_typestringТип улицы, кратко («ул», «пр-кт», «пер»).
street_type_fullstringТип улицы полностью («улица», «проспект»).
streetstringУлица без типа («Тверская»).
stead_fias_idstringКод ФИАС земельного участка. Появится с поиском участков (gar.steads).
stead_cadnumstringКадастровый номер участка. Пока не заполняется, появится с поиском земельных участков.
stead_typestringТип участка, кратко («уч»). Пока не заполняется, появится с поиском земельных участков.
stead_type_fullstringТип участка полностью («участок»). Пока не заполняется, появится с поиском земельных участков.
steadstringНомер земельного участка. Пока не заполняется, появится с поиском земельных участков.
house_fias_idstringКод ФИАС дома. Заполняется, когда дом найден в ГАР; у номера, приписанного к улице (qc_house = 4), — null.
house_kladr_idstringВ ГАР коды КЛАДР ведутся до улиц, у домов их нет — null.
house_cadnumstringКадастровый номер дома. Заполняется из полного ГАР. Где есть в реестре.
house_typestringТип дома, кратко («д»).
house_type_fullstringТип дома полностью («дом»).
housestringНомер дома («28», «28к1», «47/7»).
block_typestringТип корпуса/строения, кратко («к», «стр»). Заполняется из полного ГАР.
block_type_fullstringТип корпуса/строения полностью («корпус», «строение»). Заполняется из полного ГАР.
blockstringНомер корпуса/строения. Заполняется из полного ГАР.
entrancestringПодъезд. Не заполняется: это часть набранной строки, а не объекта реестра.
floorstringЭтаж. Не заполняется: это часть набранной строки, а не объекта реестра.
flat_fias_idstringКод ФИАС квартиры/помещения. Заполняется, когда подсказка уровня квартиры (gar.apartments).
flat_cadnumstringКадастровый номер квартиры из ГАР, где он есть в реестре.
flat_typestringТип квартиры/помещения, кратко («кв», «пом», «оф»). Заполняется на уровне квартиры.
flat_type_fullstringТип квартиры/помещения полностью («квартира», «помещение»). Заполняется на уровне квартиры.
flatstringНомер квартиры/помещения. Заполняется, когда в запросе указан номер (например «кв 5», «пом 3») или to_bound=flat.
flat_areastringПлощадь квартиры. Не заполняется: открытого источника нет.
square_meter_pricestringРыночная цена м². Не заполняется: открытого источника нет.
flat_pricestringРыночная цена квартиры. Не заполняется: открытого источника нет.
house_flat_countstringКоличество квартир в доме. Пока не заполняется, в планах.
room_fias_idstringКод ФИАС комнаты. Заполняется, когда подсказка уровня комнаты (gar.rooms).
room_cadnumstringКадастровый номер комнаты из ГАР, где он есть в реестре.
room_typestringТип комнаты, кратко («комн»). Заполняется на уровне комнаты.
room_type_fullstringТип комнаты полностью («комната»). Заполняется на уровне комнаты.
roomstringНомер комнаты. Заполняется, когда в запросе указан номер («комн 3») или to_bound=room.
postal_boxstringАбонентский ящик. Не заполняется: это часть набранной строки, а не объекта реестра.
fias_idstringКод ФИАС (ГАР) подсказанного объекта: квартиры, дома, улицы или населённого пункта.
fias_codestringНе заполняется: ГАР иерархический код не ведёт, используйте fias_id.
fias_levelstringУровень детализации, до которого распознан адрес: 1 — регион, 3 — район, 4 — город, 5 — район города, 6 — населённый пункт, 7 — улица, 8 — дом, 9 — помещение, 65 — планировочная структура, −1 — не определён.
fias_actuality_statestringПризнак актуальности в ФИАС: 0 — актуальный.
kladr_idstringКод КЛАДР самого глубокого уровня, у которого он есть. У домов кодов КЛАДР в ГАР нет — код улицы, без улицы — населённого пункта.
geoname_idstringИдентификатор GeoNames. Пока не заполняется, в планах.
capital_markerstring2 — административный центр региона; 1 — город — центр муниципального района; 0 — ни то ни другое (в том числе Москва, Санкт-Петербург, Севастополь).
okatostringКод ОКАТО. Заполняется из полного ГАР.
oktmostringКод ОКТМО территории (параметр ГАР «ОКТМО»): у дома — его собственный, иначе улицы или населённого пункта.
oktmo_budgetstringКод ОКТМО бюджетополучателя (параметр ГАР «ОКТМО бюджетополучателя»); может не совпадать с oktmo.
tax_officestringКод ИФНС для физлиц. Заполняется из полного ГАР.
tax_office_legalstringКод ИФНС для юрлиц. Заполняется из полного ГАР.
timezonestringЧасовой пояс по региону («UTC+3», «UTC+5»).
geo_latstringШирота (строка).
geo_lonstringДолгота (строка).
beltway_hitstringIN_MKAD / OUT_MKAD — Москва и Московская область; IN_KAD / OUT_KAD — Санкт-Петербург и Ленинградская область; в других регионах null. Кольцо — по данным OpenStreetMap.
beltway_distancenumberРасстояние до кольцевой по прямой, км, с округлением вверх; только за кольцом.
metroarrayБлижайшие станции метро [{ name, line, distance }]. Пока не заполняется, в планах.
qc_geostringТочность координат: 0 — точные (дом), 1 — ближайший дом (интерполяция), 2 — улица, 3 — населённый пункт, 4 — город или район, 5 — не определены. У найденного дома — по фактической точности его точки: если у дома есть только точка улицы или центр населённого пункта, это 2 или 3, а не 1. У дома, которого нет в ГАР, координаты уличные — qc_geo = 2.
precisionstringНасколько ответ совпал с набранным адресом (не с точностью координат — она в qc_geo): exact — тот самый дом, с набранными литерой, корпусом и строением (или здание OpenStreetMap с этим номером, если в ГАР дома нет); number — набранного номера в ГАР нет, но есть дом с тем же числом («3» для «3В», «25» для «25 к1»): ответ — набранный номер на улице без house_fias_id, координаты взяты от этого дома, а сам дом идёт следующей подсказкой; near — соседний номер на той же улице («50» для «5»), только в списке, не первой подсказкой; street — номер приписан к улице, дома с таким числом нет, или запрошена улица; settlement — уровень населённого пункта; null — регион.
qc_completestringПолнота адреса: 0 — до квартиры, 1 — до дома, 2 — до улицы, 3 — до города/населённого пункта, 4 — до района/региона, 9 — не распознан.
qc_housestringТочность дома: 2 — дом найден; 3 — запрошенного номера на улице нет, найден его вариант (другая литера, корпус или дробь того же числа: «5а» или «5/3» для «5»); 4 — дом не найден: номер из запроса приписан к улице, house_fias_id пуст, fias_level = 7. На уровне выше улицы — null.
history_valuesarrayПрежние названия улицы (у подсказки без улицы — населённого пункта) по истории ГАР, например [«ул Ясная»]; переименований не было — null.
cadastral_numberstringКадастровый номер квартиры или помещения (параметр ГАР), где он есть в реестре; у дома — null, номер дома — в house_cadnum.
unparsed_partsstringСлова запроса, которых нет в найденном адресе, через пробел (геокодер и пакетная обработка: «ул Пушкина дом Колотушкина» → «колотушкина»); null — нашлись все. В подсказках всегда null.
sourcestringТолько в /v1/geocode и пакетной обработке: запрос, как он пришёл. В подсказках null.
qcstringТолько в /v1/geocode и пакетной обработке: 0 — адрес найден целиком, 1 — в запросе остались слова, которых нет в адресе (см. unparsed_parts), 3 — есть другие адреса с тем же названием (ambiguous). В подсказках null; качество координат — в qc_geo.

Карта на своём сайте

Векторная карта подключается к библиотеке MapLibre GL одной ссылкой на стиль. Ключ — публичный (pk_…) с привязкой к доменам вашего сайта: он работает только со страниц этих доменов. Открытие карты (загрузка style.json) списывает единицы как «открытие карты», тайлы и шрифты не тарифицируются.

Ссылка на стиль
https://maps.adresly.ru/styles/yandex/style.json?key=pk_xxx
  • yandex — Светлая, привычная по Яндекс.Картам
  • yandex-night — Ночная к ней
  • 2gis — Светлая, привычная по 2ГИС
  • 2gis-night — Ночная к ней

Подпись карты: подключите https://adresly.ru/maps-credits.js и выключите штатную плашку MapLibre. На карте останутся «Сервис Adresly.ru» и маленькая (i) справа; упоминание OpenStreetMap и OpenMapTiles, которого требует лицензия данных, — во всплывашке по (i), она всегда свёрнута.

html
<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css"> <script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script> <script src="https://adresly.ru/maps-credits.js"></script> <div id="map" style="height: 400px"></div> <script> const KEY = "pk_xxx"; // публичный ключ, привязанный к доменам сайта const map = new maplibregl.Map({ container: "map", style: "https://maps.adresly.ru/styles/yandex/style.json?key=" + KEY, center: [37.6176, 55.7558], // [долгота, широта] zoom: 10, // Ключ — ко всем запросам карты (тайлы, шрифты, иконки). transformRequest: (url) => url.startsWith("https://maps.adresly.ru") && !url.includes("key=") ? { url: url + (url.includes("?") ? "&" : "?") + "key=" + KEY } : { url }, attributionControl: false, // вместо штатной плашки — наша подпись }); map.addControl(new AdreslyMapCredits(), "bottom-right"); </script>

Подсказки адресов

POST/v1/rs/suggest/addressучитывается как suggest_address

Автодополнение по префиксу: пользователь ввёл часть строки — сервис возвращает до 20 нормализованных адресов с разложением на компоненты, индексом и координатами. Поле data содержит полный набор адресных атрибутов — от региона до квартиры, с кодами ФИАС. Дом, корпус/строение/литеру и квартиру можно указывать одной строкой («тверская 28 к 3 кв 45»), маркеры и склейки распознаются. Поддерживает сокращения городов («мск», «спб», «ебург») и типов улиц.

Параметры тела

ПараметрТипОписание
queryобяз.stringЗапрос пользователя. От 1 до 200 символов.
countintegerСколько вариантов вернуть. 1–20, по умолчанию 10.
locationsarrayОграничить область поиска (до 20 элементов). Элементы массива объединяются по ИЛИ, поля внутри одного элемента — по И. Поля элемента: region — регион по началу названия («Московская», «Татарстан»); city — город по точному названию («Москва»); region_fias_id — код ФИАС региона; city_fias_id — код ФИАС города; kladr_id — код КЛАДР региона (13 цифр, «7700000000000»). Неизвестный код ФИАС, КЛАДР города или населённого пункта и противоречивый элемент (например, region_fias_id Москвы и city «Казань») ни с чем не совпадают: если не совпал ни один элемент, ответ — пустой список. Поля settlement_fias_id, area_fias_id, street_fias_id, house_fias_id, area, settlement, street и прочие поля фильтра принимаются для совместимости, но не применяются: рядом с поддержанным полем они не влияют на выдачу, а элемент только из них ни с чем не совпадает. country «*», «Россия» или «RU» область не сужает (все адреса — российские). Пример: [{ "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5" }, { "city": "Казань" }] — Москва или Казань.
to_boundobjectГранулярность подсказок: { "value": "street" } — только до улицы (без домов), { "value": "house" } — до дома (режим «дома выбранной улицы», даже без номера в запросе), { "value": "flat" } — до квартиры/помещения, { "value": "room" } — до комнаты. Значения region/area/city/settlement ограничивают выдачу населёнными пунктами.
from_boundobjectПринимается для совместимости со сторонними виджетами подсказок, на выборку не влияет.
divisionstringДеление для полей area/sub_area/settlement: administrative (по умолчанию) или municipal. Принимается регистронезависимо.

Поля ответа

ПолеТипОписание
suggestionsarrayСписок найденных вариантов, не больше count.
suggestions[].valuestringАдрес одной строкой — то, что подставляется в поле ввода.
suggestions[].unrestricted_valuestringАдрес одной строкой вместе с почтовым индексом.
suggestions[].dataobjectГранулярный адрес — см. раздел «Объект адреса (data)».

Полное описание всех полей data — в разделе «Объект адреса (data)».

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

curl
curl -s -X POST "https://api.adresly.ru/v1/rs/suggest/address" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "query": "мск тверская 28", "count": 1 }'

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

json
{ "suggestions": [ { "value": "г Москва, ул Тверская, д 28", "unrestricted_value": "125009, г Москва, ул Тверская, д 28", "data": { "postal_code": "125009", "country": "Россия", "country_iso_code": "RU", "federal_district": "Центральный", "region_fias_id": null, "region_kladr_id": null, "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, "sub_area_fias_id": null, "sub_area_kladr_id": null, "sub_area_with_type": null, "sub_area_type": null, "sub_area_type_full": null, "sub_area": null, "city_fias_id": null, "city_kladr_id": null, "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-85e43c0f4d1e", "street_kladr_id": null, "street_with_type": "ул Тверская", "street_type": "ул", "street_type_full": "улица", "street": "Тверская", "stead_fias_id": null, "stead_cadnum": null, "stead_type": null, "stead_type_full": null, "stead": null, "house_fias_id": "fd2911a0-4bb8-4039-a45a-37c0e103e91b", "house_kladr_id": null, "house_cadnum": null, "house_type": "д", "house_type_full": "дом", "house": "28", "block_type": null, "block_type_full": null, "block": null, "entrance": null, "floor": null, "flat_fias_id": null, "flat_cadnum": null, "flat_type": null, "flat_type_full": null, "flat": null, "flat_area": null, "square_meter_price": null, "flat_price": null, "house_flat_count": null, "room_fias_id": null, "room_cadnum": null, "room_type": null, "room_type_full": null, "room": null, "postal_box": null, "fias_id": "fd2911a0-4bb8-4039-a45a-37c0e103e91b", "fias_code": null, "fias_level": "8", "fias_actuality_state": "0", "kladr_id": null, "geoname_id": null, "capital_marker": "0", "okato": null, "oktmo": null, "oktmo_budget": null, "tax_office": null, "tax_office_legal": null, "timezone": "UTC+3", "geo_lat": "55.7649", "geo_lon": "37.6050", "beltway_hit": "IN_MKAD", "beltway_distance": null, "metro": null, "qc_geo": "0", "qc_complete": null, "qc_house": null, "history_values": null, "unparsed_parts": null, "source": null, "qc": null } } ] }
Полный состав data — в разделе «Объект адреса (data)» с описанием каждого поля. Поля без источника данных (метро, площадь и цены квартиры и т. п.) возвращаются как null. Ранжирование: если запрос начинается с города или региона («краснодар ленина 15»), подсказки этого города идут первыми (частично введённое название тоже учитывается); далее — точное совпадение названия улицы, текстовая похожесть и популярность объекта по числу домов в ГАР, поэтому без указания города «ленина 15» сначала отдаст крупные города, а не деревни.

Подсказки почтовых индексов

POST/v1/rs/suggest/postal_unitучитывается как suggest_postal

Поиск по 6-значному индексу. Принимает 3–6 цифр и возвращает покрытие — список индексов и образцовые адреса. Это не справочник отделений связи: адрес отделения, его координаты, график работы и признак закрытия не возвращаются; вместо отделения связи отдаётся образцовый адрес из зоны индекса.

Параметры тела

ПараметрТипОписание
queryобяз.stringЧасть индекса, 3–6 цифр.
countintegerСколько вариантов вернуть. 1–20, по умолчанию 10.

Поля ответа

ПолеТипОписание
suggestionsarrayСписок индексов, начинающихся с запрошенных цифр.
suggestions[].valuestringПочтовый индекс («101000»).
suggestions[].unrestricted_valuestringИндекс и образцовый адрес из зоны его покрытия.
suggestions[].dataobjectОбъект адреса (см. общий раздел). Координаты, fias_level и qc_geo у почтовых подсказок всегда null.

Полное описание всех полей data — в разделе «Объект адреса (data)».

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

curl
curl -s -X POST "https://api.adresly.ru/v1/rs/suggest/postal_unit" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "query": "1010", "count": 5 }'

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

json
{ "suggestions": [ { "value": "101000", "unrestricted_value": "101000 · г Москва, ул Мясницкая", "data": { "postal_code": "101000", "country": "Россия", "country_iso_code": "RU", "federal_district": "Центральный", "region_with_type": "г Москва", "region": "Москва", "city": "Москва", "street_with_type": "ул Мясницкая", "street": "Мясницкая", "timezone": "UTC+3", "geo_lat": null, "geo_lon": null, "qc_geo": null, "...": "остальные поля объекта адреса — см. раздел «Объект адреса (data)»" } } ] }

Геокодирование (адрес → координаты)

POST/v1/geocodeучитывается как geocode

По текстовому адресу возвращает наиболее похожие результаты с координатами и нормализованной записью. Формат элементов — тот же объект адреса, что и в подсказках. Если нужно несколько кандидатов, увеличьте параметр count. Если ни одно слово запроса не нашлось в найденном адресе («абракадабра», «qwerty»), suggestions пустой — такого адреса нет; слова, которых нет в найденном адресе, — в data.unparsed_parts.

Параметры тела

ПараметрТипОписание
queryобяз.stringАдрес. От 1 до 200 символов.
countinteger1–10, по умолчанию 1.

Поля ответа

ПолеТипОписание
suggestionsarrayСписок найденных вариантов, не больше count.
suggestions[].valuestringАдрес одной строкой — то, что подставляется в поле ввода.
suggestions[].unrestricted_valuestringАдрес одной строкой вместе с почтовым индексом.
suggestions[].dataobjectГранулярный адрес — см. раздел «Объект адреса (data)».

Полное описание всех полей data — в разделе «Объект адреса (data)».

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

curl
curl -s -X POST "https://api.adresly.ru/v1/geocode" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "query": "Москва, Льва Толстого, 16" }'

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

json
{ "suggestions": [ { "value": "г Москва, ул Льва Толстого, д 16", "unrestricted_value": "119021, г Москва, ул Льва Толстого, д 16", "data": { "postal_code": "119021", "country": "Россия", "country_iso_code": "RU", "federal_district": "Центральный", "region_iso_code": "RU-MOW", "region_with_type": "г Москва", "city": "Москва", "street_with_type": "ул Льва Толстого", "house_type": "д", "house": "16", "fias_level": "8", "timezone": "UTC+3", "geo_lat": "55.733969", "geo_lon": "37.587093", "qc_geo": "0", "...": "остальные поля объекта адреса — см. раздел «Объект адреса (data)»" } } ] }

Пакетная обработка адресов

POST/v1/batch/geocodeучитывается как batch_geocode

Стандартизация и геокодирование списка адресов за один запрос: для каждой строки — лучший вариант с кодами ФИАС/КЛАДР и координатами (тот же объект адреса, что в геокодере). Суточный лимит тарифа не расходует: стоит 15 коп. за каждый переданный адрес и списывается с рублёвого баланса аккаунта (пополнение — в личном кабинете). Работает только с секретным ключом.

Параметры тела

ПараметрТипОписание
queriesобяз.string[]Адреса, от 1 до 500 строк, каждая — от 1 до 200 символов.

Поля ответа

ПолеТипОписание
resultsarrayРезультаты в порядке queries.
results[].querystringИсходная строка.
results[].suggestionobject | nullЛучший вариант (value, unrestricted_value, data) или null, если адрес не найден. Списание — за каждую строку, найденную или нет.
charged_kopecksintegerСписано с баланса, коп. (15 × число строк).
balance_kopecksintegerОстаток баланса после списания, коп.

Полное описание всех полей data — в разделе «Объект адреса (data)».

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

curl
curl -s -X POST "https://api.adresly.ru/v1/batch/geocode" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "queries": ["Москва, Льва Толстого, 16", "спб невский 1"] }'

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

json
{ "results": [ { "query": "Москва, Льва Толстого, 16", "suggestion": { "value": "г Москва, ул Льва Толстого, д 16", "unrestricted_value": "119021, г Москва, ул Льва Толстого, д 16", "data": { "house_fias_id": "…", "geo_lat": "55.733969", "geo_lon": "37.587093", "...": "…" } } }, { "query": "спб невский 1", "suggestion": { "value": "г Санкт-Петербург, Невский пр-кт, д 1", "...": "…" } } ], "charged_kopecks": 30, "balance_kopecks": 9970 }
Деньги списываются заранее за весь пакет. Если на балансе не хватает — ответ 402 insufficient_balance и ничего не списывается. Если пакет не удалось обработать из-за ошибки сервиса, списание возвращается целиком.

Обратное геокодирование (координаты → адрес)

POST/v1/rs/geolocate/addressучитывается как reverse

Возвращает ближайший адрес и список альтернатив в радиусе. Подходит для определения адреса по геолокации мобильного приложения.

Параметры тела

ПараметрТипОписание
latобяз.numberШирота, −90…90.
lonобяз.numberДолгота, −180…180.
radius_metersintegerРадиус поиска в метрах, 10–1000. По умолчанию 200.
countintegerСколько вариантов вернуть, 1–20. По умолчанию 5.
divisionstringДеление для area/sub_area/settlement: administrative (по умолчанию) или municipal.

Поля ответа

ПолеТипОписание
suggestionsarrayАдреса в радиусе, отсортированы по удалённости от точки.
suggestions[].valuestringАдрес одной строкой.
suggestions[].unrestricted_valuestringАдрес одной строкой с индексом.
suggestions[].dataobjectОбъект адреса — см. общий раздел.

Полное описание всех полей data — в разделе «Объект адреса (data)».

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

curl
curl -s -X POST "https://api.adresly.ru/v1/rs/geolocate/address" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "lat": 59.9342, "lon": 30.3350, "radius_meters": 100, "count": 3 }'

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

json
{ "suggestions": [ { "value": "г Санкт-Петербург, Дворцовая пл, д 2", "unrestricted_value": "191055, г Санкт-Петербург, Дворцовая пл, д 2", "data": { "postal_code": "191055", "country": "Россия", "region_iso_code": "RU-SPE", "region_with_type": "г Санкт-Петербург", "city": "Санкт-Петербург", "street_with_type": "пл Дворцовая", "house": "2", "fias_level": "8", "timezone": "UTC+3", "geo_lat": "59.9388", "geo_lon": "30.3155", "qc_geo": "0", "...": "остальные поля объекта адреса — см. раздел «Объект адреса (data)»" } } ] }

Маршрут между точками

POST/v1/routeучитывается как route

Расчёт пути по 2–50 точкам. Каждая точка задаётся либо адресом (тогда геокодим), либо координатами (lat/lon). Возвращает суммарные distance и duration, геометрию маршрута (GeoJSON), а при steps=true — пошаговую навигацию.

Параметры тела

ПараметрТипОписание
pointsобяз.arrayМассив точек: { address } или { lat, lon }. 2–50 элементов.
modestringТолько car (по умолчанию). Другое значение — 400 unsupported_mode.
alternativesbooleanВернуть альтернативные маршруты. По умолчанию false.
geometrystringgeojson (по умолчанию), polyline, none.
stepsbooleanПошаговая навигация в legs[].steps. По умолчанию false.

Поля ответа

ПолеТипОписание
codestring«Ok» при успешном расчёте.
routesarrayМаршруты: первый — основной, дальше альтернативы (при alternatives=true).
routes[].distance_mnumberДлина маршрута в метрах.
routes[].duration_snumberВремя в пути в секундах.
routes[].geometryobject | string | nullГеометрия: GeoJSON LineString (geojson), строка polyline или null (none). Координаты GeoJSON — пары [lon, lat].
routes[].legsarrayСегменты маршрута между соседними точками запроса.
routes[].legs[].distance_mnumberДлина сегмента в метрах.
routes[].legs[].duration_snumberВремя сегмента в секундах.
routes[].legs[].summarystringОсновные дороги сегмента («Ярославское ш»).
routes[].legs[].stepsarrayПошаговые манёвры (только при steps=true).
waypointsarrayТочки запроса, привязанные к дорожной сети, в исходном порядке.
waypoints[].location[lon, lat]Координаты привязки на дороге.
waypoints[].namestringНазвание улицы в месте привязки.
waypoints[].distancenumberСдвиг от исходной точки до привязки, в метрах.

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

curl
curl -s -X POST "https://api.adresly.ru/v1/route" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "points": [ { "address": "Москва, Красная площадь" }, { "lat": 56.3107, "lon": 38.1316 }, { "address": "Ярославль" } ], "mode": "car", "geometry": "geojson" }'

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

json
{ "code": "Ok", "routes": [ { "distance_m": 271340, "duration_s": 15120, "geometry": { "type": "LineString", "coordinates": [[37.62, 55.75], ...] }, "legs": [ { "distance_m": 71000, "duration_s": 4200, "summary": "Ярославское ш" } ] } ], "waypoints": [ { "location": [37.6208, 55.7539], "name": "Красная площадь", "distance": 12.3 } ] }
В v1 поддерживаем маршруты по территории России. Для трансграничных запросов подключим Казахстан и Беларусь после стабилизации основного потока.

Матрица расстояний

POST/v1/distancematrixучитывается как distancematrix

Возвращает матрицы distances_m и durations_s для всех пар sources × destinations. Используется для развозок, планирования слотов, выбора ближайшего курьера/филиала.

Параметры тела

ПараметрТипОписание
sourcesобяз.arrayИсточники: { address } или { lat, lon }. 1–100 элементов.
destinationsобяз.arrayНазначения. 1–100 элементов. sources × destinations ≤ 10 000.
modestringТолько car (по умолчанию). Другое значение — 400 unsupported_mode.

Поля ответа

ПолеТипОписание
codestring«Ok» при успешном расчёте.
durations_snumber[][]Матрица времени в секундах: строка — источник, столбец — назначение. null в ячейке — пара недостижима по дорогам.
distances_mnumber[][]Матрица расстояний в метрах, той же размерности.
sourcesarrayИсточники, привязанные к дорожной сети: { location: [lon, lat], name }.
destinationsarrayНазначения, привязанные к дорожной сети: { location: [lon, lat], name }.

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

curl
curl -s -X POST "https://api.adresly.ru/v1/distancematrix" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "sources": [ { "lat": 55.7539, "lon": 37.6208 } ], "destinations": [ { "lat": 56.3107, "lon": 38.1316 }, { "lat": 57.6243, "lon": 39.9007 } ] }'

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

json
{ "code": "Ok", "durations_s": [[4200, 15120]], "distances_m": [[71000, 271340]], "sources": [{ "location": [37.6208, 55.7539], "name": "" }], "destinations": [ { "location": [38.1316, 56.3107], "name": "" }, { "location": [39.9007, 57.6243], "name": "" } ] }

Стандартизация ФИО

POST/v1/clean/nameучитывается как clean_name

Разбирает ФИО из произвольной строки: исправляет опечатки и транслит, раскладывает на фамилию, имя и отчество в любом порядке слов, понимает инициалы и тюркские отчества («Рашид оглы»), определяет пол и склоняет в родительный, дательный и творительный падежи. Формат запроса и ответа совместим с распространённым форматом clean/name. Доступен только секретному ключу: ФИО — персональные данные, вызывайте сервис со своего сервера. Тело запроса и ответ нигде не сохраняются и не пишутся в журналы.

Параметры тела

ПараметрТипОписание
(тело)обяз.string[]JSON-массив строк, по одному человеку в строке. 1–50 строк, каждая до 300 символов. Цена — 1 единица за строку в суточном лимите тарифа.

Поля ответа

ПолеТипОписание
[]arrayМассив результатов в том же порядке, что и строки запроса.
[].sourcestringИсходная строка.
[].resultstringФИО в порядке «Фамилия Имя Отчество», с исправлениями. null — если в строке нет букв.
[].result_genitivestringФИО в родительном падеже (кого?).
[].result_dativestringФИО в дательном падеже (кому?).
[].result_ablativestringФИО в творительном падеже (кем?).
[].surnamestringФамилия или null.
[].namestringИмя или null. Инициал возвращается как «И.».
[].patronymicstringОтчество или null.
[].genderstringПол: М, Ж или НД — не удалось определить однозначно.
[].qcnumberКод качества: 0 — распознано уверенно, 1 — были исправления, допущения или противоречия, стоит проверить вручную.

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

curl
curl -s -X POST "https://api.adresly.ru/v1/clean/name" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '[ "Срегей владимерович иванов" ]'

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

json
[ { "source": "Срегей владимерович иванов", "result": "Иванов Сергей Владимирович", "result_genitive": "Иванова Сергея Владимировича", "result_dative": "Иванову Сергею Владимировичу", "result_ablative": "Ивановым Сергеем Владимировичем", "surname": "Иванов", "name": "Сергей", "patronymic": "Владимирович", "gender": "М", "qc": 1 } ]
Словари имён, отчеств и фамилий — открытый набор russiannames (BSD-3), правила склонения — petrovich-rules (MIT). Фамилии не исправляются: незнакомая фамилия остаётся как введена и склоняется по правилам. Склонение в винительный и предложный падежи и разбор нескольких человек в одной строке не поддерживаются.

Организация по ИНН или ОГРН

POST/v1/rs/findById/partyучитывается как party_find

Карточка организации или индивидуального предпринимателя по ИНН или ОГРН: сведения ЕГРЮЛ/ЕГРИП — названия, коды, статус, руководитель, виды деятельности и юридический адрес. Адрес юрлица сопоставляется с ГАР и приходит с кодами ФИАС и координатами, в том же объекте адреса, что и в адресных сервисах. Тип определяется по длине номера: ИНН из 10 цифр и ОГРН из 13 — юрлицо, ИНН из 12 цифр и ОГРНИП из 15 — предприниматель. При нескольких организациях с одним ИНН отдаётся головная. Цена — 200 ед. за запрос; кроме суточного лимита единиц действует потолок обновлений сведений в сутки (см. ниже). Доступен только секретному ключу — вызывайте со своего сервера.

Параметры тела

ПараметрТипОписание
queryобяз.stringИНН (10 или 12 цифр), ОГРН (13) или ОГРНИП (15) с верной контрольной суммой. Неверная сумма — 400 bad_request без списания.
kpp, branch_typestringПринимаются и игнорируются: всегда отдаётся головная организация.

Поля ответа

ПолеТипОписание
suggestionsarrayОдна карточка или пустой массив, если организация не найдена (такой ответ тоже списывается).
suggestions[].valuestringКраткое название с ОПФ («ПАО СБЕРБАНК»); у предпринимателя — «ИП Иванов И. И.».
suggestions[].unrestricted_valuestringСтрока для показа в списке.
suggestions[].dataobjectКарточка организации, поля ниже (data.…).
stalebooleantrue — реестр сейчас недоступен, отдана последняя сохранённая копия сведений (дата — в state.actuality_date). Поле есть только в этом случае.
data.typestringLEGAL — юрлицо (ИНН из 10 цифр, ОГРН из 13), INDIVIDUAL — индивидуальный предприниматель (ИНН из 12 цифр, ОГРНИП из 15).
data.innstringИНН.
data.kppstringКПП головной организации. У предпринимателя — null.
data.ogrnstringОГРН, у предпринимателя — ОГРНИП.
data.ogrn_datestringДата присвоения ОГРН, YYYY-MM-DD.
data.okpostringКод ОКПО.
data.okato, data.oktmo, data.okogu, data.okfsstringКоды ОКАТО, ОКТМО, ОКОГУ и ОКФС. Если в реестре нет — null.
data.name.full_with_opfstringПолное название с ОПФ. У предпринимателя — «ИП Иванов И. И.».
data.name.short_with_opfstringКраткое название с ОПФ.
data.name.latinstringНазвание на английском, если указано в реестре, иначе null.
data.opf.code, data.opf.fullstringКод и название организационно-правовой формы по ОКОПФ.
data.okvedstringКод основного вида деятельности.
data.okved_typestringВерсия справочника ОКВЭД («2014»).
data.okvedsarrayВсе виды деятельности [{ code, name, main }]; у основного main = true.
data.state.statusstringСтатус по коду реестра (data.state.code): ACTIVE — действует, в том числе с отметками, которые не мешают работе (уменьшение уставного капитала, смена адреса, у ИП — глава КФХ отсутствует); LIQUIDATING — ликвидируется или принято решение о предстоящем исключении из реестра (организация ещё в реестре); BANKRUPT — дело о банкротстве: наблюдение, финансовое оздоровление, внешнее управление, конкурсное производство; REORGANIZING — в процессе реорганизации; LIQUIDATED — деятельность прекращена: ликвидирована, исключена из реестра, реорганизована с прекращением, регистрация признана недействительной, ИП прекратил деятельность. Есть дата прекращения — всегда LIQUIDATED.
data.state.code, data.state.textstringКод и текст статуса реестра. Код — по справочникам ФНС СЮЛСТ (юрлица) и СИПСТ (ИП): 101–102 — ликвидация, 105–110 — предстоящее исключение, 113–117 — банкротство, 121–139 — реорганизация, 2xx–8xx — деятельность прекращена; 001 — действует без особых отметок, 000 — деятельность прекращена.
data.state.registration_datestringДата регистрации, YYYY-MM-DD.
data.state.liquidation_datestringДата ликвидации или прекращения деятельности, YYYY-MM-DD; у действующей — null.
data.state.actuality_datestringДата, на которую получены сведения из реестра, YYYY-MM-DD.
data.managementobject | nullРуководитель { name, post, disqualified }: ФИО, должность, признак дисквалификации. У предпринимателя и если в реестре нет — null.
data.managersarrayВсе лица с правом действовать без доверенности [{ name, post }]; может быть пустым.
data.capitalobject | nullУставный капитал { type, value }: вид и сумма в рублях. Если нет — null.
data.employee_countnumberСреднесписочная численность работников или null.
data.tax_systemstringСпециальный налоговый режим (УСН, ЕСХН и т. п.) или null.
data.smb_categorystringКатегория в реестре МСП («Микропредприятие», «Малое предприятие», …) или null.
data.fioobjectТолько у предпринимателя: { surname, name, patronymic, gender }, пол — М, Ж или НД.
data.address.valuestringЮридический адрес одной строкой, как в реестре. У предпринимателя — населённый пункт.
data.address.unrestricted_valuestringАдрес с индексом, если он известен.
data.address.invaliditybooleantrue — в реестре есть отметка о недостоверности адреса.
data.address.invalidity_textstringТекст отметки о недостоверности или null.
data.address.massbooleantrue — адрес массовой регистрации.
data.address.gar_idstringКод ФИАС (ГАР) дома юридического адреса, если он указан в реестре, иначе null. Есть не у всех организаций: у многих, в том числе крупных, его нет — тогда адрес сопоставляется по тексту (match: text).
data.address.matchstringКак адрес сопоставлен с ГАР: gar_id — по коду ФИАС дома из реестра (адрес до дома), text — по тексту адреса (частый случай), null — сопоставить не удалось, тогда data = null, а value и unrestricted_value остаются.
data.address.dataobject | nullОбъект адреса с кодами ФИАС и координатами — см. раздел «Объект адреса (data)». У предпринимателя — до населённого пункта. null — если адрес не сопоставлен.

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

curl
curl -s -X POST "https://api.adresly.ru/v1/rs/findById/party" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "query": "7707083893" }'

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

json
{ "suggestions": [ { "value": "ПАО СБЕРБАНК", "unrestricted_value": "ПАО СБЕРБАНК", "data": { "type": "LEGAL", "inn": "7707083893", "kpp": "773601001", "ogrn": "1027700132195", "ogrn_date": "2002-08-16", "name": { "full_with_opf": "ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"СБЕРБАНК РОССИИ\"", "short_with_opf": "ПАО СБЕРБАНК", "latin": null }, "opf": { "code": "12247", "full": "Публичные акционерные общества" }, "okved": "64.19", "state": { "status": "ACTIVE", "code": "001", "text": "Действует", "registration_date": "1991-06-20", "liquidation_date": null, "actuality_date": "2026-11-06" }, "address": { "value": "117312, г. Москва, ул. Вавилова, д. 19", "invalidity": false, "mass": true, "gar_id": null, "match": "text", "data": { "postal_code": "117312", "city": "Москва", "street_with_type": "ул Вавилова", "house": "19", "fias_id": "…", "geo_lat": "…", "geo_lon": "…", "...": "остальные поля объекта адреса" } }, "...": "остальные поля карточки — в таблице выше" } } ] }
Списание. 200 ед. списываются за ответ 200: организация найдена, не найдена (пустой suggestions — реестр проверен, такой ответ тоже стоит 200 ед.) или отдана сохранённая копия со stale: true. Не списываются: пустой ответ на запрос короче 4 символов или неполный номер, 400 bad_request (неверное тело или контрольная сумма ИНН/ОГРН), 401/403, 429 rate_limited и limit_exceeded, 429 party_fetch_limit и 503 party_unavailable (с заголовком Retry-After). Если реестр недоступен (сбой, исчерпана квота или закончились средства у поставщика сведений), ответ 402 эти ручки не отдают: организация, запрошенная раньше, приходит из сохранённой копии со stale: true, остальные — 503 party_unavailable без списания. Лимиты. Каждый запрос — 200 ед. из суточного лимита тарифа (на Бесплатном это 50 запросов в сутки). Отдельно у тарифа есть потолок обновлений сведений в сутки: Бесплатный — 20, Старт — 50, Базовый — 150, Максимальный — 300, Корпоративный — 600. Повторный запрос той же организации в течение 3 дней не считается: она отдаётся из сохранённой копии. Потолок исчерпан — 429 party_fetch_limit, единицы не списываются, уже сохранённые организации отдаются как обычно. Потолок восстанавливается в 00:00 по МСК. Поиск по названию для формы — в разделе «Подсказки организаций», там же рекомендуемый поток.

Подсказки организаций

POST/v1/rs/suggest/partyучитывается как party_suggest

Поиск организаций и предпринимателей по названию для поля «Организация или ИНН» в форме — по сведениям ЕГРЮЛ/ЕГРИП. Текстовый запрос от 4 символов возвращает до 20 вариантов по релевантности. Полный ИНН или ОГРН с верной контрольной суммой возвращает одну подсказку с полной карточкой, как findById. Запрос короче 4 символов и неполный номер дают пустой список без списания. Цена — 200 ед. за запрос при любом count, в суточном лимите единиц; поиск по названию расходует и потолок обновлений сведений в сутки (повтор того же запроса в течение суток — нет). Доступен только секретному ключу.

Параметры тела

ПараметрТипОписание
queryобяз.stringНазвание организации или ФИО предпринимателя — от 4 символов; либо полный ИНН или ОГРН.
countintegerСколько вариантов вернуть. 1–20, по умолчанию 10.
typestringLEGAL — организации (по умолчанию), INDIVIDUAL — предприниматели. Оба типа одним запросом не ищутся.
statusstring[]Только ["ACTIVE"] — без ликвидированных. Без параметра — все.

Поля ответа

ПолеТипОписание
suggestionsarrayНайденные варианты, не больше count; пустой массив — ничего не нашли.
suggestions[].valuestringКраткое название с ОПФ — то, что подставляется в поле.
suggestions[].unrestricted_valuestringСтрока для показа в списке.
data.type, data.inn, data.kpp, data.ogrnstringТип и номера, как в карточке findById.
data.name.full_with_opf, data.name.short_with_opfstringПолное и краткое название с ОПФ.
data.fioobjectТолько у предпринимателя: { surname, name, patronymic, gender }.
data.state.status, data.state.registration_date, data.state.liquidation_datestringСтатус — те же значения, что в findById (ACTIVE, LIQUIDATING, LIQUIDATED, BANKRUPT, REORGANIZING), но по тексту статуса: в поиске реестр не отдаёт код; точный код — в карточке findById. Даты — YYYY-MM-DD, liquidation_date — дата прекращения у юрлица и у ИП.
data.okvednullВ подсказках по названию null: реестр в поиске отдаёт только наименование основного вида деятельности (оно в data.okveds), код — в карточке findById/party.
data.okvedsarrayОсновной вид деятельности [{ code: null, name, main: true }] или пустой массив.
data.address.valuestringЮридический адрес одной строкой, с индексом. У предпринимателя — null.
data.address.region_codestringКод региона («77»); у предпринимателя адреса в подсказке нет, только регион.
data.address.datanullВ подсказках по названию всегда null: адрес с ФИАС и координатами — запросом findById/party по выбранной подсказке. При запросе полным ИНН или ОГРН — полная карточка, как в findById.
stalebooleantrue — реестр сейчас недоступен, отдана последняя сохранённая копия сведений (дата — в state.actuality_date). Поле есть только в этом случае.

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

curl
curl -s -X POST "https://api.adresly.ru/v1/rs/suggest/party" \ -H "Authorization: Token adr_xxx" \ -H "Content-Type: application/json" \ -d '{ "query": "сбербанк", "count": 3 }'

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

json
{ "suggestions": [ { "value": "АО \"СБЕРБАНК ЛИЗИНГ\"", "unrestricted_value": "АО \"СБЕРБАНК ЛИЗИНГ\"", "data": { "type": "LEGAL", "inn": "7707009586", "kpp": "503201001", "ogrn": "1027739000728", "name": { "full_with_opf": "АКЦИОНЕРНОЕ ОБЩЕСТВО \"СБЕРБАНК ЛИЗИНГ\"", "short_with_opf": "АО \"СБЕРБАНК ЛИЗИНГ\"" }, "fio": null, "state": { "status": "ACTIVE", "registration_date": "1993-08-17", "liquidation_date": null }, "okved": null, "okveds": [{ "code": null, "name": "Деятельность по финансовой аренде (лизингу/сублизингу) в прочих областях, кроме племенных животных", "main": true }], "address": { "value": "143003, Московская область, г. о. Одинцовский, г. Одинцово, ул. Маршала Неделина, д. 6А, этаж/помещ. 5 / 512, 513", "region_code": "50", "data": null } } }, { "value": "…", "data": { "inn": "…", "...": "…" } } ] }
Рекомендуемый поток для формы: пользователь вводит название → suggest/party показывает варианты → по выбранной подсказке вызовите findById/party с её data.inn → придут КПП, руководитель, коды и юридический адрес с ФИАС и координатами. Это два запроса по 200 ед. Списание. 200 ед. списываются за ответ 200: организация найдена, не найдена (пустой suggestions — реестр проверен, такой ответ тоже стоит 200 ед.) или отдана сохранённая копия со stale: true. Не списываются: пустой ответ на запрос короче 4 символов или неполный номер, 400 bad_request (неверное тело или контрольная сумма ИНН/ОГРН), 401/403, 429 rate_limited и limit_exceeded, 429 party_fetch_limit и 503 party_unavailable (с заголовком Retry-After). Если реестр недоступен (сбой, исчерпана квота или закончились средства у поставщика сведений), ответ 402 эти ручки не отдают: организация, запрошенная раньше, приходит из сохранённой копии со stale: true, остальные — 503 party_unavailable без списания. Лимиты. Каждый запрос — 200 ед. из суточного лимита тарифа (на Бесплатном это 50 запросов в сутки). Отдельно у тарифа есть потолок обновлений сведений в сутки: Бесплатный — 20, Старт — 50, Базовый — 150, Максимальный — 300, Корпоративный — 600. Повторный запрос той же организации в течение 3 дней не считается: она отдаётся из сохранённой копии. Потолок исчерпан — 429 party_fetch_limit, единицы не списываются, уже сохранённые организации отдаются как обычно. Потолок восстанавливается в 00:00 по МСК.
Документация API — Adresly