API search

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

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

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

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

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

Запрос

Пример запроса:
https://api.geotree.ru/search.php?term=нов&level=4

  • Большинство параметров можно использовать одновременно
  • Значения в перечислениях разделяются запятой
  • В качестве значений типа 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 км от указанной точки

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