API search

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

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

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

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

Запрос

Пример запроса:
https://api.geotree.ru/search.php?key=ВАШ_КЛЮЧ&term=нов&level=4

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

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

• key - ключ, доступен в личном кабинете после регистрации

• 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 км от указанной точки

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

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

• 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).

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