Сервис прямого геокодирования

Общие сведения

Сервис выполняет задачи поиска объектов на карте по произвольной текстовой адресной строке. Используется для поиска объектов на карте по текстовой строке или для получения пространственной составляющей для адресной информации в веб-сайтах, мобильных и настольных приложениях.

Наилучший результат достигается при четкой структурированности задаваемого адреса: регион -> населенный пункт -> улица -> дом. Сервис возвращает структурированное описание объекта (номер дома, улица, населенный пункт, административное подчинение) и его координаты.

Доступны режимы поиска по введенной строке и подсказок по мере введения текста (suggest).

Принципы работы сервиса

Сервис работает по протоколу HTTP(S).

Параметры запроса передаются в формате QUERY STRING, значения параметров закодированы в PERCENT-ENCODING.

Запрос к сервису имеет следующий общий формат:

http://<адрес_сервера>/<вид_запроса>?guid=XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX&<остальные_параметры>

Значения указанных в строке запроса параметров описываются ниже в данном документе.

Результатом запроса является ответ в формате GeoJSON (JSON) в зависимости от вида запроса и параметров запроса, в кодировке UTF-8.

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

  • Поисковый запрос объектов по текстовой строке (search).

  • Запрос автозаполнения текстовой строки для поиска (suggest).

Найденные объекты сортируются по релевантности (чем больше совпадение найденного объекта с введенной текстовой строкой, тем выше в списке он находится). При указании сервису опорной точки результаты также сортируются с учетом удаленности от указанной точки.

Сервис выдает результаты как в простом виде для быстрого просмотра, так и в структурированной форме, где адрес разбивается на отдельные элементы. Для каждого из элементов адреса возвращается набор характеристик, в том числе значения кодов ОКТМО, ФИАС, ОКСМ и проч.

Алгоритм поиска умеет исправлять небольшие ошибки, опечатки, различные варианты написания типов адресных элементов, но в любом случае наилучшие результаты поиска достигаются при правильно введенном адресе.

Параметры запросов и принципы их обработки

Принципы обработки параметров:

  • обработка параметров проводится без учета регистра (case insensitive);

  • при отсутствии или ошибочном значении необязательного параметра в запросе используется значение по умолчанию;

  • порядок следования параметров в запросе не имеет значения;

  • при передаче нескольких одинаковых параметров в запросе используется значение первого параметра, все остальные значения игнорируются.

Параметры запроса представлены в таблице.

Параметры запроса

N п/п

Параметр

Возможные значения

Значение по умолчанию

Описание

1

guid

текст

Ключ лицензии пользователя

2

text

текст

Строка для поиска

3

count

число

10

Максимальное количество возвращаемых результатов

4

format

  • regular

  • geojson:suggest

  • geojson:suggestWithCoords

  • geojson:full

  • simple

geojson:full

Вид результата запроса на выходе:

  • regular - основной формат результата поиска, результат в формате GeoJSON;

  • geojson:suggest – формат результата для запроса автозаполнения текстовой строки для поиска, содержит теги оформления, подсказки смены раскладки клавиатуры, результат в формате GeoJSON;

  • geojson:suggestWithCoords – формат результата для запроса автозаполнения текстовой строки для поиска, содержит только объекты с координатами и не содержит тегов оформления и подсказок, результат в формате GeoJSON;

  • geojson:full - полный перечень показателей для результатов поиска в формате GeoJSON, используется для отладки и может быть изменен по усмотрению разработчика;

  • simple – упрощенный вариант результатов поиска, содержит только название и координаты найденных объектов, формат - JSON

5

mode

search, geocode

search

Режим поиска адреса:

  • search – поиск наиболее подходящего адреса или объекта, максимально совпадающего с поисковой строкой. Используется для поиска объектов на веб-сайтах, в пользовательских интерфейсах;

  • geocode – геокодирование адреса. Поиск адресов или объектов, максимально совпадающих с поисковой строкой, с более жесткими правилами учета иерархии объектов и ошибок в написании. Поисковая строка обязательно должна содержать названия регионов, населенных пунктов, для более точной привязки объектов. Используется для геокодирования хорошо структурированных данных для минимизации возможных ошибок геокодинга

6

data

all, address

all

Вид данных, среди которых осуществляется поиск:

  • all - поиск среди всех доступных объектов;

  • address - поиск по адресным данным (включая улицы, административное деление)

7

lang

ru, en

ru

Язык отображения результатов:

  • ru - русский;

  • en - английский (транслитерация)

8

spatialin

  • EPSG:3857

  • EPSG:4326

  • GSK:42

  • GSK:42_DIRECT

  • EPSG:4923

  • GSK:90

  • GSK:90_DIRECT

  • GSK:9002

  • GSK:9011

  • GSK:2011

  • GSK:2011_DIRECT

EPSG:4326

Координатная система входных данных:

  • EPSG:4326 – WGS84, десятичные градусы;

  • EPSG:3857 – Web Mercator Auxiliary Sphere;

  • GSK:42 – СК42, ГОСТ Р 32453-2013, переход через ПЗ-90.02;

  • GSK:42_DIRECT – СК42, ГОСТ 51794-2001;

  • EPSG:4923 – ПЗ90, переход по версии EPSG;

  • GSK:90 – ПЗ90, ГОСТ 51794-2008 (Приложение Б), переход через GSK:42;

  • GSK:90_DIRECT – ПЗ90, ГОСТ 51794-2008 (Приложение Г);

  • GSK:9002 – ПЗ-90.02, ГОСТ Р 32453-2013 (Приложение В);

  • GSK:9011 – ПЗ-90.11, справочный документ «Параметры Земли 1990 года» (ПЗ-90.11) Минобороны России;

  • GSK:2011 – ГСК2011, ПРИКАЗ от 23 марта 2016 г. N П/0134 ОБ УТВЕРЖДЕНИИ ПАРАМЕТРОВ ГСК2011, переход через GSK:9011;

  • GSK:2011_DIRECT – ГСК2011, ПРИКАЗ от 23 марта 2016 г. N П/0134 ОБ УТВЕРЖДЕНИИ ПАРАМЕТРОВ ГСК2011

9

spatialout

  • EPSG:3857

  • EPSG:4326

  • GSK:42

  • GSK:42_DIRECT

  • EPSG:4923

  • GSK:90

  • GSK:90_DIRECT

  • GSK:9002

  • GSK:9011

  • GSK:2011

  • GSK:2011_DIRECT

EPSG:4326

Координатная система входных данных:

  • EPSG:4326 – WGS84, десятичные градусы;

  • EPSG:3857 – Web Mercator Auxiliary Sphere;

  • GSK:42 – СК42, ГОСТ Р 32453-2013, переход через ПЗ-90.02;

  • GSK:42_DIRECT – СК42, ГОСТ 51794-2001;

  • EPSG:4923 – ПЗ90, переход по версии EPSG;

  • GSK:90 – ПЗ90, ГОСТ 51794-2008 (Приложение Б), переход через GSK:42;

  • GSK:90_DIRECT – ПЗ90, ГОСТ 51794-2008 (Приложение Г);

  • GSK:9002 – ПЗ-90.02, ГОСТ Р 32453-2013 (Приложение В);

  • GSK:9011 – ПЗ-90.11, справочный документ «Параметры Земли 1990 года» (ПЗ-90.11) Минобороны России;

  • GSK:2011 – ГСК2011, ПРИКАЗ от 23 марта 2016 г. N П/0134 ОБ УТВЕРЖДЕНИИ ПАРАМЕТРОВ ГСК2011, переход через GSK:9011;

  • GSK:2011_DIRECT – ГСК2011, ПРИКАЗ от 23 марта 2016 г. N П/0134 ОБ УТВЕРЖДЕНИИ ПАРАМЕТРОВ ГСК2011

10

x

число

Координата X точки в проекции spatialin. При указании в запросе координат x, y результаты поиска сортируются по релевантности с учетом удаленности от заданной точки

11

y

число

Координата Y точки в проекции spatialin. При указании в запросе координат x, y результаты поиска сортируются по релевантности с учетом удаленности от заданной точки

12

minAddrAccuracy

число

0

Минимальная степень совпадения найденного адреса с введенной текстовой строкой в диапазоне от 0 до 100 для включения его в результаты поиска

13

minCount

число

0

Системный параметр, deprecated. Минимальное число результатов, которые выдаются в ответе, если значения параметра minAddrAccuracy > 0

14

maxCount

число

count

Системный параметр, deprecated. Максимальное число результатов, которые выдаются в ответе, если значения параметра minAddrAccuracy > 0

Иерархическая организация адресной информации и типы адресных элементов

Для достижения наилучших результатов поиска, особенно в режиме mode=geocode, следует передавать адрес, соблюдая иерархическую последовательность элементов. Эта иерархическая последовательность соответствует официальному административному делению Российской Федерации, а также формату записи адресов.

Иерархические уровни также соответствуют типам объектов, возвращаемым в ответе сервиса:

  • country - страны мира;

  • admin - субъекты Российской Федерации (регионы) и соответствующие им объекты других государств;

  • district_a - административные округа и районы городов федерального значения Российской Федерации и соответствующие им объекты других государств;

  • admin1 - муниципальные районы и городские округа субъектов Российской Федерации и соответствующие им объекты других государств;

  • district_a1 - внутригородские территории городов федерального значения и административные единицы городских округов РФ (административные районы города, внутригородские округа, внутригородские районы, сельские территории) и соответствующие им объекты других государств;

  • admin2 - городские и сельские поселения муниципальных районов Российской Федерации и соответствующие им объекты других государств;

  • town - населенные пункты Российской Федерации (согласно ОКТМО) и соответствующие им объекты других государств;

  • district_t - административные единицы населенных пунктов Российской Федерации (внутригородские территории, административные районы и административные округа городов) и соответствующие им объекты других государств;

  • quarter - отдельные кварталы, микрорайоны, поселки в ранге микрорайонов, входящие в состав более крупных административных подразделений Российской Федерации и соответствующие им объекты других государств;

  • village - дачные поселки, коттеджные поселки, садоводческие некоммерческие товарищества и партнерства, дачные и садовые участки Российской Федерации и соответствующие им объекты других государств;

  • road - автомобильные дороги и улицы населенных пунктов Российской Федерации и соответствующие им объекты других государств;

  • address - номера домов зданий и сооружений Российской Федерации и соответствующие им объекты других государств.

Объекты из уровней district_a, district_a1, district_t, как правило, не встречаются в адресах, поэтому не указываются.

Пример правильно структурированной записи адреса для наилучшего результата геокодирования:

Российская Федерация, город Москва, административный округ Западный, улица Барклая, дом 6 строение 3

Запрос автозаполнения текстовой строки для поиска (suggest)

Для получения данных с целью создания текстовых подсказок автозаполнения адресной строки используются запросы к сервису следующего вида:

http://<адрес_сервера>/suggest?guid=XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX&...

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

  • текст для поиска (параметр text), не менее трех символов;

  • вид представления результатов поиска (параметр format);

  • установить количество результатов поиска (параметр count);

  • задать опорное местоположение для дополнительной сортировки полученных результатов (параметры x, y).

Также можно задать дополнительные настройки:

  • выставить язык для вывода результатов (параметр lang);

  • установить параметры проекции для вывода результатов (параметры spatialin, spatialout).

При выполнении запросов suggest настоятельно рекомендуется указывать опорную точку, относительно которой будет осуществляться сортировка результатов.

Запрос suggest адресов (geojson:suggest) с текстом «мос»

Запрос

Пример простого запроса suggest адресов, формат geojson:suggest, с опорной точкой в Москве и текстом «мос»:

http://<адрес_сервера>/suggest?guid=XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX&text=мос&data=address&format=geojson:suggest&count=5&x=37.587748&y=55.746149

Ответ

В результате выполнения запроса возвращаются данные в формате GeoJSON, относящиеся к Москве:

{
   "features": [
       // Первый найденный объект.
       {                               // Первый найденный объект.
           "geometry": null,
           "properties": {
       // Вид найденного объекта (address - адрес или адресный объект).
               "dataType": "address",
       // Массив индексов начала и конца участков текста в строке suggest, которые подсвечиваются пользователю.
               "hl": [
                   [
                       0,
                       3
                   ]
               ],
       // Текст, который должен быть помещен в поле поиска при выборе данной текстовой подсказки.
               "search": "Россия, Москва",
       // Подсказка, показываемая пользователю.
               "suggest": "Москва, Россия"
           },
           "type": "Feature"
       },
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       0,
                       3
                   ]
               ],
               "search": "Россия, Московская область",
               "suggest": "Московская область, Россия"
           },
           "type": "Feature"
       },
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       5,
                       8
                   ]
               ],
               "search": "Россия, Москва, ММДЦ Москва-Сити",
               "suggest": "ММДЦ Москва-Сити, Москва, Россия"
           },
           "type": "Feature"
       },
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       21,
                       24
                   ]
               ],
               "search": "Россия, Москва, жилой комплекс Мечта Москвича",
               "suggest": "жилой комплекс Мечта Москвича, Москва, Россия"
           },
           "type": "Feature"
       },
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       0,
                       3
                   ],
                   [
                       18,
                       21
                   ]
               ],
               "search": "Россия, Москва, Московская аллея",
               "suggest": "Московская аллея, Москва, Россия"
           },
           "type": "Feature"
       }
   ],
   "query": "мос",       // Текст поискового запроса.
   "type": "FeatureCollection" }

Пример запроса и ответа на Санкт-Петербург

Тот же запрос с опорной точкой в районе Санкт-Петербурга:

http://<адрес_сервера>/suggest?guid=XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX&text=мос&data=address&format=geojson:suggest&count=5&x=30.380906&y=59.911373

В ответе содержатся объекты в окрестностях Санкт-Петербурга:

{
   "features": [
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       0,
                       3
                   ]
               ],
               "search": "Россия, Санкт-Петербург, Московский район",
               "suggest": "Московский район, Санкт-Петербург, Россия"
           },
           "type": "Feature"
       },
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       8,
                       11
                   ]
               ],
               "search": "Россия, Санкт-Петербург, Большая Московская улица",
               "suggest": "Большая Московская улица, Санкт-Петербург, Россия"
           },
           "type": "Feature"
       },
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       6,
                       9
                   ]
               ],
               "search": "Россия, Санкт-Петербург, Малая Московская улица",
               "suggest": "Малая Московская улица, Санкт-Петербург, Россия"
           },
           "type": "Feature"
       },
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       0,
                       3
                   ]
               ],
               "search": "Россия, Санкт-Петербург, Московский проспект",
               "suggest": "Московский проспект, Санкт-Петербург, Россия"
           },
           "type": "Feature"
       },
       {
           "geometry": null,
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       0,
                       3
                   ]
               ],
               "search": "Россия, Санкт-Петербург, Московское шоссе",
               "suggest": "Московское шоссе, Санкт-Петербург, Россия"
           },
           "type": "Feature"
       }
   ],
   "query": "мос",
   "type": "FeatureCollection" }

Запрос suggest адресов (geojson:suggestWithCoords) с текстом «мос»

Пример простого запроса suggest, формат выдачи данных geojson:suggestWithCoords, с опорной точкой в Москве и текстом «мос»:

http://<адрес_сервера>/suggest?guid=XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX&text=мос&data=address&format=geojson:suggestWighCoords&count=5&x=37.587748&y=55.746149

В результате выполнения запроса возвращаются те же данные, что и в случае формата geojson:suggest, с заполненными данными о геометрии найденных объектов (как правило, в режиме suggest геометрия объектов не требуется, поэтому ее не стоит получать без необходимости): 

{
 {
   "features": [
       {
           "bbox": [
               36.8037544,
               55.1422463,
               37.9678193,
               56.0209193
           ],
           "geometry": {
               "coordinates": [
                   37.617629223,
                   55.751305723
               ],
               "type": "Point"
           },
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       0,
                       3
                   ]
               ],
               "search": "Россия, Москва",
               "suggest": "Москва, Россия"
           },
           "type": "Feature"
       },
       ...
       {
           "bbox": [
               37.5589111,
               55.7866784,
               37.566417,
               55.7897745
           ],
           "geometry": {
               "coordinates": [
                   37.56260351010832,
                   55.78806346844892
               ],
               "type": "Point"
           },
           "properties": {
               "dataType": "address",
               "hl": [
                   [
                       0,
                       3
                   ],
                   [
                       18,
                       21
                   ]
               ],
               "search": "Россия, Москва, Московская аллея",
               "suggest": "Московская аллея, Москва, Россия"
           },
           "type": "Feature"
       }
   ],
   "query": "мос",
   "type": "FeatureCollection"
       }

Вариант применения подсветки

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

  var hilitedSuggest=rez.items[i].suggest;
  for (j = rez.items[i].hl.length-1; j >=0 ; j--)
  {
   hilitedSuggest=hilitedSuggest.insert(rez.items[i].hl[j][1],'</b>');
   hilitedSuggest=hilitedSuggest.insert(rez.items[i].hl[j][0],'<b>');
}

Обработка ошибок

Сервис возвращает ошибки в следующем формате:

{
   "code": код_ошибки,
       "message": "текст_ошибки",
       "verboseMessage": "подробный_текст_ошибки"
       }

Перечень возможных кодов ошибок и их описание

Перечень возможных кодов ошибок и их описание приведены в таблице ниже.

Перечень возможных кодов ошибок и их описание

Код ошибки

Текст ошибки

HTTP код ответа

Описание

1

Resource not found

404

Ресурс не найден (неправильный путь в запросе)

2

Resource not initialized

500

Ресурс не инициализирован (правильный запрос, но не загрузились данные)

3

Layer not found

400

Слой не найден (слой в запросе указан неправильно)

4

Layer not initialized

500

Слой не инициализирован (правильный запрос, но не загрузились данные слоя)

5

No license was found

401

Включена проверка лицензии, но не передан ключ

6

License error

403

С переданным ключом нельзя выполнить указанную операцию

7

Bad parameter value

400

Неправильное или неправильно сформированное значение параметра в запросе

8

Service error

500

Общая ошибка сервиса (используется, когда невозможно определить ошибку точнее)