Расходы и лимиты

Тарифы

Квота общая для проектов аккаунта. Матрица учитывается по парам точек, остальные платные операции — по выполненным запросам. Применимый тариф и доступные операции проверяйте в кабинете.

Бесплатная проба API

Создайте аккаунт, подтвердите email и выпустите ключ в разделе «Проекты и ключи». Запросы в пределах бесплатной квоты доступны без пополнения баланса и привязки банковской карты. Первый запрос по шагам.

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

Хранение результатов

Результаты API можно сохранять у себя: в базе данных, кеше, заказах и отчётах. Используйте найденные адреса, координаты и рассчитанные маршруты повторно, в том числе на другой карте. Чтение сохранённого результата не вызывает новый запрос к Ммаппс и не расходует квоту.

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

Для поиска адресов и геокодирования атрибуцию OpenStreetMap можно разместить один раз в общем футере приложения, без подписи под каждым полем адреса. Правила размещения и пример.

Что считается операцией

• Поиск, геокодинг и обратный геокодинг учитываются при успешном выполнении, в том числе с пустым результатом или необходимостью уточнения.
• Расчёт маршрута — одна операция route.
• Матрица — N × M элементов, включая повторяющиеся пары, диагональ и завершённые no_route.
• В маршруте и матрице по адресам каждый выполненный поиск текста — отдельный geocode. До подтверждения адресов сам маршрут или матрица не оплачивается.
• resolve и status — без отдельной платы, в пределах частоты запросов ключа.
• Перемещение карты, маркеры, кластеры, отображение готовой геометрии и воспроизведение Ваших данных на таймлайне не расходуют квоту API.

Ошибка запроса или сервиса отличается от успешного ответа «ничего не найдено». У маршрута проверяйте outcome, у матрицы — статус каждой пары. При частичном выполнении поиска по адресам уже выполненные операции могут быть учтены; смотрите квитанцию и историю использования.

Баланс и месячный бюджет

После исчерпания бесплатной квоты нужны доступный баланс и разрешённый бюджет. Бюджет 0 оставляет только бесплатную квоту. Бюджеты аккаунта и проекта действуют одновременно. Создание другого проекта не увеличивает квоту.

Месяц учитывается по Москве. «Лимиты и уведомления» позволяют ограничить расходы, «Использование» — посмотреть историю, применить фильтры и выгрузить CSV. В статистике матрицы запросы и элементы указаны отдельно.

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

Для новой логической операции создавайте новый Idempotency-Key; в SDK это operationKey. При сетевом сбое повторяйте то же тело с прежним ключом. Не создавайте новый ключ при каждом автоматическом повторе.

Изменение тела при прежнем ключе возвращает 409. Сервис хранит ответ для повторной выдачи 15 минут; после этого повтор не запускает новую оплачиваемую операцию. Этот срок не ограничивает хранение полученного результата в Вашей базе по условиям соглашения. Если ответ для повтора истёк или операция ещё обрабатывается, сначала уточните её состояние.

Заголовок X-Usage-Operation содержит идентификатор операции. Квитанцию можно прочитать через GET /platform/v1/usage-operations/{id} тем же API-ключом с нужными правами. X-Charged-Microrub передаёт сумму целым числом в миллионных долях рубля; X-Geo-Funding — free, paid или mixed. Для обычной матрицы X-Geo-Quantity, X-Geo-Free-Units и X-Geo-Paid-Units показывают число элементов.

Ошибки

По умолчанию JSON ошибки содержит error.code, error.message, error.request_id, error.retryable. Для Accept: application/problem+json используется формат Problem Details из OpenAPI. Решение о повторе принимайте по коду и retryable, а не только по HTTP-статусу.

ROUTING_UNAVAILABLE означает недоступность расчёта. INCOMPATIBLE_GEO_SCHEMA — временную несовместимость сервиса; не пытайтесь обходить её запросом старого формата. При IDEMPOTENCY_SCHEMA_CHANGED прежняя операция уже учтена: новый ключ может создать новый расход.

Пополнения и возвраты

Пополняйте баланс через кабинет, минимум — 300 ₽. Возврат со страницы оплаты ещё не подтверждает зачисление — дождитесь подтверждённого статуса платежа. После регистрации чека в разделе «Платежи» появится кнопка «Скачать чек»: электронную копию можно открыть в браузере и распечатать или сохранить в PDF. Правила возвратов описаны в пользовательском соглашении.

Для обращения в поддержку достаточно кода ошибки и ID запроса. Не отправляйте ключи и географические данные пользователей.