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

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

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

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

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

Ключ можно ограничить списком IP-адресов или подсетей. Запрос с адреса вне списка возвращает 403.

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. Исходный код и полный список опций — в репозитории пакета.

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

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

Тариф	Подсказок в сутки	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.ru поддерживается DaData-совместимый плоский data-формат.

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

На DaData-совместимом URL имена некоторых справочников отличаются от основных. Для drop-in миграции поддерживаются их псевдонимы: fts_unit → таможни, okved2 → ОКВЭД, postal_unit → почтовые отделения. Остальные имена совпадают.

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

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

Тариф	Поля
Все тарифы	компоненты адреса и корпус (`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).