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

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

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

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

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

/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

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

Имя поля
Формат
Описание
Пример
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": "Хорошёвский"
}
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]
]

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

{
    "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 г.
Was this information helpful?