Разработчикам

Сначала выполните запрос. Решайте потом.

Песочница ниже отвечает без ключа. Когда ключ понадобится, нужен будет адрес почты и не нужна карта — бесплатные лимиты те же, что публикует HERE.

Получить ключ Открыть справочник

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

Три шага, около сорока секунд.

01
Получите ключ
Регистрация по почте. Ключ ограничен теми сервисами, которые вы отметили, и в любой момент ротируется из консоли.
02
Отправьте запрос
Bearer-авторизация в заголовке. Без подписи, без ключа в query-строке и без отдельного хоста на каждый сервис.
03
Смотрите счётчик
В каждом ответе есть заголовок с остатком бесплатного лимита по этому сервису, поэтому потребление не удивит в конце месяца.

curl -sG "https://api.apinavi.com/v1/geocode" \
  -H "Authorization: Bearer $APINAVI_KEY" \
  -d "q=Torstraße 66, Berlin" \
  -d "in=countryCode:DEU"

Заголовки в каждом ответе

x-apinavi-quota-remaining: 29 641
x-apinavi-cost-usd: 0.00044
x-apinavi-request-id: req_01J9Z…

Песочница

Любой эндпоинт, без аккаунта.

Ответы приходят из набора фикстур в документированных форматах и помечены заголовком x-apinavi-sandbox, чтобы их нельзя было принять за живые данные.

curl -sG "https://api.apinavi.com/v1/geocode" \
  -H "Authorization: Bearer $APINAVI_KEY" \
  -d "q=Torstraße 66, Berlin" \
  -d "in=countryCode:DEU"

ОтветДанные песочницы

Авторизация

Один bearer-токен на десять сервисов.

Ключи — это bearer-токены в заголовке Authorization. Их можно ограничить по сервисам, по реферреру или IP и ротировать с окном перекрытия, чтобы деплой не гонялся с ротацией. Отдельного app id и подписи запросов нет.

Ограниченные ключи: доступ только к тем сервисам, которые нужны приложению
Ротация с перекрытием в 24 часа — старый и новый ключи работают одновременно
Списки разрешённых реферреров и IP для браузерных ключей
Серверные ключи никогда не попадают в URL

SDK

Пять языков, сгенерированных из одной спецификации.

Каждый SDK генерируется из документа OpenAPI 3.1, поэтому новый параметр доходит до всех них в одном релизе.

JavaScript / TypeScript

npm i @apinavi/sdk

Python

pip install apinavi

Go

go get github.com/apinavi/apinavi-go

Swift

https://github.com/apinavi/apinavi-swift

Kotlin / Android

implementation("com.apinavi:sdk:1.4.0")

Ошибки

Ошибки, которые говорят, что делать дальше.

Один конверт ошибки во всех сервисах. Код стабилен, сообщение написано для человека, а возможность повтора указана явно, а не выводится из статуса.

Статус	Код	Что значит	Повтор
400	invalidParameter	Параметр не прошёл валидацию; поле названо в details[].	Нет
401	unauthenticated	Bearer-токен отсутствует или некорректен.	Нет
403	serviceNotEnabled	Ключ не даёт доступа к этому сервису.	Нет
404	noResult	Запрос корректен и ничего не нашёл. Это не ошибка — смотрите items[].	Нет
429	rateLimited	Лимит в секунду или ваш потолок расходов. Retry-After присутствует всегда.	Да, после заголовка
503	regionUnavailable	Регион деградировал; в ответе назван работающий соседний.	Да, с бэкоффом

error envelope

{
  "error": {
    "code": "invalidParameter",
    "message": "in=countryCode expects ISO 3166-1 alpha-3",
    "requestId": "req_01J9ZC4T8M",
    "retryable": false,
    "details": [{ "field": "in", "got": "DE", "expected": "DEU" }]
  }
}

Лимиты

Лимиты и что происходит на их границе.

Лимиты действуют на ключ и на сервис и опубликованы — их не нужно выяснять на проде.

План	Запросов в секунду	Всплеск	Примечания
Free	10	20	Достаточно для разработки и небольшого продакшена.
Growth	500	1 000	У ключей автодополнения выше допуск на вызовы по нажатию.
Scale	2 500	5 000	Поднимается по запросу без изменения договора.
Enterprise	По договору	По договору	Есть опция зарезервированной мощности.

Потолок расходов — это жёсткая остановка, а не уведомление: за ним API возвращает 429 с кодом spendCapReached, и дальше ничего не тарифицируется.

Договорённости

Скучные гарантии.

Версионирование

Мажорная версия — в пути. Ломающие изменения получают новую мажорную, добавление полей — нет. Минорные изменения перечислены в чейнджлоге с датой.

Депрекация

Минимум двенадцать месяцев уведомления, объявление в чейнджлоге и заголовок Sunset на затронутых эндпоинтах.

Идемпотентность

POST-эндпоинты принимают заголовок Idempotency-Key и повторяют исходный ответ в течение 24 часов.

Пагинация

По курсору, с полем next в виде полного URL. Без сдвига смещений на больших выборках.

Агентам