# Yandex Geocoder API key

Эта инструкция нужна для ручного подключения геокодера Яндекса к `iola-cli`.

Рекомендуемый путь для обычного пользователя - через [Yandex Cloud Connector](Yandex-Cloud-Connector):

```bash
iola yandex cloud setup
```

Геокодер нужен жителям для вопросов вида:

- что находится рядом с моим адресом;
- где находится школа или детский сад;
- какой объект ближе;
- открыть объект на карте;
- не перепутать Йошкар-Олу, Семеновку и другие населенные пункты.

## Получение ключа

1. Откройте Кабинет разработчика Яндекса: `https://developer.tech.yandex.ru/services/`.
2. Войдите в аккаунт Яндекса.
3. В списке `API интерфейсы` найдите `API Геокодера`.
4. Откройте `API Геокодера`.
5. Проверьте блок тарифа. На момент проверки 02.06.2026 в кабинете был показан тариф `Бесплатный с ограничениями` и счетчик `1000` запросов в сутки.
6. В блоке `Ключи API` нажмите `Новый ключ`.
7. В поле `Название ключа` введите понятное имя, например `iola-cli geocoder`.
8. Нажмите `Добавить ключ`.
9. После создания ключ появится в списке ключей API Геокодера.
10. Скопируйте значение ключа. Это значение будет `YANDEX_GEOCODER_API_KEY`.

Важно: новый ключ может начать работать не сразу. В документации Яндекса указано, что активация ключа может занять до 15 минут, на практике лучше спокойно подождать 15-30 минут. Если CLI пишет `Invalid api key` сразу после создания ключа, это не обязательно ошибка: подождите и повторите проверку командой `iola geo key doctor`.

## Сохранение в CLI

Запустите:

```bash
iola geo key set yandex
```

CLI попросит ввести:

```text
YANDEX_GEOCODER_API_KEY
```

Ключ сохраняется локально на устройстве пользователя в `~/.iola/secrets.json`.

Проверить сохранение:

```bash
iola geo key status
```

Проверить рабочий запрос к API:

```bash
iola geo key doctor
```

Проверить геокодирование адреса:

```bash
iola geo geocode "Йошкар-Ола, улица Петрова, 15"
```

CLI также понимает переменные окружения:

- `YANDEX_GEOCODER_API_KEY`;
- `YANDEX_MAPS_API_KEY`.

## Официальные ссылки

- Кабинет разработчика: `https://developer.tech.yandex.ru/services/`
- API Геокодера: `https://developer.tech.yandex.ru/services/2`
- Документация Geocoder API: `https://yandex.com/maps-api/docs/geocoder-api/`
- Формат запроса: `https://yandex.com/maps-api/docs/geocoder-api/request.html`
