Desarrolladores

Primero ejecuta una solicitud. Decide después.

El sandbox de abajo responde sin clave. Cuando quieras una, hace falta un correo y ninguna tarjeta: los límites gratuitos son los mismos que publica HERE.

Obtener una clave Leer la referencia

Inicio rápido

Tres pasos, unos cuarenta segundos.

01
Consigue una clave
Registro con un correo. La clave queda limitada a los servicios que marques y se puede rotar desde la consola en cualquier momento.
02
Envía una solicitud
Autenticación Bearer en una cabecera. Sin firmas, sin clave en la cadena de consulta y sin un host distinto por servicio.
03
Mira el contador
Cada respuesta lleva en una cabecera lo que queda del límite gratuito de ese servicio, así que el consumo nunca sorprende a fin de mes.

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

Cabeceras en cada respuesta

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

Sandbox

Cualquier endpoint, sin cuenta.

Las respuestas salen de un conjunto de fixtures con los formatos documentados y llevan x-apinavi-sandbox, para que nadie las confunda con datos en vivo.

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

RespuestaDatos de sandbox

Autenticación

Un token Bearer para diez servicios.

Las claves son tokens Bearer en la cabecera Authorization. Se pueden limitar por servicio, restringir por referente o IP y rotar con una ventana de solapamiento, para que un despliegue nunca compita con una rotación. No hay app id aparte ni firma de solicitudes.

Claves limitadas: solo los servicios que necesita cada aplicación
Rotación con 24 horas de solapamiento: la vieja y la nueva funcionan a la vez
Listas de referentes e IPs permitidos para claves de navegador
Las claves de servidor nunca aparecen en una URL

SDKs

Cinco lenguajes, generados desde la misma especificación.

Cada SDK se genera del documento OpenAPI 3.1, así que un parámetro nuevo llega a todos en la misma versión.

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

Errores

Errores que dicen qué hacer después.

Un único sobre de error en todos los servicios. El código es estable, el mensaje es para personas y la posibilidad de reintento es explícita en lugar de deducirse del estado.

Estado	Código	Significado	Reintento
400	invalidParameter	Un parámetro no ha pasado la validación; el campo se nombra en details[].	No
401	unauthenticated	Token Bearer ausente o mal formado.	No
403	serviceNotEnabled	La clave no cubre este servicio.	No
404	noResult	La consulta era válida y no encontró nada. No es un error: revisa items[].	No
429	rateLimited	Límite por segundo o tope de gasto que has fijado. Retry-After siempre está presente.	Sí, tras la cabecera
503	regionUnavailable	Una región está degradada; la respuesta indica una alternativa sana.	Sí, con espera creciente

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

Límites

Límites de tasa y qué pasa en su frontera.

Los límites son por clave y por servicio, y están publicados: no se descubren en producción.

Plan	Solicitudes/segundo	Pico	Notas
Free	10	20	Suficiente para desarrollo y una aplicación pequeña en producción.
Growth	500	1 000	Las claves de autocompletado tienen una cuota mayor por pulsación.
Scale	2 500	5 000	Se sube bajo petición sin cambiar el contrato.
Enterprise	Negociado	Negociado	Incluye opción de capacidad reservada.

Un tope de gasto es una parada dura, no un aviso: pasado ese punto la API devuelve 429 con el código spendCapReached y no se factura nada más.

Convenciones

Las garantías aburridas.

Versionado

La versión mayor va en la ruta. Los cambios rompedores estrenan mayor; los campos añadidos no. Los cambios menores se listan con fecha en el changelog.

Obsolescencia

Doce meses de aviso como mínimo, anunciados en el changelog y con una cabecera Sunset en los endpoints afectados.

Idempotencia

Los endpoints POST aceptan una cabecera Idempotency-Key y repiten la respuesta original durante 24 horas.

Paginación

Basada en cursor, con un campo next que es una URL completa. Sin deriva de desplazamiento en resultados grandes.

Agentes