Développeurs

Lancez d'abord une requête. Décidez ensuite.

Le bac à sable ci-dessous répond sans clé. Quand vous en voudrez une, il faudra une adresse e-mail et aucune carte — les quotas gratuits sont ceux que publie HERE.

Obtenir une clé Lire la référence

Démarrage rapide

Trois étapes, une quarantaine de secondes.

01
Obtenez une clé
Inscription par e-mail. La clé est limitée aux services cochés et se renouvelle depuis la console à tout moment.
02
Envoyez une requête
Authentification Bearer dans un en-tête. Pas de signature, pas de clé dans la chaîne de requête, pas d'hôte différent par service.
03
Lisez le compteur
Chaque réponse porte le quota gratuit restant pour ce service dans un en-tête : la consommation ne surprend jamais en fin de mois.

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

En-têtes présents dans chaque réponse

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

Bac à sable

N'importe quel point d'entrée, sans compte.

Les réponses viennent d'un jeu de fixtures aux formats documentés et portent x-apinavi-sandbox, pour que personne ne les prenne pour des données réelles.

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

RéponseDonnées du bac à sable

Authentification

Un jeton Bearer pour dix services.

Les clés sont des jetons Bearer envoyés dans l'en-tête Authorization. Elles peuvent être limitées par service, restreintes par référent ou par IP et renouvelées avec une fenêtre de chevauchement, pour qu'un déploiement n'entre jamais en course avec une rotation. Il n'y a ni app id distinct ni signature de requête.

Clés restreintes : uniquement les services dont une application a besoin
Rotation avec 24 heures de chevauchement : l'ancienne et la nouvelle fonctionnent ensemble
Listes d'autorisation par référent et par IP pour les clés navigateur
Les clés serveur n'apparaissent jamais dans une URL

SDK

Cinq langages, générés depuis la même spécification.

Chaque SDK est généré depuis le document OpenAPI 3.1 : un nouveau paramètre atteint tous les SDK dans la même version.

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

Erreurs

Des erreurs qui disent quoi faire ensuite.

Une seule enveloppe d'erreur pour tous les services. Le code est stable, le message s'adresse à un humain, et la possibilité de réessayer est explicite plutôt que déduite du statut.

Statut	Code	Signification	Réessai
400	invalidParameter	Un paramètre a échoué à la validation ; le champ est nommé dans details[].	Non
401	unauthenticated	Jeton Bearer absent ou mal formé.	Non
403	serviceNotEnabled	La clé ne couvre pas ce service.	Non
404	noResult	La requête était valide et n'a rien trouvé. Ce n'est pas une erreur : regardez items[].	Non
429	rateLimited	Limite par seconde ou plafond de dépense que vous avez fixé. Retry-After est toujours présent.	Oui, après l'en-tête
503	regionUnavailable	Une région est dégradée ; la réponse indique une alternative saine.	Oui, avec attente croissante

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

Limites

Limites de débit et ce qui se passe à leur bord.

Les limites s'appliquent par clé et par service, et elles sont publiées — on ne les découvre pas en production.

Formule	Requêtes/seconde	Pointe	Remarques
Free	10	20	Suffisant pour le développement et une petite application en production.
Growth	500	1 000	Les clés d'autocomplétion disposent d'un quota plus élevé par frappe.
Scale	2 500	5 000	Relevé sur demande sans changement de contrat.
Enterprise	Négocié	Négocié	Comprend une option de capacité réservée.

Un plafond de dépense est un arrêt net, pas une alerte : au-delà, l'API renvoie 429 avec le code spendCapReached et plus rien n'est facturé.

Conventions

Les garanties ennuyeuses.

Versionnage

La version majeure figure dans le chemin. Les ruptures passent en majeure, les champs ajoutés non. Les changements mineurs sont listés et datés dans le journal.

Obsolescence

Douze mois de préavis au minimum, annoncés dans le journal et signalés par un en-tête Sunset sur les points d'entrée concernés.

Idempotence

Les points d'entrée POST acceptent un en-tête Idempotency-Key et rejouent la réponse d'origine pendant 24 heures.

Pagination

Par curseur, avec un champ next qui est une URL complète. Pas de dérive d'offset sur les grands jeux de résultats.

Agents