# Быстрый старт

Создайте ключ и выполните первый запрос к API Ммаппс.

## Выберите способ подключения

Если нужна только карта, начните с [примера без ключа](https://mmapps.ru/docs/maps). Следующие шаги нужны для поиска адресов, маршрута и матрицы.

## Попробуйте API бесплатно

После регистрации и подтверждения email Вы можете выпустить личный API-ключ и выполнять запросы в пределах [бесплатной месячной квоты](https://mmapps.ru/docs/billing). Пополнять баланс и привязывать банковскую карту для этого не нужно.

Проверьте поиск на адресах, с которыми работает Ваш бизнес. Когда квота закончится, новые платные запросы потребуют средств на балансе и доступного бюджета. Регистрация для бесплатной карты по-прежнему не нужна.

## Создайте проект и ключ

1. [Зарегистрируйтесь](https://mmapps.ru/app/register), подтвердите email и откройте [«Проекты и ключи»](https://mmapps.ru/app/projects).
2. Используйте основной проект или создайте отдельный для своего приложения.
3. Нажмите «Создать ключ», выберите «На сервере» и разрешите подсказки адресов (`search`).
4. Скопируйте ключ: полностью он показывается один раз. Сохраните его в приватных настройках сервера.

Для JavaScript в браузере создайте отдельный ключ «На сайте» и укажите разрешённый сайт. Серверный ключ в браузер не передавайте. [Подробнее о правах и хранении](https://mmapps.ru/docs/keys).

## Выполните запрос

Базовый адрес API — `https://mmapps.ru`. Переменная окружения `MMAPPS_SERVER_KEY` в примере должна содержать Ваш серверный ключ. `YOUR_SERVER_KEY` — условное обозначение, а не действующий ключ.

```bash
curl --request POST 'https://mmapps.ru/v1/search' \
  --header "Authorization: Bearer ${MMAPPS_SERVER_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: 4c9cc4ef-b924-40df-8f61-c36a865b2d7e' \
  --data '{"q":"Примерная улица","limit":5}'
```

Замените «Примерная улица» на нужный Вам адрес. Для каждого нового запроса создавайте новый `Idempotency-Key`. Если повторяете тот же запрос, сохраните прежний ключ и тело.

## Обработайте ответ

Читайте `outcome` и список `candidates`. Отобразите `candidate.label` и предложите пользователю выбрать подходящий адрес. `candidate.point` может быть `null`: такой вариант нельзя использовать как координату. `ref` сохраняйте целиком, включая `id` и `dataset_version`.

HTTP 200 может означать, что вариантов нет или нужно уточнить запрос. Форматы и значения результатов описаны в [разделе поиска](https://mmapps.ru/docs/addresses).

## Проверьте расход

Откройте [«Использование»](https://mmapps.ru/app/usage), затем задайте бюджет в [«Лимиты и уведомления»](https://mmapps.ru/app/limits). Бесплатная квота общая для проектов аккаунта.



Для диагностики сохраняйте код ошибки и `X-Request-Id`. Не записывайте API-ключи, адреса пользователей и координаты в журналы ошибок и аналитику.