API search

API search позволяет искать объекты классификации ОКТМО: населенные пункты и муниципальные образования России.

Результат интерфейса search совместим с плагином jQuery autocomplete (https://jqueryui.com/autocomplete) и может быть использован для автоподстановки (автодополнения) данных. Подробный разбор примеров представлен отдельно: jQuery autocomplete, работа с картой, выполнение запросов на PHP. Демонстрацию автоподстановки также можно увидеть на главной странице сайта и в разделе каталог.

Стоимость и условия использования

Возможны следующие условия использования:

  • Демонстрационный тариф позволяет выполнять до 500 стандартных запросов в сутки бесплатно.
  • Платный тариф позволяет выполнять 300 станадртных запросов за 1 рубль. Пользователь может самостоятельно установить ежедневно списываемую сумму и количество доступных в сутки запросов. Тариф устанавливается в личном кабинете.

Стандартным запросом считается запрос к API search, без параметра limit (или со значением не больше 10) и без параметра distance_exact (или значением "false").
При значении параметра limit больше 10 каждые 10 полученных записей считаются как 1 стандартный запрос (например, если получено 15 записей, то такой запрос считается как 2 стандартных).
При значении параметр distance_exact каждые 10 полученных записей считаются как 2 стандартных запроса.

Общая информация, использумая в запросе и в ответе

Возможные значения и соответствия параметров level и oktmo_type (оба параметра могут быть использованы в запросе и ответе):

leveloktmo_type
4"г" - город, "пгт" - посёлок городского типа, "снп" - сельский населенный пункт
3"гп" - городское поселение, "сп" - сельское поселение, "вр" - внутригородской район, "мс" - межселенные территории
2"го" - городской округ, "мр" - муниципальный район, "мо" - муниципальный округ
1"суб" - субъект РФ, "гфз" - город федерального значения

Информация по определению расстояния
По умолчанию расстояние считается от указанной точки до многоугольника, упрощенного до нескольких точек. Такой способ расчета менее точен, чем поиск до истинного многоугольника, который может состоять из нескольких тысяч точек, но выполняется значительно быстрее. Для расчета точной дистанции (от точки до истинного многоугольника) следует использовать параметр запроса distance_exact=yes. Такой запрос имеет двойную стоимость.

Запрос

Формат запроса:
https://api.geotree.ru/address.php?key=demo-wpB0VbmfrQv8bYF&параметр1=значение1&параметр2=значение2...

  • Обязательным параметром запроса является только параметр key - ключ, который можно получить в личном кабинете
  • Для удобства отображения результата в браузере следует использовать параметр format=text
  • Большинство параметров можно использовать одновременно
  • При использовании ajax-ключа не допускается изменять параметры "distance_exact" и устанавливать значение "limit" больше 10
  • Значения в перечислениях разделяются запятой
  • В качестве значений типа boolean можно указывать: yes/no, true/false, 1/0
  • Расстояние указывается в километрах с точностью до 6 знаков после запятой
  • По умолчанию записи отсортированы по рейтингу, который устанавливается на основе уровня объекта (от 4 к 1), типа объекта (сначала крупные города), численности населения

Параметры фильтрации и сортировки:

  • term - искомая строка
    term=Волгогра - поиск по объектов по указанной строке (в том числе область, городской округ, город)
    term=клин московская - можно уточнить поисковой запрос, если найдено много записей

  • level - уровни ОКТМО. Один или несколько из списка: 1,2,3,4. По умолчанию выполняется поиск объектов любого уровня. Если указан уровень 4, то в порядке исключения к результату запроса добавляются города федерального значения (хотя для них параметр level равен "1"), так как фактически они являются и населенными пунктами
    level=4&term=Волгогра - информация по городу Волгоград
    level=1 - отображение всех субъектов РФ (в пределах параметра limit, которой по умолчанию равен 10)

  • oktmo_start - начало или полный код ОКМТО
    oktmo_start=25 - любые объекты, код которых начинается на 25 (Иркутская область)
    oktmo_start=257 - городские округа в Иркутской области
    oktmo_start=25&level=4 - населенные пункты в Иркутской области
    oktmo_start=25000000 - информация по только 1 объекту: Иркутская область

  • oktmo_list - список кодов ОКТМО, среди которых будет выполнен поиск. Перечисление до 100 шт.
    oktmo_list=52,22000000,75701000001 - информация по объектам: Омская область, Нижегородская область, город Челябинск

  • oktmo_priority - указанные и нижестоящие объекты будут иметь приоритет при выдаче
    term=клин&oktmo_priority=66,28648 - сначала будут отображены объекты, найденные в Смоленской области и Ржевском районе Тверской области, далее - все остальные

  • oktmo_parent - вывод только указанных и нижестоящих объектов. До 10 кодов ОКТМО
    level=4&oktmo_parent=01,84615,84701 - населенные пункты в Алтайском крае, Майминском районе Республики Алтай и городском округе Горно-Алтайск

  • oktmo_type - типы объектов, определенные по коду ОКТМО (один или несколько), возможные значения указаны выше
    oktmo_type=г,пгт&oktmo_parent=54 - города и посёлки городского типа Орловской области
    oktmo_type=мр,го&oktmo_parent=54 - муниципальные районы и городские округа Орловской области

  • lon, lat - долгота и широта (используется для определения расстояния)
    lon=38.770&lat=55.085 - к информации об объектах будет добавлено расстояние от города Коломна (сортировка будет использована по умолчанию)

  • distance_sort - расстояние, в пределах которого объекты будут отсортированы по расстоянию и отображены перед остальными. Указывается в километрах
    distance_sort=100&lon=38.770&lat=55.085&term=Октябрьское - показать объекты с именем "Октябрьское", с сортировкой по расстоянию в пределах 100км от указанной точки указанной точки (город Коломна), объекты не вошедшие в указанный радиус будут отсортированы по умолчанию

  • distance_priority - расстояние, в пределах которого объекты будут отображены перед остальными (сортировка по расстоянию при этом не производится)
    distance_priority=100&lon=38.770&lat=55.085&term=Октябрьское - показать объекты с именем "Октябрьское", с сортировкой по умолчанию, но сначала будут отображены объекты, находящиеся не дальше 100км от указанной точки (город Коломна)

  • distance_limit - ограничение по расстоянию
    distance_priority=100&lon=38.770&lat=55.085&term=Октябрьское - показать объекты с именем "Октябрьское", находящиеся не дальше 100км от указанной точки (город Коломна)

  • geopoint_only - поиск только тех объектов, внутри которых расположена точка, заданная параметрами lon и lat
    lon=37.54&lat=54.92&geopoint_only=1 - информация о текущей геоточке

  • center_level - максимальный уровень объектов, центром которых являются искомые объекты. Один или несколько из списка: 1,2,3.
    "1" - центры субъектов и города федерального значения
    "2" - центры районов и округов
    "3" - центры поселений
    center_level=1 - центры субъектов РФ
    center_level=3&oktmo_start=20617 - центры городских и сельских поселений Каменского района Воронежской области

  • search_by_oktmo - искать объекты по коду ОКТМО, указанному в параметре term (найденные объекты сортируются по коду ОКТМО):
    "1" - искать только по коду
    "2" - искать сначала по коду, потом по имени
    "3" - искать сначала по имени, потом по коду
    level=4&term=527&search_by_oktmo=2 - сначала будет отображен город Омск (т.к. его код начинается на 527), далее - населенный пункт "разъезд 527 км"
    level=4&term=527&search_by_oktmo=3 - сначала будет отображен населенный пункт "разъезд 527 км" (найден по имени), далее - город Омск (т.к. его код начинается на 527)
    Пример поиска и по имени, и по коду (когда параметр search_by_oktmo равен 3), можно увидеть в разделе каталог, вводя символы по одному: 52701

  • sort - сортировка. Возможно одно из значений: default, oktmo.
    oktmo_start=247&level=2&sort=oktmo - городские округа Ивановской области, отсортированные по коду ОКТМО

  • area_min, area_max - минимальная и/или максимальная площадь. По умолчанию объекты, площадь которых не известна, не включаются в результат. Указывается в квадратных километрах с точностью до 6 знаков после запятой.

  • area_null - включать ли объекты, для которых площадь неизвестна. Значение типа boolean. Если параметры area_min или area_max указаны, значение по умолчанию - false, в ином случае параметр не учитывается.
    level=4&oktmo_start=27706&area_max=1&area_null=1 - населенные пункты Гвардейского городского округа Калининградской области, имеющие площадь не более 1 кв. км, включая те, площадь которых неизвестна

  • population_min, population_max - минимальная и/или максимальная численность населения. По умолчанию объекты, численность населения которых не известно, не включаются в результат.

  • population_null - включать ли объекты, для которых численность населения неизвестна. Значение типа boolean. Если параметры population_min или population_max указаны, значение по умолчанию - false, в ином случае параметр не учитывается.
    level=4&oktmo_start=27706&population_min=100&population_null=1 - населенные пункты Гвардейского городского округа Калининградской области, в население которых не менее 100 человек, включая те, население которых не известно

Параметры выполнения запроса:

  • limit - максимальное количество записей. По умолчанию - 10. Параметр влияет на стоимость запроса, нельзя использовать с ключом для ajax-запросов
    level=4&lon=37.54&lat=54.92&distance_sort=100&limit=1 - ближайший населенный пункт в радиусе 100 км от указанной точки

  • count_records - Показать только количество записей, соответствующих запросу. Несовместим параметром term.
    oktmo_type=г&oktmo_parent=05&count_records=1 - количество городов в Приморском крае

  • fields - параметры, которые должны быть отображены для найденных записей
    fields=oktmo,value - для каждого элемента будет отображен код ОКТМО и полное имя
    fields=oktmo,name_display,parents - для каждого элемента будет отображен код ОКТМО, имя и список вышестоящих элементов

  • parent_fields - параметры, которые будут отображены для вышестоящих записей. Если параметр не указан, для родительских объектов будут отображены те же параметры, что и для найденных.
    level=4&fields=oktmo,name_display&parent_fields=oktmo,name_display,oktmo_type - для каждого найденного элемента будет отображен код ОКТМО, имя и список вышестоящих объектов, у которых будут отображены: код, имя, тип ОКТМО

  • distance_exact - рассчитывать точное расстояние. Влияет на стоимость запроса, нельзя использовать с ключом для ajax-запросов.

  • format - формат вывода:
    "json" - используется по умолчанию
    "text" - для удобного чтения в браузере
    format=text&fields=oktmo,value - отображение только кода ОКТМО и полного имени для каждого найденного элемента

Ответ

Результатом запроса является список найденных записей, содержащих следующие параметры:

  • value - полное имя, включающее имена объектов вышестоящих уровней. Уровень 3 для объектов уровня 4 указывается, только если в этом же муниципальном районе есть населенные пункты с таким же именем.

  • oktmo_short - код ОКТМО в сокращенном виде (без ступеней, значение которых равно "000")

  • oktmo - код ОКТМО длиной 8 символов для объектов уровней 1, 2 и 3; длиной 11 символов для объектов уровня 4.

  • name_display - имя в удобном для отображения виде

  • name_source - имя в том же виде, как указано в справочнике ОКТМО

  • name_without_type - имя без указания типа (можно использовать для дальнейшей сортировки по алфавиту)

  • name_type_short - только для объектов уровня 4: сокращенный тип, полученный из name_source

  • name_type_full - только для объектов уровня 4: полный тип, полученный из name_type_short

  • level - уровень объекта

  • oktmo_type - тип объекта

  • center_level - уровень объекта, центром которого является данный объект (только для объектов уровня 4)
    "1" - центр субъекта или город федерального значения
    "2" - центр района и/или округа
    "3" - центр городского или сельского поселения

  • unique_display - уровень, в котором параметр name_display является уникальным
    "0" - имя уникально в России
    "1" - имя уникально в субъекте РФ
    "2" - имя уникально в районе или округе
    "3" - имя уникально в городском или сельском поселении
    "4" - имя не является уникальным даже в своем городском или сельском поселении
    пример 1) рп Благовещенка - имя с типом уникально в России (параметр unique равен 0)
    пример 2) в Калининском районе Тверской области находятся две деревни "Дмитровское", но в разных сельских поселениях (параметр unique равен 3), поэтому для того что бы точно идентифицировать такие населенные пункты, следует указать сельское поселение:
    28620438131 - деревня Дмитровское, поселение Медновское, Калининский район, Тверская область
    28620418126 - деревня Дмитровское, поселение Заволжское, Калининский район, Тверская область

  • unique_without_type - уровень, в котором имя без типа (name_without_type) является уникальным (аналогично параметру unique_display)

  • unique_source - уровень, в котором имя без типа (name_source) является уникальным (аналогично параметру unique_display)

  • geo_type - тип геометрии
    "polygon" - многоугольник
    "point" - точка
    "level3" - географический центр родительского объекта уровня 3
    "level2" - географический центр вышестоящего объекта уровня 2
    "level1" - географический центр вышестоящего объекта уровня 1

  • siblings - количество соседних элементов

  • childs - количество нижестоящих элементов (массив, в котором ключ соответствует уровню, значение - количеству элементов)

  • parent_level - уровень родительского объекта (пример: для населенных пунктов в муниципальных районах уровень родительского объекта равен "3", для населенных пунктов в городских округах - "2").

  • population - численность населения

  • center_of - коды ОКТМО объектов, центром административным центром которых является данный объект (только для объектов уровня 4)

  • center_oktmo - код ОКТМО административного центра (только для объектов уровней 1, 2 и 3)

  • area - площадь

  • geo_center - географический центр

  • geo_center_inside - находится ли географический центр внутри территории

  • geo_inside - точка, расположенная внутри территории

  • geopoint - окружает ли объект точку, заданную параметрами запроса lon и lat

  • distance - расстояние до объекта в метрах (если, конечно, указаны параметры запроса lon и lat). По умолчанию расстояние считается от указанной точки до многоугольника, упрощенного до нескольких или нескольких десятков точек. Такой способ расчета менее точен, чем поиск до истинного многоугольника (который может состоять из нескольких тысяч точек), но выполняется значительно быстрее. Для расчета точной дистанции (от точки до истинного многоугольника), следует использовать параметр запроса distance_exact=yes, но такой запрос будет стоить дороже.

  • parents - массив с информацией о вышестоящих объектах (например, для сельского населенного пункта: информация о субъекте РФ, о муниципальном районе, о сельском поселении)