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

Геокодер — это сервис, который обеспечивает прямое и обратное геокодирование.

Прямое геокодирование — это процесс преобразования адресов в географические координаты (широта и долгота), которые можно использовать для размещения маркеров на карте или для размещения карты на экране.

Обратное геокодирование — это процесс преобразования географических координат (широта и долгота) в адрес или часть адреса (страна, город, регион и т.д.).

Все сервисы геокодирования работают по территории всего мира на всех доступных языках.

/search — единая точка вызова сервисов прямого и обратного геокодирования адресных объектов.

Запрос

Обязательные параметры запроса

Имя поля

Формат

Описание

Пример

api_key

hex-string

Доступ к сервисам

api_key=fa749bace6d8a3b1....

string

Тело поискового запроса.

Для обратного геокодирования — координаты в формате lat,lon, где:

lat — широта искомой точки в градусах (используется 6 знаков после запятой);
lon — долгота искомой точки в градусах (используется 6 знаков после запятой).

Для прямого геокодирования — текстовая строка.

q=Москва Ленинградский 39с80

q=Мюнхен

q=Austria

q=55.7967432,37.5373542

Общие дополнительные параметры запроса

Имя поля

Формат

Описание

Пример

lang

2-х символьный код языка

Язык ответа на одном из доступных языков.

По умолчанию на языке региона, в котором найден объект.

lang=en

limit

unsigned integer

Ограничение числа объектов в ответе. поддерживаются значения в интервале от 1 до 100.

По умолчанию: 5

limit=10

fields

fieldname1,fieldname2,....fieldnameN

Выбор полей, отображаемых в ответе.

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

address_details (по умолчанию) — детальная информация о найденном адресе с почтовым индексом без координат;
address — полный найденный адрес одной строкой;
pin (по умолчанию) — координаты найденного объекта (долгота и широта);
bbox — область местонахождения объекта;
geometry — границы объекта;
type — тип объекта.

fields=geometry,address_details

admin_level

admin level

Ограничение ответа по административному уровню.

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

1 — страна;
2 — регион;
3 — населённый пункт;
4 — улица;
5 — дом.

По умолчанию ограничение не задано — поиск осуществляется по всем административным уровням.

admim_level=2

Дополнительные параметры запроса для прямого геокодирования

Имя поля

Формат

Описание

Пример

location

string

Координата, относительно которой будет осуществляться поиск и ранжирование результатов ответа.

Координаты в формате lat, lon, где:

lat — широта искомой точки в градусах. Используется 6 знаков после запятой;
lon — долгота искомой точки в градусах. Используется 6 знаков после запятой.

Результаты поиска будут отсортированы по расстоянию от указанной координаты

location=55.7967432,37.5373542

isocode

2char

Двухбуквенный код страны согласно ISO 3166-1 alpha-2

isocode=RU

Дополнительные параметры запроса для обратного геокодирования

Имя поля

Формат

Описание

Пример

radius

integer

Радиус поиска в метрах относительно координат, указанных в запросе в параметре q

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

radius=300

Ответ

Ответ предоставляется только в JSON формате. Используется JSON формат, разработанный специально для сервиса Геокодер v.3 и содержит информацию найденную по запросу.

JSON формат

Имя поля

Формат

Описание

Пример

request

string

Запрос

"request": "/v3/search?api_key=demo_demo_main&limit=1&q=55.796668,37.538871&fields=address_details,address,pin,bbox,geometry,type",

results

list

Найденный результат

"results": [
    {
      "address": "Россия, Москва, Северный административный округ, Москва, Хорошёвский, Ленинградский проспект, 39 с14",
      "address_details": {
        "building": "39 с14",
        "country": "Россия",
        "postal_code": "125167",
        "isocode": "RU",
        "locality": "Москва",
        "region": "Москва",
        "street": "Ленинградский проспект",
        "subregion": "Северный административный округ",
        "suburb": "Хорошёвский"
      },
      "bbox": [
        37.538253,
        55.796405,
        37.539368,
        55.79694
      ],
      "geometry": {
        "coordinates": [
          [
            [
              37.538253,
              55.796822
            ],
            [
              37.539204,
              55.796405
            ],
            [
              37.539368,
              55.796523
            ],
            [
              37.539105,
              55.796639
            ],
            [
              37.539082,
              55.796674
            ],
            [
              37.539052,
              55.796705
            ],
            [
              37.53901,
              55.796737
            ],
            [
              37.538958,
              55.796763
            ],
            [
              37.538899,
              55.796784
            ],
            [
              37.538835,
              55.796801
            ],
            [
              37.538772,
              55.796808
            ],
            [
              37.538714,
              55.79681
            ],
            [
              37.538416,
              55.79694
            ],
            [
              37.538253,
              55.796822
            ]
          ]
        ],
        "type": "Polygon"
      },
      "pin": [
        37.538851,
        55.796731
      ],
      "type": "building"
    }
  ]

address

string

Полный найденный адрес

"address": "Россия, Москва, Северный административный округ, Москва, Хорошёвский, Ленинградский проспект, 39 с14",

address_details

list

Детальная информация о найденном адресе

"address_details": {
        "building": "39 с80",
        "country": "Россия",
        "isocode": "RU",
        "locality": "Москва",
        "postal_code": "125167",
        "region": "Москва",
        "street": "Ленинградский проспект",
        "subregion": "Северный административный округ",
        "suburb": "Хорошёвский"
}

list

Координаты найденного объекта (долгота и широта)

"pin": [
        37.538851,
        55.796731
]

bbox

list

Границы местонахождения найденного объекта для позиционирования на карте

geometry

list

Геометрия найденного объекта

"geometry": {
        "coordinates": [
          [
            [
              37.538253,
              55.796822
            ],
            [
              37.539204,
              55.796405
            ],
            [
              37.539368,
              55.796523
            ],
            [
              37.539105,
              55.796639
            ],
            [
              37.539082,
              55.796674
            ],
            [
              37.539052,
              55.796705
            ],
            [
              37.53901,
              55.796737
            ],
            [
              37.538958,
              55.796763
            ],
            [
              37.538899,
              55.796784
            ],
            [
              37.538835,
              55.796801
            ],
            [
              37.538772,
              55.796808
            ],
            [
              37.538714,
              55.79681
            ],
            [
              37.538416,
              55.79694
            ],
            [
              37.538253,
              55.796822
            ]
          ]
        ],
        "type": "Polygon"
     }

type

string

Тип объекта

"type": "building"

Описание полей address_details

Имя поля

Формат

Описание

Пример

country

string

Страна

"country": "Россия"

isocode

2char

Двухбуквенный код страны согласно ISO 3166-1 alpha-2

"isocode": "RU"

region

string

Область

"region": "Москва"

subregion

string

Район

"subregion": "Северный административный округй"

locality

string

Населённый пункт

"locality": "Москва"

sublocality

string

Микрорайон или название жилого комплекса

"sublocality": "Аэропорт"

street

string

Улица

"street": "Проспект Ленинградский"

building

string

Номер дома, части дома или строения

"building": "39 с80"

suburb

string

Район/микрорайон населённого пункта

"suburb": "Хорошёвский"

postal_code

string

Почтовый код

"postal_code": "125167"

Описание полей geometry

Имя поля

Формат

Описание

Пример

type

string

Тип геометрии:

Point — точка;
MultiPoint — несколько точек;
LineString — линия;
MultiLineString — несколько линий;
Polygon — полигон;
MultiPolygon — несколько полигонов.

"type": "Polygon"

coordinates

list

Массив точек (долгота и широта), описывающий геометрию объекта

"coordinates":  [
    [100.0, 0.0], [101.0, 0.0],
    [101.0, 1.0], [100.0, 1.0],
    [100.0, 0.0]
]

Если по запросу ничего не найдено, ответ будет выглядеть следующим образом:

{
    "results": [],
    "request": "/v3/search?limit=1&q=Ленингрвавамский вца"
}

Пример

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

Запрос

https://geo.rustore.ru/api/search?api_key=<YOUR_API_KEY>q=Москва%20Ленинградский%2039%20с14&fields=address_details,address,pin,bbox,geometry,type&limit=1

Ответ

{
  "request": "/search?api_key=demo_demo_main&limit=1&q=Москва Ленинградский 39 с14&fields=address_details,address,pin,bbox,geometry,type",
  "results": [
    {
      "address": "Россия, Москва, Северный административный округ, Москва, Хорошёвский, Ленинградский проспект, 39 с14",
      "address_details": {
        "building": "39 с14",
        "country": "Россия",
        "postal_code": "125167",
        "isocode": "RU",
        "locality": "Москва",
        "region": "Москва",
        "street": "Ленинградский проспект",
        "subregion": "Северный административный округ",
        "suburb": "Хорошёвский"
      },
      "bbox": [
        37.538253,
        55.796405,
        37.539368,
        55.79694
      ],
      "geometry": {
        "coordinates": [
          [
            [
              37.538253,
              55.796822
            ],
            [
              37.539204,
              55.796405
            ],
            [
              37.539368,
              55.796523
            ],
            [
              37.539105,
              55.796639
            ],
            [
              37.539082,
              55.796674
            ],
            [
              37.539052,
              55.796705
            ],
            [
              37.53901,
              55.796737
            ],
            [
              37.538958,
              55.796763
            ],
            [
              37.538899,
              55.796784
            ],
            [
              37.538835,
              55.796801
            ],
            [
              37.538772,
              55.796808
            ],
            [
              37.538714,
              55.79681
            ],
            [
              37.538416,
              55.79694
            ],
            [
              37.538253,
              55.796822
            ]
          ]
        ],
        "type": "Polygon"
      },
      "pin": [
        37.538851,
        55.796731
      ],
      "type": "building"
    }
  ]
}

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

Запрос

https://geo.rustore.ru/api/search?api_key=<YOUR_API_KEY>q=55.796668,37.538871&fields=address_details,address,pin,bbox,geometry,type&limit=1

Ответ

{
  "request": "/v3/search?api_key=demo_demo_main&limit=1&q=55.796668,37.538871&fields=address_details,address,pin,bbox,geometry,type",
  "results": [
    {
      "address": "Россия, Москва, Северный административный округ, Москва, Хорошёвский, Ленинградский проспект, 39 с14",
      "address_details": {
        "building": "39 с14",
        "country": "Россия",
 
        "isocode": "RU",
        "locality": "Москва",
        "region": "Москва",
        "street": "Ленинградский проспект",
        "subregion": "Северный административный округ",
        "suburb": "Хорошёвский"
      },
      "bbox": [
        37.538253,
        55.796405,
        37.539368,
        55.79694
      ],
      "geometry": {
        "coordinates": [
          [
            [
              37.538253,
              55.796822
            ],
            [
              37.539204,
              55.796405
            ],
            [
              37.539368,
              55.796523
            ],
            [
              37.539105,
              55.796639
            ],
            [
              37.539082,
              55.796674
            ],
            [
              37.539052,
              55.796705
            ],
            [
              37.53901,
              55.796737
            ],
            [
              37.538958,
              55.796763
            ],
            [
              37.538899,
              55.796784
            ],
            [
              37.538835,
              55.796801
            ],
            [
              37.538772,
              55.796808
            ],
            [
              37.538714,
              55.79681
            ],
            [
              37.538416,
              55.79694
            ],
            [
              37.538253,
              55.796822
            ]
          ]
        ],
        "type": "Polygon"
      },
      "pin": [
        37.538851,
        55.796731
      ],
      "type": "building"
    }
  ]
}

Обновлено 22 декабря 2022 г.