Найти координаты по адресу

Порядок работы для агента · Методы API и схема OpenAPI.

НазначениеНазначение

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

Метод: POST /api/geocoder/v2

ДоступДоступ

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

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

Входные данныеВходные данные

В data.requestText передайте минимальное описание места, достаточное для поиска. Включайте город, регион, улицу и номер дома, если пользователь их указал или они нужны для уточнения. Исключите имена, телефоны, комментарии к заказу, идентификаторы организаций и сведения вне задачи.

• Для конкретного места передайте непустой текст.
• Пустая строка или строка из пробелов возвращает до 50 популярных вариантов. Используйте её по явной просьбе предложить места. Выбор города согласуйте с пользователем.
• Радиус задаётся в запросе поиска заказов. Если он влияет на результат и пользователь его не назвал, уточните радиус.

РезультатРезультат

data.foundAddresses содержит независимые варианты. Для поиска подходят конечные числа lat в диапазоне [-90, 90] и lon в диапазоне [-180, 180].

Показывайте display_address как подпись варианта. Она может содержать больше подробностей, чем address.

address содержит краткое представление адреса. В фильтр по радиусу передавайте координаты.

lat — широта, lon — долгота. Копируйте значения без преобразований. В фильтре поиска заказов поле долготы называется long.

Необязательные province, area, locality, street и house помогают уточнить вариант. Если компонент отсутствует, он недоступен или неприменим для этого результата. Координаты проверяйте отдельно.

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

countryCode — необязательный код страны. Вариант может содержать подходящие координаты и без него.

Пустой массив означает, что геокодер не вернул подходящего варианта. Уточните requestText или спросите пользователя о более общем месте. О наличии заказов судите после поиска.

Передать координаты в поиск заказовПередать координаты в поиск заказов

1. Вызовите POST /api/geocoder/v2 и выберите один подтверждённый вариант.
2. Для поиска заказчика используйте POST /api/orders/v0/transferOrder/getOrderIdsForCustomer, для исполнителя — POST /api/orders/v0/transferOrder/getOrderIdsForExecutor.
3. Если нужна любая точка погрузки груза, используйте data.filter.loadPoint. Для любой точки выгрузки используйте data.filter.unloadPoint. Если пользователь указал именно первую погрузку или последнюю выгрузку всего маршрута, используйте соответственно data.filter.orderWayFirstLoadingWayPoint или data.filter.orderWayLastUnloadingWayPoint. Если пользователь задал два условия, передайте оба в одном запросе.
4. Скопируйте lat в .lat, lon в .long. В .radiusM передайте согласованный радиус в метрах.
5. Передайте выбранные идентификаторы как data.exactOrderIds в POST /api/orders/v0/transferOrder/getFlatForCustomer для заказчика или POST /api/orders/v0/transferOrder/getFlatForExecutor для исполнителя. Описывайте заказ по полям ответа метода деталей.

Повтор запросаПовтор запроса

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

Работа с чувствительными даннымиРабота с чувствительными данными

requestText может содержать домашний адрес, место работы или адрес склада.

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

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

Проверенные примерыПроверенные примеры

Получить координаты синтетического адреса · синтетический пример

Адрес, координаты и все компоненты ответа полностью синтетические.

Запрос

{
  "data": {
    "requestText": "Example City, Test Street, 1"
  }
}

Сокращённый ответ

{
  "data": {
    "foundAddresses": [
      {
        "display_address": "Example Region, Example City, Test Street, 1",
        "address": "Test Street, 1",
        "lat": 55.0001,
        "lon": 37.0001,
        "province": "Example Region",
        "area": "Example District",
        "locality": "Example City",
        "street": "Test Street",
        "house": "1",
        "accuracy": "exact",
        "postalCode": "123456",
        "countryCode": "RU"
      }
    ]
  }
}

Подходящих вариантов нетПодходящих вариантов нет

Подходящий адрес не найден · синтетический пример

Успешный запрос без подходящей подсказки возвращает пустой список.

Запрос

{
  "data": {
    "requestText": "example-address-with-no-match"
  }
}

Сокращённый ответ

{
  "data": {
    "foundAddresses": []
  }
}

Блоки запроса и ответов ниже сгенерированы из OpenAPI. Подстановки вроде example показывают структуру JSON. Для вызова возьмите значения из сценария, справочников или предыдущих ответов API.

RequestRequest

https://partner-test-yamagistrali.ru/api/geocoder/v2

{
  "data": {
    "requestText": "example"
  }
}

{
  "requestText": "example"
}

{
  "requestText": "example"
}

ResponsesResponses

{
  "data": {
    "foundAddresses": [
      {
        "accuracy": "example",
        "address": "example",
        "area": "example",
        "countryCode": "example",
        "display_address": "example",
        "house": "example",
        "lat": 0.5,
        "locality": "example",
        "lon": 0.5,
        "postalCode": "example",
        "province": "example",
        "street": "example"
      }
    ]
  }
}

{
  "foundAddresses": [
    {
      "accuracy": "example",
      "address": "example",
      "area": "example",
      "countryCode": "example",
      "display_address": "example",
      "house": "example",
      "lat": 0.5,
      "locality": "example",
      "lon": 0.5,
      "postalCode": "example",
      "province": "example",
      "street": "example"
    }
  ]
}

{
  "accuracy": "example",
  "address": "example",
  "area": "example",
  "countryCode": "example",
  "display_address": "example",
  "house": "example",
  "lat": 0.5,
  "locality": "example",
  "lon": 0.5,
  "postalCode": "example",
  "province": "example",
  "street": "example"
}

[
  {
    "accuracy": "example",
    "address": "example",
    "area": "example",
    "countryCode": "example",
    "display_address": "example",
    "house": "example",
    "lat": 0.5,
    "locality": "example",
    "lon": 0.5,
    "postalCode": "example",
    "province": "example",
    "street": "example"
  }
]

{
  "foundAddresses": [
    {
      "accuracy": "example",
      "address": "example",
      "area": "example",
      "countryCode": "example",
      "display_address": "example",
      "house": "example",
      "lat": 0.5,
      "locality": "example",
      "lon": 0.5,
      "postalCode": "example",
      "province": "example",
      "street": "example"
    }
  ]
}

{
  "error": {
    "info": {},
    "message": "example",
    "message_code": "example"
  }
}

{
  "info": {},
  "message": "example",
  "message_code": "example"
}

{}

{
  "info": {},
  "message": "example",
  "message_code": "example"
}

{
  "error": {
    "info": {},
    "message": "example",
    "message_code": "example"
  }
}

{
  "info": {},
  "message": "example",
  "message_code": "example"
}

{
  "error": {
    "info": {},
    "message": "example",
    "message_code": "example"
  }
}

{
  "info": {},
  "message": "example",
  "message_code": "example"
}