⚡ REFERENCIA OFICIAL API PARA DESARROLLADORES V1

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á).

URL Base Global:
https://www.gethuntly.eu/api/v1
✨ Copertura Ufficiale: Italia, Francia, Germania, Spagna, Portogallo, Regno Unito e Quebec (Canada) con granularità per singola stazione e coordinate GPS geoverificate. I dati di Svizzera e Belgio sono forniti come medie nazionali collaborative.

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>`.

Cabecera HTTP Obligatoria:
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"
GET/api/v1/fuel/nearby

Búsqueda geoespacial inmediata por radio alrededor de coordenadas GPS (PostGIS ST_DWithin).

ParámetroTipoObligatorioPor DefectoDescripción
latfloatSì—Latitud en grados decimales (-90.0 a 90.0)
lngfloatSì—Longitud en grados decimales (-180.0 a 180.0)
radius_kmfloatNo10Radio de búsqueda en kilómetros (mín 0.5, máx 50)
fuel_typestringNoallFiltro de combustible: `diesel`, `benzina`, `gpl`, `metano`.
limitintegerNo20Límite máximo de estaciones devueltas (mín 1, máx 100)
Esempio Risposta JSON (200 OK):
200 OK — application/json
{
  "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"
      }
    }
  ]
}
GET/api/v1/fuel/stations

Filtrado por área administrativa (Ciudad o Código de País ISO-2).

ParámetroTipoObligatorioPor DefectoDescripción
countrystringOpzionale*—Código ISO de 2 letras: `IT`, `FR`, `DE`, `ES`, `PT`, `UK`, `CA`.
citystringOpzionale*—Nombre de la ciudad (ej. Madrid, Barcelona, Valencia, Roma).
fuel_typestringNoallFiltro de combustible: `diesel`, `benzina`, `gpl`, `metano`.
limitintegerNo50Numero di risultati (min 1, max 200)
⚠️ Nota Filtro: Es obligatorio especificar al menos `country` o `city`.
GET/api/v1/health

Endpoint público para verificar el estado del clúster Edge.

200 OK — Pubblico (Nessuna chiave richiesta)
{
  "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 HTTPTipoDescrizione
X-RateLimit-LimitintegerLímite mensual permitido por su plan contratado.
X-RateLimit-RemainingintegerLlamadas restantes para el ciclo mensual actual.
X-RateLimit-ResetISO-8601 stringFecha y hora ISO de reinicio de la cuota.
Cache-ControlstringValori di caching Edge (`s-maxage=600`, `stale-while-revalidate`) per azzerare le latenze tra chiamate identiche.

8. Códigos de Error HTTP

CódigoSignificadoEscenario Típico
200OKPetición procesada con éxito.
400Bad RequestParámetros incorrectos o ausentes (ej. radio > 50km).
401UnauthorizedClave API inválida o revocada.
429Too Many RequestsCuota mensual agotada.
500Internal ErrorError interno del servidor.

¿Necesita asistencia técnica?

Nuestro equipo de ingeniería atiende proyectos enterprise y data lakes personalizados.

📧 Contactar en infos@gethuntly.eu