Entwickler

Erst die Anfrage. Entscheiden danach.

Die Sandbox unten antwortet ohne Schlüssel. Wenn Sie einen wollen, braucht es eine E-Mail-Adresse und keine Karte — die Freikontingente sind dieselben, die HERE veröffentlicht.

API-Schlüssel holen Referenz lesen

Schnellstart

Drei Schritte, rund vierzig Sekunden.

01
Schlüssel holen
Registrierung per E-Mail. Der Schlüssel gilt nur für die angehakten Dienste und lässt sich jederzeit in der Konsole rotieren.
02
Anfrage senden
Bearer-Auth im Header. Keine Signatur, kein Schlüssel im Query-String, kein eigener Host je Dienst.
03
Zähler ablesen
Jede Antwort trägt das verbleibende Freikontingent dieses Dienstes im Header, sodass die Nutzung zum Monatsende nicht überrascht.

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

Header in jeder Antwort

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

Sandbox

Jeder Endpunkt, ohne Konto.

Die Antworten stammen aus einem Fixture-Satz mit den dokumentierten Formaten und tragen x-apinavi-sandbox, damit sie niemand für Live-Daten hält.

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

AntwortSandbox-Daten

Authentifizierung

Ein Bearer-Token für zehn Dienste.

Schlüssel sind Bearer-Token im Authorization-Header. Sie lassen sich je Dienst einschränken, per Referrer oder IP beschränken und mit Überlappungsfenster rotieren, damit ein Deploy nie mit einer Rotation kollidiert. Es gibt keine separate App-ID und keine Anfragesignatur.

Eingeschränkte Schlüssel: nur die Dienste, die eine App braucht
Rotation mit 24 Stunden Überlappung — alt und neu funktionieren parallel
Referrer- und IP-Freigabelisten für Browser-Schlüssel
Serverseitige Schlüssel tauchen nie in einer URL auf

SDKs

Fünf Sprachen, aus derselben Spezifikation erzeugt.

Jedes SDK wird aus dem OpenAPI-3.1-Dokument generiert, sodass ein neuer Parameter alle im selben Release erreicht.

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

Fehler

Fehler, die sagen, was als Nächstes zu tun ist.

Ein Fehlerformat über alle Dienste. Der Code ist stabil, die Meldung ist für Menschen, und die Wiederholbarkeit steht explizit da statt implizit im Status.

Status	Code	Bedeutung	Wiederholen
400	invalidParameter	Ein Parameter ist an der Validierung gescheitert; das Feld steht in details[].	Nein
401	unauthenticated	Bearer-Token fehlt oder ist fehlerhaft.	Nein
403	serviceNotEnabled	Der Schlüssel gilt nicht für diesen Dienst.	Nein
404	noResult	Die Anfrage war gültig und hat nichts getroffen. Kein Fehlerzustand — prüfen Sie items[].	Nein
429	rateLimited	Sekundenlimit oder ein von Ihnen gesetztes Ausgabenlimit. Retry-After ist immer gesetzt.	Ja, nach dem Header
503	regionUnavailable	Eine Region ist beeinträchtigt; die Antwort nennt eine gesunde Alternative.	Ja, mit 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 und was an ihrer Grenze passiert.

Limits gelten je Schlüssel und je Dienst und sind veröffentlicht — man entdeckt sie nicht erst im Betrieb.

Plan	Anfragen/Sekunde	Burst	Hinweise
Free	10	20	Genug für Entwicklung und eine kleine produktive App.
Growth	500	1 000	Schlüssel für Vorschläge bekommen ein höheres Kontingent je Tastendruck.
Scale	2 500	5 000	Auf Anfrage ohne Vertragsänderung angehoben.
Enterprise	Verhandelt	Verhandelt	Inklusive Option auf reservierte Kapazität.

Ein Ausgabenlimit ist ein harter Stopp, keine Warnung: Danach gibt die API 429 mit dem Code spendCapReached zurück, und es wird nichts weiter berechnet.

Konventionen

Die langweiligen Zusagen.

Versionierung

Die Hauptversion steht im Pfad. Breaking Changes bekommen eine neue Hauptversion, zusätzliche Felder nicht. Kleinere Änderungen stehen mit Datum im Changelog.

Abkündigung

Mindestens zwölf Monate Vorlauf, angekündigt im Changelog und über einen Sunset-Header an den betroffenen Endpunkten.

Idempotenz

POST-Endpunkte akzeptieren einen Idempotency-Key-Header und wiederholen die ursprüngliche Antwort 24 Stunden lang.

Paginierung

Cursorbasiert, mit einem next-Feld als vollständiger URL. Kein Offset-Drift bei großen Ergebnismengen.

Agenten