Referencia API Huntly Desarrolladores
Integre precios de combustible en tiempo real, coordenadas GPS certificadas y metadatos de más de 80.000 estaciones con latencia mínima a través de Vercel Global Edge.
1. Visión General y Arquitectura
La API B2B de Huntly proporciona acceso programado y normalizado a precios y estaciones en 6 mercados de la UE (España, Francia, Alemania, Italia, Portugal, Reino Unido) y Quebec (Canadá).
2. Autenticación (X-Huntly-Key)
Todos los endpoints de datos requieren una clave API activa en la cabecera `X-Huntly-Key` o `Authorization: Bearer <API_KEY>`.
X-Huntly-Key: hnt_sbx_9a8b7c6d5e4f3a2b1c0d
Las claves Sandbox (`hnt_sbx_...`) incluyen 500 llamadas gratuitas al mes sin requerir tarjeta bancaria.
3. Inicio Rápido (Quickstart)
Realice su primera llamada API en menos de 60 segundos:
curl -X GET "https://www.gethuntly.eu/api/v1/fuel/nearby?lat=41.9028&lng=12.4964&radius_km=5&fuel_type=diesel" \ -H "X-Huntly-Key: YOUR_API_KEY"
Búsqueda geoespacial inmediata por radio alrededor de coordenadas GPS (PostGIS ST_DWithin).
| Parámetro | Tipo | Obligatorio | Por Defecto | Descripción |
|---|---|---|---|---|
| lat | float | Sì | — | Latitud en grados decimales (-90.0 a 90.0) |
| lng | float | Sì | — | Longitud en grados decimales (-180.0 a 180.0) |
| radius_km | float | No | 10 | Radio de búsqueda en kilómetros (mín 0.5, máx 50) |
| fuel_type | string | No | all | Filtro de combustible: `diesel`, `benzina`, `gpl`, `metano`. |
| limit | integer | No | 20 | Límite máximo de estaciones devueltas (mín 1, máx 100) |
{
"status": "success",
"meta": {
"query": {
"latitude": 41.9028,
"longitude": 12.4964,
"radius_km": 5,
"fuel_type": "diesel",
"limit": 20
},
"results_count": 1,
"tier": "sandbox",
"quota_remaining": 492,
"timestamp": "2026-10-10T12:00:00.000Z"
},
"data": [
{
"id": "shop_01j7h8k...",
"name": "Eni Station Roma Termini",
"brand": "Eni",
"address": "Via Giovanni Giolitti 40",
"city": "Roma",
"country": "IT",
"coordinates": {
"latitude": 41.8982,
"longitude": 12.5034
},
"distance_km": 0.78,
"fuel": {
"type": "diesel",
"price": 1.639,
"service_type": "self",
"last_updated": "2026-10-10T06:15:00.000Z"
}
}
]
}Filtrado por área administrativa (Ciudad o Código de País ISO-2).
| Parámetro | Tipo | Obligatorio | Por Defecto | Descripción |
|---|---|---|---|---|
| country | string | Opzionale* | — | Código ISO de 2 letras: `IT`, `FR`, `DE`, `ES`, `PT`, `UK`, `CA`. |
| city | string | Opzionale* | — | Nombre de la ciudad (ej. Madrid, Barcelona, Valencia, Roma). |
| fuel_type | string | No | all | Filtro de combustible: `diesel`, `benzina`, `gpl`, `metano`. |
| limit | integer | No | 50 | Numero di risultati (min 1, max 200) |
Endpoint público para verificar el estado del clúster Edge.
{
"status": "ok",
"service": "Huntly European Fuel & Retail B2B API",
"version": "v1.0.0",
"timestamp": "2026-10-10T12:00:00.000Z",
"coverage": {
"countries": ["IT", "FR", "ES", "DE", "PT", "NL", "BE", "CA-QC"],
"stations_monitored": "80,000+"
}
}7. Límites de Tasa y Cabeceras HTTP
Cada respuesta HTTP devuelve cabeceras diagnósticas para controlar el uso:
| Header HTTP | Tipo | Descrizione |
|---|---|---|
| X-RateLimit-Limit | integer | Límite mensual permitido por su plan contratado. |
| X-RateLimit-Remaining | integer | Llamadas restantes para el ciclo mensual actual. |
| X-RateLimit-Reset | ISO-8601 string | Fecha y hora ISO de reinicio de la cuota. |
| Cache-Control | string | Valori di caching Edge (`s-maxage=600`, `stale-while-revalidate`) per azzerare le latenze tra chiamate identiche. |
8. Códigos de Error HTTP
| Código | Significado | Escenario Típico |
|---|---|---|
| 200 | OK | Petición procesada con éxito. |
| 400 | Bad Request | Parámetros incorrectos o ausentes (ej. radio > 50km). |
| 401 | Unauthorized | Clave API inválida o revocada. |
| 429 | Too Many Requests | Cuota mensual agotada. |
| 500 | Internal Error | Error interno del servidor. |
¿Necesita asistencia técnica?
Nuestro equipo de ingeniería atiende proyectos enterprise y data lakes personalizados.
📧 Contactar en infos@gethuntly.eu