API подсказок по адресам
Ищет адреса по любой части адреса от региона до дома («тверская нижний 12» → «Нижегородская обл, г Нижний Новгород, ул Тверская, д 12»). Также ищет по почтовому индексу («105568» → «г Москва, ул Магнитогорская»).
Что умеет и не умеет
✔️ Работает по всем странам мира (по России до квартиры, по Белоруссии до дома, по остальным странам — до города). Ищет и показывает результаты как на русском языке («Самара, пр-кт Металлургов»), так и на английском («Russia, gorod Samara, prospekt Metallurgov»).
✔️ Находит актуальные адреса по историческим названиям (Свердловск → Екатеринбург) и синонимам (Питер → Санкт-Петербург).
✔️ Ищет по частичному совпадению («москва болот» → «г Москва, Болотная наб»), но только в последнем слове запроса («мос болот» не найдет).
✔️ Исправляет опечатки («самара авиционная») и запросы в неправильной раскладке («vjcrdf» → «москва»).
✔️ Раскладывает выбранный адрес на гранулярные части (от региона до квартиры).
✔️ Поддерживает гранулярные подсказки по отдельным частям адреса (регионы, города, улицы, дома).
✔️ Подсказывает адреса в конкретных регионах, районах, городах и населенных пунктах. Понимает названия («Петергоф»), коды КЛАДР («7800000800000») и ФИАС («8f238984-812b-4bb1-850b-49749fb5c56d»).
✔️ Учитывает, где вы находитесь (в связке с методом город по IP-адресу).
❌ Автоматически (без участия человека) обработать адреса из базы или файла.
❌ Транслитерировать (moskva suhonskaja 11 → 127642, г Москва, ул Сухонская, д 11).
Подсказки не подходят для автоматической обработки адресов. Они предлагают варианты, но не гарантируют, что угадали правильно. Поэтому окончательное решение всегда должен принимать человек.
Для автоматической обработки и транслитерации используйте API Стандартизации
Как вызвать
Чтобы вызвать метод, зарегистрируйтесь и подтвердите почту.
Укажите при вызове:
Параметры запроса
| Название | Тип | Обяз.? | По умолч. | Описание |
|---|---|---|---|---|
| query | string | ✓ | Текст запроса | |
| count | number | 10 | Количество результатов (максимум — 20) | |
| language | string | ru | На каком языке вернуть результат (ru / en) | |
| locations | array [object] | Ограничение по родителю (страна, регион, район, город, улица) | ||
| locations_geo | array [object] | Ограничение по радиусу окружности | ||
| locations_boost | array [object] | Приоритет города при ранжировании | ||
| from_bound to_bound | object | Гранулярные подсказки по адресу |
Что в ответе
Объект с массивом подсказок в поле suggestions :
Идентификатор OpenStreetMap для Белоруссии.
Для остальных стран — не заполняется.
Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.
Заполняются при выборе конкретной подсказки. До этого они пустые.
Координаты есть у 97% домов в Москве, 91% в Санкт-Петербурге, 69% в других городах-миллиониках и 47% по остальной России.
Площадь и стоимость есть у 70% квартир в России.
Коды ответа на запрос
| HTTP-код ответа | Описание |
|---|---|
| 200 | Запрос успешно обработан |
| 400 | Некорректный запрос (невалидный JSON или XML) |
| 401 | В запросе отсутствует API-ключ |
| 403 | В запросе указан несуществующий API-ключ Или не подтверждена почта Или исчерпан дневной лимит по количеству запросов |
| 405 | Запрос сделан с методом, отличным от POST |
| 413 | Слишком большая длина запроса или слишком много условий |
| 429 | Слишком много запросов в секунду или новых соединений в минуту |
| 5xx | Произошла внутренняя ошибка сервиса |
Примеры вызова
Гранулярные подсказки (отдельно регион, отдельно город, отдельно улица)
Ограничения
Для иностранных адресов заполнен ограниченный набор полей, вне зависимости от тарифного плана: почтовый индекс, страна, регион, населенный пункт, часовой пояс и геокоординаты. Прочие поля — пустые.
Количество условий в параметрах locations и locations_boost — не более 10.
Длина запроса (параметр query ) — не более 300 символов.
Количество запросов в день — в соответствии с тарифным планом.
Максимальная частота запросов — 20 в секунду с одного IP-адреса.
Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.
Частые вопросы
По адресам
Да, есть подсказки по всем городам мира. Чтобы их включить, передайте параметр country = «*» :
Как включить подсказки на английском языке (транслитом)?
Передайте параметр language = «en» :
Как часто обновляется справочник адресов (ФИАС)?
Один раз в неделю, на выходных.
Почему индекс неправильный — не такой, как у Почты России?
Дадата работает по объединенному справочнику налоговой службы (ФИАС) и Почты России. В нем исправлены более 7 000 некорректных и отсутствующих индексов.
К сожалению, справочник индексов Почты детализирован только до населенных пунктов. Привязки к улицам и домам нет. Поэтому все-все индексы исправить не удалось.
Если получили от Дадаты неправильный индекс — отправьте адрес через специальную форму. Мы исправляем ошибки ежемесячно.
Почему подсказки не возвращают геокоординаты и район города?
Подсказки возвращают геокоординаты и район после того, как человек выбрал конкретный адрес из списка.
Почему подсказки не возвращают площадь квартиры, ближайшее метро и часовой пояс?
Эти поля возвращаются только для тарифа «Максимальный».
Почему подсказки не возвращают коды качества?
Подсказки в принципе не возвращают коды качества, потому что не занимаются разбором адресов. Для этого есть стандартизация.
Почему на картах дом есть, а в подсказках — нет?
Подсказки используют справочник адресов налоговой службы (ФИАС). В нем нет некоторых реально существующих домов и строений. К сожалению, более полной базы, чем ФИАС, просто не существует.
Чтобы добавить дом в подсказки, отправьте его через специальную форму. Мы пополняем справочник ежемесячно.
Общие
Подсказки перестанут подсказывать ツ До начала нового дня, затем снова заработают.
10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы.
Стоимость
Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.
Как устроены адресные подсказки «Дадаты»
«Дадата» с 2014 года пилит «Подсказки». Они помогают быстро и без ошибок вводить контактные данные: адреса, реквизиты банков и компаний, емейлы — вот это все.
Штука устроена затейливо, и мы решили о ней рассказать. Возьмем подсказки по адресам, потому что они самые сложные.
Справочники и индексация
«Подсказки» знают, что подсказывать, потому что у них есть гигантские справочники. Хоть статья эта о подсказках по адресам, для пользы дела перечислю и другие справочники «Дадаты».
Искать что-то в неподготовленном справочнике — дело долгое и неблагодарное. Поэтому мы берем чудесную библиотеку Lucene и превращаем исходные данные в поисковый индекс.
Поисковый индекс — такой формат, при котором находить информацию можно оооочень быстро.
Физически индекс представляет из себя набор двух типов файлов:
Индекс и данные по адресам в сумме занимают 20 гигабайт. По компаниям примерно столько же, а остальные весят меньше.
Из официальных справочников для экономии убираем данные, по которым не ищем и которые не возвращаем. Также вычищаем дубли и очевидные ошибки. Например, в индексе по адресам нет:
Поиск адекватных подсказок
«Подсказки» работают довольно заковыристо. Для простоты разобью процесс на этапы и расскажу о каждом подробнее. Если останутся вопросы, спрашивайте в комментариях.
1. Поехали: человек вводит символы в поле «Подсказок».
Каждый новый символ запускает серверный запрос с новыми параметрами. Частоту запросов можно подкрутить, об этом дальше
2. Плагин «Подсказок» собирает запрос. Между человеком и сервером трудится диспетчер — jQuery-плагин «Подсказок» (исходный код на GitHub).
Плагин принимает данные для поиска, упаковывает в запрос и передает на сервер.
От себя плагин добавляет, сколько адресов вернуть. Число задают как параметр при интеграции «Подсказок». Если количество не указали, «Подсказки» возвращают 10 результатов. Больше 20 просить бесполезно — вернутся только 20 вариантов.
Также плагин передает параметры фильтрации, их тоже задают при интеграции «Подсказок». Вот какие фильтры существуют:
А еще есть такая штука как geoboost. Похожа на ограничение по родителю, но влияет только на ранжирование адресов. Хотите, чтобы омские улицы стояли выше московских — пожалуйста.
«Яндекс.Деньги» по умолчанию предлагают улицы Москвы. Ограничение на город настраивают через параметры фильтрации «Подсказок»
По умолчанию в плагине включена геолокация: он передает на сервер местоположение пользователя. Это тоже параметр поиска.
При интеграции можно регулировать задержку запросов к серверу. Например, поставили задержку 100 миллисекунд. Если некий виртуоз за 100 миллисекунд вбил четыре символа, на сервер уйдет один запрос с четырьмя новыми символами. А не четыре запроса по одному.
Плагин работает в IE начиная с версии 10 и всех нормальных браузерах. Еще ему нужен jQuery 1.10+.
3. Проверяем кэш. Когда запрос приходит на сервер, «Подсказки» первым делом смотрят в кэш. Ищут там совпадение по всем параметрам запроса до единого.
Кэширование спасает от коротких запросов вроде «М», «Мо», «С». Таких однотипных комбинаций приходит колоссальное количество. Поскольку каждая буква — это отдельный запрос, кэширование защищает сервер от миллионов обращений к поисковому индексу.
Кэш целиком помещается в оперативной памяти, в нем лежит 100 000 результатов.
4. Ищем подходящие подсказки в индексе. Если в кэше ничего подходящего нет, «Подсказки» направляются в поисковый индекс.
«Подсказки» ищут адреса́ по:
Алгоритм подразумевает, что неполное или ошибочное в запросе только последнее слово. Если человек написал «Москва Турч», «Подсказки» ищут «Москва Турч*».
Запросы вроде «москв турч» не пройдут. Проблем это не создает, потому что люди набирают адреса́ последовательно, и «Подсказки» последовательно предлагают правильное написание каждой части а́дреса
Если в плагине отключили геолокацию, по запросам в 1-2 символа «Подсказки» ищут только регионы, муниципальные районы и города. Дома́ сервис ищет со второго слова в запросе.
Каждому результату «Подсказки» назначают вес. Вес нужен, потому что алгоритм порой находит тысячи вариантов, особенно для коротких запросов. А вернуть можно максимум 20 штук. Поэтому «Подсказки» сортируют результаты по весу и возвращают топовые.
Алгоритм ранжирования результатов — ноу-хау «Дадаты». Это такая серьезная штука, что описывать ее подробно я не могу: проклянут разработчики.
5. Сортируем результаты. Если у результатов поиска одинаковый вес, «Подсказки» их сортируют. Алгоритм сортировки тоже самописный, поэтому снова сохраняю таинственность.
6. Готовим ответ. Адреса, которые возвращают «Подсказки», по формату немного отличаются от ФИАС:
7. Кэшируем. Прежде чем вернуть результат, «Подсказки» кэшируют запрос со всеми параметрами и с ответом.
Кэш ограничен 100 000 записей по алгоритму LRU, поэтому сервис выкидывает оттуда редкие запросы. Популярные же вроде «Мо» висят в кэше вечно.
8. Плагин рисует подсказки. Он принимает ответ от сервера, показывает адреса́ на экране и подсвечивает совпадения. Если во время ввода нажать Enter, плагин сравнит текст с найденными подсказками и подставит в поле самую подходящую.
API стандартизации адресов
✔️ Разбивает адрес по отдельным полям (регион, город, улица, дом, квартира).
✔️ Рассчитывает корректный индекс по данным Почты России.
✔️ Определяет координаты.
✔️ Показывает округ и район города, ближайшее метро, площадь и стоимость квартиры.
✔️ Достает коды КЛАДР, ФИАС, ОКАТО, ОКТМО и ИФНС.
Как вызвать
Чтобы вызвать метод, зарегистрируйтесь и подтвердите почту.
Укажите при вызове:
Что в ответе
Пример ответа
| Название | Длина | Описание |
|---|---|---|
| source | 250 | Исходный адрес одной строкой |
| result | 500 | Стандартизованный адрес одной строкой |
| postal_code | 6 | Индекс |
| country | 120 | Страна |
| country_iso_code | 2 | ISO-код страны |
| federal_district | 20 | Федеральный округ |
| region_fias_id | 36 | ФИАС-код региона |
| region_kladr_id | 19 | КЛАДР-код региона |
| region_iso_code | 6 | ISO-код региона |
| region_with_type | 131 | Регион с типом |
| region_type | 10 | Тип региона (сокращенный) |
| region_type_full | 50 | Тип региона |
| region | 120 | Регион |
| area_fias_id | 36 | ФИАС-код района |
| area_kladr_id | 19 | КЛАДР-код района |
| area_with_type | 131 | Район в регионе с типом |
| area_type | 10 | Тип района в регионе (сокращенный) |
| area_type_full | 50 | Тип района в регионе |
| area | 120 | Район в регионе |
| city_fias_id | 36 | ФИАС-код города |
| city_kladr_id | 19 | КЛАДР-код города |
| city_with_type | 131 | Город с типом |
| city_type | 10 | Тип города (сокращенный) |
| city_type_full | 50 | Тип города |
| city | 120 | Город |
| city_area | 120 | Административный округ (только для Москвы) |
| city_district_fias_id | 36 | ФИАС-код района города (заполняется, только если район есть в ФИАС) |
| city_district_kladr_id | 19 | КЛАДР-код района города (не заполняется) |
| city_district_with_type | 131 | Район города с типом |
| city_district_type | 10 | Тип района города (сокращенный) |
| city_district_type_full | 50 | Тип района города |
| city_district | 120 | Район города |
| settlement_fias_id | 36 | ФИАС-код населенного пункта |
| settlement_kladr_id | 19 | КЛАДР-код населенного пункта |
| settlement_with_type | 131 | Населенный пункт с типом |
| settlement_type | 10 | Тип населенного пункта (сокращенный) |
| settlement_type_full | 50 | Тип населенного пункта |
| settlement | 120 | Населенный пункт |
| street_fias_id | 36 | ФИАС-код улицы |
| street_kladr_id | 19 | КЛАДР-код улицы |
| street_with_type | 131 | Улица с типом |
| street_type | 10 | Тип улицы (сокращенный) |
| street_type_full | 50 | Тип улицы |
| street | 120 | Улица |
| house_fias_id | 36 | ФИАС-код дома |
| house_kladr_id | 19 | КЛАДР-код дома |
| house_type | 10 | Тип дома (сокращенный) |
| house_type_full | 50 | Тип дома |
| house | 50 | Дом |
| block_type | 10 | Тип корпуса/строения (сокращенный) |
| block_type_full | 50 | Тип корпуса/строения |
| block | 50 | Корпус/строение |
| entrance | 10 | Подъезд |
| floor | 10 | Этаж |
| flat_fias_id | 36 | ФИАС-код квартиры |
| flat_type | 10 | Тип квартиры (сокращенный) |
| flat_type_full | 50 | Тип квартиры |
| flat | 50 | Квартира |
| flat_area | 50 | Площадь квартиры |
| square_meter_price | 50 | Рыночная стоимость м² |
| flat_price | 50 | Рыночная стоимость квартиры |
| postal_box | 50 | Абонентский ящик |
| fias_id | 36 | ФИАС-код адреса (идентификатор ФИАС) |
| fias_code | Иерархический код адреса в ФИАС (СС+РРР+ГГГ+ППП+СССС+УУУУ+ДДДД) | |
| fias_level | 2 | Уровень детализации, до которого адрес найден в ФИАС |
| fias_actuality_state | Признак актуальности адреса в ФИАС | |
| kladr_id | 19 | КЛАДР-код адреса |
| capital_marker | 1 | Признак центра района или региона |
| okato | 11 | Код ОКАТО |
| oktmo | 11 | Код ОКТМО |
| tax_office | 4 | Код ИФНС для физических лиц |
| tax_office_legal | 4 | Код ИФНС для организаций |
| timezone | 50 | Часовой пояс города для России, часовой пояс страны — для иностранных адресов. Если у страны несколько поясов, вернёт минимальный и максимальный через слеш: UTC+5/UTC+6 |
| geo_lat | 12 | Координаты: широта |
| geo_lon | 12 | Координаты: долгота |
| beltway_hit | 8 | Внутри кольцевой? |
| beltway_distance | 3 | Расстояние от кольцевой в км. Заполнено, только если beltway_hit = OUT_MKAD или OUT_KAD, иначе пустое |
| qc_geo | 5 | Код точности координат |
| qc_complete | 5 | Код пригодности к рассылке |
| qc_house | 5 | Признак наличия дома в ФИАС |
| qc | 5 | Код проверки адреса |
| unparsed_parts | 250 | Нераспознанная часть адреса. Для адреса «Москва, Митинская улица, 40, вход с торца» вернет «ВХОД, С, ТОРЦА» |
| metro | Список ближайших станций метро (до трёх штук) |
Координаты есть у 97% домов в Москве, 91% в Санкт-Петербурге, 69% в других городах-миллиониках и 47% по остальной России.
Площадь и стоимость есть у 70% квартир в России.
Коды качества
Код проверки qc
Нужно ли вручную проверить распознанный адрес:
| Код qc | Описание | Нужно проверить вручную? |
|---|---|---|
| 0 | Адрес распознан уверенно | Нет |
| 2 | Адрес пустой или заведомо «мусорный» | Нет |
| 1 | Да | |
| 3 | Есть альтернативные варианты. Пример: «Москва Тверская-Ямская» — в Москве четыре Тверских-Ямских улицы. | Да |
Код пригодности к рассылке qc_complete
Годится ли адрес для доставки корреспонденции:
| Код qc_complete | Подходит для рассылки? | Описание |
|---|---|---|
| 0 | Да | Пригоден для почтовой рассылки |
| 10 | Под вопросом | Дома нет в ФИАС |
| 5 | Под вопросом | Нет квартиры. Подходит для юридических лиц или частных владений |
| 8 | Под вопросом | До почтового отделения — абонентский ящик или адрес до востребования. Подходит для писем, но не для курьерской доставки. |
| 9 | Под вопросом | Сначала проверьте, правильно ли Дадата разобрала исходный адрес |
| 1 | Нет | Нет региона |
| 2 | Нет | Нет города |
| 3 | Нет | Нет улицы |
| 4 | Нет | Нет дома |
| 6 | Нет | Адрес неполный |
| 7 | Нет | Иностранный адрес |
Признак наличия дома в ФИАС qc_house и код точности координат qc_geo
Уточняют вероятность успешной доставки письма:
| Код qc_house | Код qc_geo | Вероятность доставки | Описание |
|---|---|---|---|
| 2 | любой | Высокая | Дом найден в ФИАС |
| 10 | 0 | Высокая | Дом не найден в ФИАС, но есть на картах |
| 10 | 1 | Средняя | Дом не найден в ФИАС, но есть похожий на картах |
| 10 | ≥ 2 | Низкая | Дом не найден в ФИАС и на картах |
Код точности координат qc_geo
Точность координат адреса для курьерской доставки:
| Код qc_geo | Описание |
|---|---|
| 0 | Точные координаты |
| 1 | Ближайший дом |
| 2 | Улица |
| 3 | Населенный пункт |
| 4 | Город |
| 5 | Координаты не определены |
Коды ответа на запрос
| HTTP-код ответа | Описание |
|---|---|
| 200 | Запрос успешно обработан |
| 400 | Некорректный запрос |
| 401 | В запросе отсутствует API-ключ или секретный ключ Или в запросе указан несуществующий ключ |
| 403 | Не подтверждена почта Или недостаточно средств для обработки запроса, пополните баланс |
| 405 | Запрос сделан с методом, отличным от POST |
| 429 | Слишком много запросов в секунду или новых соединений в минуту |
| 5xx | Произошла внутренняя ошибка сервиса |
Примеры и интеграции
Ограничения
Максимальная частота запросов — 10 в секунду с одного IP-адреса.
Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.
Дадата не поддерживает вызов этого метода из браузерного JavaScript. Иначе злоумышленник мог бы похитить секретный ключ и использовать API за ваш счет.
