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

HintData — единый REST API для подсказок, стандартизации и обогащения данных. Все методы принимают POST с JSON-телом и возвращают JSON.

Работаете с ИИ-ассистентом? Подключите API как MCP-сервер: Claude, Cursor, Yandex AI Studio и другие клиенты будут сами искать адреса, компании и объекты недвижимости.

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

API-ключ передаётся в заголовке Authorization с префиксом Token. Поддерживаются два типа ключей.

Ключ	Где использовать	Доступ
`pk_…`публичный	браузер, виджеты, мобильные приложения	подсказки по любому справочнику (кадастр в том числе — он тарифицируется за запрос) и геолокация. Можно передавать query-параметром `?token=pk_…`.
`sk_…`секретный	только сервер	полный доступ: подсказки, стандартизация (`clean`), точный поиск (`find`), кадастр. Не размещается в клиентском коде.

Любой ключ можно ограничить списком IP-адресов или подсетей, публичный — ещё и списком сайтов (проверяется заголовок Origin, без него — Referer). Запрос вне списка возвращает 403 (forbidden_ip / forbidden_origin).

curl https://api.hintdata.ru/v1/suggest/address \
  -H "Authorization: Token sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "query": "москва" }'

Если нужен не свой интерфейс, а работающее поле с подсказками — подключите виджет @hintdata/js. Он навешивается на обычное поле формы — <input> или <textarea> — и дальше работает сам: держит паузу после набора, отменяет устаревшие запросы и углубляется по уровням адреса. Связанные поля (город → улица → дом) и заполнение соседних полей задаются атрибутами, без единой строки JavaScript.

Три способа подключения равнозначны: тег <script> с нашего домена, тот же файл с публичного CDN unpkg или установка пакетом из npm. Стили встроены, отдельный файл подключать не нужно.

<!-- 1. подключите виджет: наш домен или независимый CDN -->
<script src="https://api.hintdata.ru/widget.js" data-key="pk_xxx"></script>

<!-- 2. добавьте атрибут к полю — этого достаточно -->
<input data-hintdata="address">

<!-- связанные поля и заполнение соседних — тоже атрибутами -->
<input data-hintdata="address" data-parent="#city" data-to="street">
<input data-hintdata="address" data-fill-postal="#zip" data-fill-city="#city">

В браузер ставится только публичный pk_-ключ. Он ограничивается списком разрешённых сайтов (и при необходимости IP) в разделе «API-ключи». Исходный код и полный список опций — в репозитории пакета.

Лимиты и квоты

Лимиты зависят от тарифа. При превышении возвращается 429 Too Many Requests с заголовком Retry-After. Подсказки расходуют суточный пул; стандартизация и кадастр — отдельные пулы (кадастр — оплата за запрос). Актуальные цены и условия — на странице «Тарифы».

Ограничения одного запроса одинаковы на всех тарифах: подсказок за раз — до 20 (count), точных записей по идентификатору — до 300, строк за один разбор — до 1 000 для адреса и до 10 000 для ФИО, телефона, почты и даты рождения.

Тариф	Подсказок в сутки	RPS	Поля адреса
`Бесплатный`	10 000	10	базовые
`Старт`	50 000	10	базовые
`Расширенный`	100 000	15	+ кольцевая (МКАД/КАД)
`Бизнес`плавающий	200 000 – 3 000 000	от 20, растёт с объёмом	+ кадастр, часовой пояс, квартиры, метро
`Корпоративный`	безлимит	по SLA	все

Бизнес — плавающий тариф: суточный лимит подсказок настраивается в диапазоне 200 000–3 000 000 (шаг 100 000), RPS увеличивается пропорционально лимиту (от 20). Корпоративный тариф — по договору.

Справочная информация

Форматы ответа

По умолчанию все методы отвечают в нашем формате — вложенный объект с components, codes и geo. У каждого метода есть второй адрес, по которому тот же ответ приходит в формате DaData.

Способ	Формат
`/v1/…`	наш формат: вложенный, со всеми полями (рекомендуем)
`/suggestions/api/4_1/rs/…`	формат DaData: те же адреса методов и та же форма ответа — их SDK подключается без доработок
`/api/v1/clean/…`	стандартизация в формате DaData; тип `name` на этом адресе — стандартизация ФИО
стандартизация: тело-массив `["…"]`	ответ придёт в формате DaData; чтобы получить наш — присылайте `{"items": ["…"]}`

По совместимому адресу три справочника зовутся иначе: fts_unit — таможни, okved2 — ОКВЭД, postal_unit — почтовые отделения. Остальные имена совпадают.

Без пустых полей (omit_null)

По умолчанию в нашем формате ключ есть, даже когда значения нет: тогда оно равно null. Передайте в теле запроса "omit_null": true, и ключи со значением null уйдут из ответа на любой глубине. Пустые массивы, пустые строки, 0 и false остаются: пустой список значит «нет ни одного», а не «неизвестно». Параметр работает во всех методах нашего формата, где тело запроса — объект. В формате DaData набор ключей всегда полный.

Поля адресов по тарифам

Часть полей адресного ответа доступна начиная с определённого тарифа. В нашем формате недоступные поля опускаются — ключа нет в JSON. В формате DaData набор ключей всегда полный, недоступные поля приходят со значением null.

Тариф	Поля
Все тарифы	компоненты адреса и корпус (`house_num`/`block`), ФИАС/КЛАДР, индекс, ОКАТО, ОКТМО, ИФНС ФЛ/ЮЛ (`tax_office`, `tax_office_legal`), признак адмцентра (`capital_marker`), история переименований
Расширенный и выше	положение относительно кольцевой (`beltway_hit`, `beltway_distance`)
Бизнес и выше	кадастровый номер (`cadastral_num`), часовой пояс (`timezone`), количество квартир в доме (`house_flat_count`), площадь и стоимость квартиры, ближайшее метро

Коды ошибок

Стандартные HTTP-коды. Тело ошибки — { "error": "<код причины>" } (строковый код, например unauthorized, forbidden_scope).

Код	error	Значение
`200`	—	Успех.
`400`	`invalid_json`	Некорректное тело запроса.
`401`	`unauthorized`	Нет ключа или ключ неверный.
`402`	`insufficient_balance`	Недостаточно средств на платном пуле (стандартизация/кадастр).
`403`	`forbidden_scope`	У ключа нет нужного доступа к методу/домену.
`404`	`unknown route`	Неизвестный путь или домен.
`429`	`rate_limited` / `quota_exceeded`	Превышен лимит запросов в секунду или суточный пул подсказок — см. заголовок `Retry-After`.
`503`	`no_capacity` / `service_unavailable`	Сервис временно недоступен (нет узла / бэкенд недоступен).

OpenAPI и справочник API

API описан в формате OpenAPI 3.1: по описанию можно сгенерировать клиент на любом языке. Интерактивный справочник — api.hintdata.ru/docs: методы, параметры запросов, коды ошибок и пробный запрос с вашим ключом прямо со страницы. Описаны методы адресов, организаций и банков.

Описание	Адреса методов	Файлы
Основное	`/v1/…`	native.json, native.yaml
Совместимое с DaData	`/suggestions/api/4_1/rs/…`	dadata.json, dadata.yaml

У совместимого описания базовый адрес — https://api.hintdata.ru/suggestions/api/4_1/rs, как у DaData: клиент переключается между сервисами заменой базового адреса.

Генерация клиента

Ключ передаётся в заголовке Authorization со значением Token <ключ>. В сгенерированном клиенте задайте его как API-ключ в заголовке Authorization — значение целиком, вместе со словом Token.

# TypeScript-типы (openapi-typescript)
npx openapi-typescript https://api.hintdata.ru/openapi/native.json \
  --default-non-nullable false -o hintdata.d.ts

# C# (Kiota)
kiota generate -l CSharp -d https://api.hintdata.ru/openapi/native.json \
  -c HintDataClient -n HintData.Client -o ./HintData

# другие языки (openapi-generator), например Python
docker run --rm -v "$PWD":/local openapitools/openapi-generator-cli generate \
  -i https://api.hintdata.ru/openapi/native.json -g python -o /local/hintdata