Developers

Run a request first. Decide afterwards.

The sandbox below answers without a key. When you want one, it takes an email and no card — the free allowances are the same ones HERE publishes.

Get an API key Read the reference

Quickstart

Three steps, about forty seconds.

01
Get a key
Sign up with an email. The key is scoped to the services you tick and can be rotated from the console at any time.
02
Send a request
Bearer auth in a header. No signing, no query-string key, no per-service host to remember.
03
Read the meter
Every response carries the remaining free allowance for that service in a header, so usage never surprises you at month end.

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

Headers on every response

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

Sandbox

Every endpoint, no account.

Responses come from a fixture set with the documented shapes, marked with x-apinavi-sandbox so nothing can mistake them for live data.

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

ResponseSandbox data

Authentication

One bearer token, ten services.

Keys are bearer tokens sent in the Authorization header. They can be scoped per service, restricted by referrer or IP, and rotated with an overlap window so a deploy never races a rotation. There is no separate app id and no request signing.

Scoped keys: grant only the services an app needs
Rotation with a 24-hour overlap, so old and new both work during a deploy
Referrer and IP allowlists for browser keys
Server-side keys never appear in a URL

SDKs

Five languages, generated from the same spec.

Each SDK is generated from the OpenAPI 3.1 document, so a new parameter reaches all of them in the same release.

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")

Errors

Errors that say what to do next.

One error envelope across every service. The code is stable, the message is for humans, and retryability is explicit rather than implied by the status.

Status	Code	Meaning	Retry
400	invalidParameter	A parameter failed validation; the field is named in details[].	No
401	unauthenticated	Missing or malformed bearer token.	No
403	serviceNotEnabled	The key is not scoped to this service.	No
404	noResult	The query was valid and matched nothing. Not an error condition — check items[].	No
429	rateLimited	Per-second limit or a spend cap you set. Retry-After is always present.	Yes, after the header
503	regionUnavailable	A region is degraded; the response names a healthy alternative.	Yes, with backoff

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" }]
  }
}

Limits

Rate limits and what happens at the edge of them.

Limits are per key, per service, and published — not discovered in production.

Plan	Requests/second	Burst	Notes
Free	10	20	Enough for development and a small production app.
Growth	500	1 000	Autosuggest keys get a higher per-keystroke allowance.
Scale	2 500	5 000	Raised on request without a contract change.
Enterprise	Negotiated	Negotiated	Includes a reserved-capacity option.

A spend cap is a hard stop, not an alert: past it the API returns 429 with code spendCapReached and nothing further is billed.

Conventions

The boring guarantees.

Versioning

The path carries the major version. Breaking changes get a new major; additive fields do not. Minor changes are listed in the changelog with a date.

Deprecation

Twelve months of notice minimum, announced in the changelog and via a Sunset header on affected endpoints.

Idempotency

POST endpoints accept an Idempotency-Key header and replay the original response for 24 hours.

Pagination

Cursor-based, with a next field that is a complete URL. No offset drift on large result sets.

Agents