---
metadata:
  - name: generator
    content: Diplodoc Platform v5.70.0
vcsPath: motorway/magacg/support/docs/src/ru-x-ai/methods/geo.geocoder.v2.md
alternate:
  - href: https://yamagistrali.ru/docs/ru-x-ai/methods/geo.geocoder.v2.md
    type: text/markdown
    title: Markdown version
  - href: https://yamagistrali.ru/docs/ru-x-ai/llms.txt
    rel: describedby
---
<div class="openapi">

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

<!-- markdownlint-disable-file -->

[Порядок работы для агента](https://yamagistrali.ru/docs/ru-x-ai/concepts/agent-workflow.md) · [Методы API и схема OpenAPI](https://yamagistrali.ru/docs/ru-x-ai/methods/index.md).

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

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

> **Метод:** `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` — необязательный код страны. Вариант может содержать подходящие координаты и без него.

| Значение `accuracy` | Как использовать |
|---|---|
| `exact` | Самая точная категория. Проверьте, что подпись соответствует месту пользователя. |
| `near` | Координаты приблизительные. Уточните место, если погрешность влияет на результат поиска. |
| `substituted` | Геокодер сопоставил введённую подпись с приблизительными координатами. Для поиска в узком радиусе получите подтверждение. |
| `low` | Привязка грубая или неуверенная. Уточните место или согласуйте больший радиус. |

Пустой массив означает, что геокодер не вернул подходящего варианта. Уточните `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` может содержать домашний адрес, место работы или адрес склада.

| Поле | Класс данных | Субъект | По умолчанию | Ограничения |
|---|---|---|---|---|
| `request.data.requestText` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |

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

| Поле | Класс данных | Субъект | По умолчанию | Ограничения |
|---|---|---|---|---|
| `response.data.foundAddresses[].address` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].area` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].display_address` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].house` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].lat` | Точное местоположение | Смешанный или неизвестный | Показывать агрегированно | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].locality` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].lon` | Точное местоположение | Смешанный или неизвестный | Показывать агрегированно | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].postalCode` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].province` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |
| `response.data.foundAddresses[].street` | Чувствительный адрес | Смешанный или неизвестный | Маскировать | Пользователю: только при явной подтверждённой необходимости; в AI-контекст: только при явной подтверждённой необходимости; во внешние системы: только при явной подтверждённой необходимости; в журналы, трассировки и метрики: не передавать исходное значение; примеры: только синтетические значения |

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

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

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

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

**Запрос**

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

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

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

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

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

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

**Запрос**

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

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

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

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

## Request

<div class="openapi__requests">

<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-post);margin-bottom: 12px">

<div class="openapi__request">

POST {.openapi__method}
```text translate=no
https://partner-test-yamagistrali.ru/api/geocoder/v2
```

</div>

Тестовый стенд

</div>

</div>

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "data": {
    "requestText": "example"
  }
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_data_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [GeocoderV2Request](https://yamagistrali.ru/docs/ru-x-ai/methods/geo.geocoder.v2.md#entity-GeocoderV2Request)

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "requestText": "example"
}
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

</div>

<div class="openapi-entity">

### GeocoderV2Request {#entity-GeocoderV2Request}

#|
|| **Name** | **Description** ||
||

_requestText_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

текст запроса

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "requestText": "example"
}
```

{% endcut %}

</div>

## Responses

<div class="openapi__response__code__200">

## 200 OK

OK

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "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"
      }
    ]
  }
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_data_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [GeocoderV2Response](https://yamagistrali.ru/docs/ru-x-ai/methods/geo.geocoder.v2.md#entity-GeocoderV2Response)

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "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"
    }
  ]
}
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

</div>

<div class="openapi-entity">

### GeocoderV2FoundAddress {#entity-GeocoderV2FoundAddress}

#|
|| **Name** | **Description** ||
||

_accuracy_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

уровень точности

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_address_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

адрес, например `Калужское шоссе, 22-й километр, 10`

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_display_address_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

адрес для основного отображения, например `Фудсити`, или `Москва, ул. Медиков, д 18`

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_lat_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: number

широта
{.table-cell}
||
||

_lon_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: number

долгота
{.table-cell}
||
||

_area_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string &#124; null

район

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_countryCode_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string &#124; null

код страны

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_house_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string &#124; null

дом

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_locality_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string &#124; null

город

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_postalCode_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string &#124; null

почтовый индекс

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_province_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string &#124; null

провинция

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_street_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string &#124; null

улица

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "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"
}
```

{% endcut %}

</div>

<div class="openapi-entity">

### GeocoderV2Response {#entity-GeocoderV2Response}

#|
|| **Name** | **Description** ||
||

_foundAddresses_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [GeocoderV2FoundAddress](https://yamagistrali.ru/docs/ru-x-ai/methods/geo.geocoder.v2.md#entity-GeocoderV2FoundAddress)[] &#124; null

найденные адреса

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  {
    "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"
  }
]
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "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"
    }
  ]
}
```

{% endcut %}

</div>

</div>

<div class="openapi__response__code__400">

## 400 Bad Request

Bad Request

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "error": {
    "info": {},
    "message": "example",
    "message_code": "example"
  }
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_error_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [Error](https://yamagistrali.ru/docs/ru-x-ai/methods/geo.geocoder.v2.md#entity-Error)

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "info": {},
  "message": "example",
  "message_code": "example"
}
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

</div>

<div class="openapi-entity">

### Error {#entity-Error}

#|
|| **Name** | **Description** ||
||

_info_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: object

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{}
```

{% endcut %}
{.table-cell}
||
||

_message_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_message_code_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "info": {},
  "message": "example",
  "message_code": "example"
}
```

{% endcut %}

</div>

</div>

<div class="openapi__response__code__403">

## 403 Forbidden

Forbidden

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "error": {
    "info": {},
    "message": "example",
    "message_code": "example"
  }
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_error_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [Error](https://yamagistrali.ru/docs/ru-x-ai/methods/geo.geocoder.v2.md#entity-Error)

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "info": {},
  "message": "example",
  "message_code": "example"
}
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

</div>

</div>

<div class="openapi__response__code__500">

## 500 Internal Server Error

Internal Server Error

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "error": {
    "info": {},
    "message": "example",
    "message_code": "example"
  }
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_error_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [Error](https://yamagistrali.ru/docs/ru-x-ai/methods/geo.geocoder.v2.md#entity-Error)

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "info": {},
  "message": "example",
  "message_code": "example"
}
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

</div>

</div>

</div>

[*Deprecated]: No longer supported, please use an alternative and newer version.