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

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

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

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

Запрос

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

Имя поля Формат Описание Пример

Имя поля	Формат	Описание	Пример
`api_key`	hex-string	Доступ к сервисам.	`api_key=fa749bace6d8a3b1....`
`q`	string	Тело поискового запроса. Для обратного геокодирования — координаты в формате `lat`, `lon`, где: • `lat`— широта искомой точки в градусах (используется 6 знаков после запятой); • `lon`— долгота искомой точки в градусах (используется 6 знаков после запятой). Для прямого геокодирования — текстовая строка.	`q=Москва Ленинградский 39с80` `q=Мюнхен` `q=Austria` `q=55.7967432,37.5373542`

api_key

hex-string

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

api_key=fa749bace6d8a3b1....

q

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`

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": "Хорошёвский" }`
`pin`	list	Координаты найденного объекта (долгота и широта)	`"pin": [ 37.538851, 55.796731 ]`
`bbox`	list	Границы местонахождения найденного объекта для позиционирования на карте	`"bbox": [ 37.538253, 55.796405, 37.539368, 55.79694 ]`
`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] ]`

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=Ленингрвавамский вца"
}

Пример

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

Запрос

Ответ

{
  "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"
    }
  ]
}

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

Запрос​

Ответ​

Пример​

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

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

Запрос

Ответ

Пример

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

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