Руководство пользователя#

Сервис геокодирования позволяет определять координаты и получать сведения об объекте на карте по его адресу (прямое геокодирование) и наоборот, определять адрес объекта на карте по его координатам (обратное геокодирование).

Если в запросе указать адрес объекта, то сервис геокодирования возвратит его географические координаты. И наоборот, если в запросе указать географические координаты объекта, то сервис геокодирования возвратит его адрес.

Сервис геокодирования реализован в виде REST-службы. Запросы осуществляются методом HTTP GET, все необходимые параметры передаются в строке запроса. Ответы сервиса формируются в виде JSON-текста.

Настройки сервиса геокодирования#

Сервис настраивается с помощью конфигурационного файла appsettings.json, имеющего такую структуру:

{
  "SolR": {
    "BaseUri": "http://server:8984/solr/"
  },
  "Search": {
    "SearchDistanceSuggest": 5000,
    "SearchDistanceGeocode": 0,
    "MinScoreGeocodingDirect": 6.0,
    "MinScoreGeocodingSuggest": 0.1,
    "ResultLimit": 500
  },
  "Indexing": {
    "Schedule": "next 1w"
  },
  "Modules": {
    "Path": "SearchModules"
  }
}

BaseUri – адрес работающего сервера SolR, имеющего в составе необходимые виды поиска. Следует заметить, что порт, указанный в примере, может отличаться от действующего на сервере.
SearchDistanceSuggest – радиус для поиска похожих адресов, м.
SearchDistanceGeocode – радиус для поиска при обратном геокодировании, м.
MinScoreGeocodingDirect – порог релевантности результатов поиска для прямого геокодирования.
MinScoreGeocodingSuggest – порог релевантности результатов поиска для запроса подсказок.
ResultLimit – максимальное число записей в результатах запроса.
Schedule – описание правила периодического запуска индексирования.
Path – путь к директории модулей поиска относительно директории запуска сервиса (не рекомендуется изменять).

Настройка модулей поиска#

Каждый модуль поиска имеет типовые настройки, которые хранятся в файле modulesettings.json:

{
  "Module": {
    "Priority": 100,
    "Name": "Модуль геокодирования с использованием данных \"ДубльГИС\"",
    "SearchCoreName": "GeocoderDoubleGis",
    "EnableIndexing": true,
    "Csc": "WGS:84"
  }
}

Priority – значение приоритета модуля, целое число. В случае одновременной работы нескольких модулей используется для их упорядочивания. Модули с младшим приоритетом первые получают поступивший запрос на геокодирование.
Name – наименование модуля, служит для его идентификации в журнале сервиса.
SearchCoreName – название вида поиска, которое модуль использует для взаимодействия с SolR.
EnableIndexing – логический признак использования автоматического индексирования данных.
Csc – код системы координат, поддерживаемой указанным видом поиска.

Как правило, существующие настройки модуля менять не требуется. Изменения могут понадобиться если:

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

Как создать вид поиска#

Поиск объектов при геокодировании выполняется сервисом поиска Solr. Который, в свою очередь, использует т.н. «виды поиска». Для создания вида поиска, в первую очередь, необходимо выяснить директорию хранения данных SolR. Часть пути может отличаться, это зависит от параметров, с которыми производилась установка SolR:

Далее следует перейти в эту директорию на сервере, например, с помощью WinSCP. В ней нужно создать директорию для размещения вида поиска, например, «geocoder_iasaddressplan». В свойствах созданной директории следует установить права, как показано на рисунке:

В левой панели WinSCP нужно найти директорию описанием вида поиска из распакованного дистрибутива сервиса геокодирования. Описание будет располагаться по такому пути: <путь_к_распакованному_архиву>\GeocodingServiceExtraModules\<название_модуля>\bin\release\Configurator\8.7.0\SearchCoreSettings

Следует скопировать содержимое в созданную директорию на сервере:

Далее для вида поиска необходимо задать настройки соединения с базой данных. Для этого потребуется открыть файл «data-config.xml» и указать нужные реквизиты: <сервер_БД>:5432/<БД>, "<пользователь>", "<пароль>".

<?xml version="1.0" encoding="utf-8"?>
<dataConfig xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance” xmlns:xsd="http://www.w3.org/2001/XMLSchema”>
      <dataSource driver="org.postgresql.Driver”
                              url="jdbc:postgresql://<сервер_БД>:5432/<БД>
                              user="<пользователь>"
                              password="<пароль>"
                              autoCommit="false"
                              transactionIsolation="TRANSACTION_READ_COMMITTED”
                              holdability="CLOSE_CURSORS_AT_COMMIT"/>

Вид поиска настраивается для конкретного проекта. Для этого необходимо указать наименование схемы БД в файле data-config.xml в строке:

set search_path = ИМЯ_СХЕМЫ_ПРОЕКТА,public;

Следует обратить внимание, что описание вида поиска рассчитано на версию Solr 8.7.0. Если на сервере установлена другая версия поискового сервиса, либо он установлен в другой директории, потребуется внести изменения в файл описания вида поиска «solrconfig.xml» с указанием корректной версии и директории Solr:

<?xml version="1.0" encoding="utf-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema”>
        <luceneMatchVersion>8.7.0</luceneMatchVersion>
        <lib dir="/opt/solr-8.7.0/contrib/dateimporthandler/lib" regex=".*\.jar" />
        <lib dir="/opt/solr-8.7.0/dist" regex="solr-dataimporthandler-*.*\.jar" />
        <lib dir="/opt/solr-8.7.0/server/solr-webapp/webapp/WEB-INF/lib/" regex="spatial4-*.*\.jar" />
        <lib dir="/opt/solr-8.7.0/server/solr-webapp/webapp/WEB-INF/lib/" regex="jts-*.*\.jar" />
        <requestHandler name="/dataimport" clas="org.apache.solr.handler.dataimport.DataImportHandler" default="true">
                <lst name="defaults">
                        <str name="config">data-config.xml</str>
                </lst>
        </requestHandler>

Как настроить индексирование#

Периодичность индексирования задается настройкой «Schedule» в конфигурационном файле appsettings.json. Настройка может иметь значения:

«now 1d» – выполнить индексацию при запуске сервиса и затем повторять каждый день;
«next 2h» – выполнить через два часа после запуска и затем повторять каждые два часа.

Общее правило записи настройки:

<now|next> N<w|d|h|m|s>

Пояснения:

now – начать операцию сразу после запуска сервиса, затем повторять через указанный интервал;
next – начать операцию по истечении указанного времени, затем повторять через указанный интервал;
N – продолжительность интервала, положительное целое число. За ней следует единица измерения:
- w – неделя;
- d – день;
- h – час;
- m – минута;
- s – секунда.

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

Для запуска процесса нужно зайти в административный интерфейс SolR: http://localhost:8991/solr/#/GeocodingService/dataimport/

Диалог индексирования (импорта данных):

В выпадающем списке Entity необходимо выбрать значение «GeocoderSearchGeodetic» (1), затем нажать на кнопку Execute (2) и при необходимости контроля процесса, отметить опцию «Auto-Refresh Status» (3).

Далее в панели справа будет отображаться ход операции индексирования. По завершении панель сменит цвет на зелёной, в ней будут показаны результаты операции.

Ручной запуск индексирования#

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

Для запуска процесса нужно зайти в административный интерфейс SolR: http://адрес_solr:8984/solr/

Далее следует выбрать вид поиска, пункт «DataImport» (1).

В выпадающем списке Entity (2) выбрать единственное доступное значение, затем нажать на кнопку «Execute» (3) и при необходимости контроля процесса, отметить опцию «Auto–Refresh Status».

В панели справа будет отображаться ход операции индексирования. По завершении панель сменит цвет на зелёной, в ней будут показаны результаты операции.

Перезапуск SolR#

Для вступления настроек в силу потребуется перезапуск SolR. Это можно сделать следующей командой:

service solr_geocoder restart

Ожидается следующий вывод:

Если вывод отличается от приведённого, вероятно, служба SolR не сумела запуститься корректно. В этом случае веб-интерфейс SolR также не будет доступен. Одной из возможных причин такого поведения может быть недостаток оперативной памяти. Проверить текущее состояние по использованию памяти можно с помощью команды «htop». Для корректировки объёма памяти, доступной SolR, следует внести изменения в файл «/etc/default/solr_geocoder.in.sh»:

Как проверить доступность сервиса геокодирования#

Для проверки доступности сервиса необходимо в браузере или любым другим доступным способом (например, через команду «wget») получить доступ по адресу: http://адрес_сервиса:порт_сервиса/api/geocode/ping

В ответ должен прийти ответ «ok». Если такой ответ не получен, это может означать, что сервис недоступен для внешних клиентов и требуется предоставить такой доступ. Для ОС «Centos» это можно сделать командой:

firewall-cmd --zone=public --permanent --add-port=<порт_сервиса>/tcp && firewall-cmd --reload

В случае затруднений на этом шаге обратитесь к сетевому администратору.

Описание API сервиса геокодирования#

Все запросы к сервису геокодирования выполняются по протоколу HTTP c помощью метода GET.

Интерфейс сервиса имеет две версии:

Первая сохранена для совместимости с системами, уже использующими сервис геокодирования в своей работе.
Вторая – поддерживает более широкий спектр возможностей по фильтрации данных и имеет отдельный метод для запроса данных по коду ФИАС.

API версии 1#

Базовый адрес для доступа к API:

<адрес_сервиса>/api/geocode/<операция>[?парам=знач[&парам=знач]...]

Среди параметров могут быть следующие элементы:

«a» – адрес, строка произвольного вида.
«l» – описание координат точки, пара координат в виде «широта,долгота».
«r» – радиус поиска, метры.
«d» – признак детализации ответа, «true» или «false».

Прямое геокодирование#

Чтобы определить координаты объекта по его адресу, отправляется запрос:

<адрес_сервиса>/api/geocode/direct?a=Сахалинская ул., 69

В запросе передаётся подстрока или полный адрес (параметр «a»), в ответ возвращаются географические координаты объекта, либо null, если такой объект найти не удалось:

{
  "result": {
    "lat": 46.9634409757701,
    "lng": 142.725827792901
  }
}

Обратное геокодирование#

При обратном геокодировании в запросе указываются координаты искомого объекта. Запрос выглядит следующим образом:

<адрес_сервиса>/api/geocode/reverse?l=46.9634,142.7258

Для выполнения обратного геокодирования передаются координаты точки (параметр «l») и, при необходимости, радиус поиска адресного объекта (параметр «r») в метрах. Ответом на запрос выше будет:

{
  "result": "г. Южно-Сахалинск, Сахалинская ул., 69"
}

Также к любому запросу можно добавить параметр «d» со значением «true», что обернётся полным описанием адресов в ответе сервиса: название населённого пункта, улицы, номер дома, координаты центроида здания, а также описание полигона объекта в формате WKT.

Запрос с подсказкой#

Такой вариант использования сервиса позволяет получить подсказки по имеющемуся неполному адресу. Часть адреса (или его значение целиком) передаётся в виде параметра «a», также можно задать координаты точки (параметр «l»), относительно которой будет осуществляться поиск объектов с похожими адресами. Кроме того, вместе с параметром «l» может быть задан радиус поиска «r», который по умолчанию равен 5000 м.

Если в запросе задан параметр «l», то результаты запроса формируются в порядке увеличения расстояния от заданной точки до каждого из найденных объектов в пределах обозначенного радиуса:

<базовый_адрес>/api/geocode/suggest?a=ул Сахалинская&l=46.9634,142.7258 &r=200

Ответ на такой запрос выглядит следующим образом:

{
  "result": [
    "г. Южно-Сахалинск, Сахалинская ул., д. 52",
    "г. Южно-Сахалинск, Сахалинская ул., 69",
    "г. Южно-Сахалинск, Сахалинская ул., д. 68Б",
...

API версии 2#

Базовый адрес для доступа к API:

<адрес_сервиса>/api/v2/geocode/<операция>[?парам=знач[&парам=знач]...]

Перечень параметров запроса немного шире первой версии API:

«a» – адрес, строка произвольного вида.
«l» – описание координат точки, пара координат в виде «широта,долгота».
«r» – радиус поиска, метры.
«d» – признак детализации ответа, «true» или «false».
«f» – фильтр типов объектов, может принимать одно из двух значений:
- «Building» – для получения данных по зданиям.
- «Parcel» – для получения данных по земельным участкам.
«k» – ключ ФИАС для поиска в соответствующем запросе.

Следует обратить внимание на то, что результаты запросов, в отличие от API первой версии, отдаются в виде массива. Так, если по запросу не удалось обнаружить ни одного объекта, то будет возвращён пустой массив.

Прямое геокодирование#

Запрос:

<адрес_сервиса>/api/v2/geocode/direct?a=Сахалинская ул., 69

{
  "result": [
    {
      "lat": 46.9633675251068,
      "lng": 142.725769927575
    },
    {
      "lat": 46.9634409757701,
      "lng": 142.725827792901
    }
  ]
}

Результат запроса содержит два объекта, поскольку не был задан параметр фильтрации «f», а это означает, что по данному адресу обнаружено как здание, так и земельный участок.

Обратное геокодирование#

Запрос:

<адрес_сервиса>/api/v2/geocode/reverse?l=46.9634,142.7258&f=Building

Для выполнения обратного геокодирования передаются координаты точки (параметр «l») и, при необходимости, радиус поиска адресного объекта (параметр «r») в метрах. Также пример содержит фильтрацию по типу объекта. Ответом на запрос выше будет:

{
  "result": [
    "г. Южно-Сахалинск, Сахалинская ул., 69"
  ]
}

Обратите внимание, что на данный запрос пришёл один ответ. Это произошло, т.к. запрос содержит фильтр по типу объектов (здания).

Запрос подсказок#

<базовый_адрес>/api/v2/geocode/suggest?a=ул Сахалинская&l=46.9634,142.7258 &r=200

Ответ на такой запрос выглядит следующим образом:

{
  "result": [
    "г. Южно-Сахалинск, Сахалинская ул., 69",
    "г. Южно-Сахалинск, Сахалинская ул., 69",
    "г. Южно-Сахалинск, Крюкова Д.Н. ул., д. 64",
...

Поиск по коду ФИАС#

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

<базовый_адрес>/api/v2/geocode/fias?k=<код_ФИАС>

При наличии в системе данных о кодах ФИАС, будет возвращён ответ, аналогичный прямому геокодированию, т.е. координаты объекта. Впрочем, при добавлении параметра «d» со значением true ответ будет содержать полное описание найденного объекта.

Получение координат объекта по описанию кадастрового номера ЗУ или ОКС#

Пример запроса:

<адрес_сервиса>/api/v2/geocode/cadastralnumber/16:50:172021:2

Ответ на запрос со значениями широты и долготы:

{
  "result": [
     {
        "lat": 55.676201697453024,
        "lng": 49.13706307664968
     }
  ]
}

Где посмотреть данные о работе сервиса#

Детальная информация о событиях в работе сервиса, в том числе об ошибках (включая развернутый стек вызовов), выводится в файл журнала «geocoder.log», расположенный в папке сервиса геокодирования.