Free
0 €
- 1 000 requêtes / mois
- 100 requêtes / jour
- 5 requêtes / minute
- Rayon 10 km
- 25 résultats / requête
- Historique 14 jours
- 1 clé active
Sviluppatori
API MaPompe
Integra stazioni e prezzi dei carburanti MaPompe in un’applicazione, un sito o un servizio.
01 · PER INIZIARE
URL di base
https://mapompe.com/api/v1
L’API commerciale utilizza l’autenticazione tramite chiave API. Le chiamate sono pensate per un utilizzo server-to-server.
Importante:
L’endpoint /api/stations utilizzato dal sito pubblico MaPompe è un’API interna. Non fa parte dell’API commerciale e il suo accesso è protetto.
02 · AUTENTICAZIONE
Chiave API
Crea una chiave da Il mio account → API sviluppatori. La chiave completa viene mostrata una sola volta.
X-API-Key: mp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
È accettato anche lo schema Bearer:
Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Non inserire mai una chiave API nel JavaScript distribuito al browser, in un’app mobile non protetta o in un repository Git pubblico.
03 · ENDPOINT
Stazioni intorno a un punto
/api/v1/stations
Restituisce le stazioni attive più vicine, ordinate per prezzo e poi per distanza.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
lat |
number | Sì | Latitude du centre. |
lng |
number | Sì | Longitude du centre. |
radius |
number | No | Rayon en kilomètres selon le plan. |
fuel |
string | No | gazole, e10, sp95, sp98, e85 ou gplc. |
limit |
integer | No | Nombre maximal de stations selon le plan. |
curl -H "X-API-Key: mp_live_xxx" \
"https://mapompe.com/api/v1/stations?lat=43.3442&lng=3.2150&radius=10&fuel=gazole&limit=25"
{
"data": [
{
"id": 123,
"country": "FR",
"slug": "station-exemple",
"name": "Station Exemple",
"brand": "TotalEnergies",
"address": "10 rue Exemple",
"city": "Béziers",
"postcode": "34500",
"latitude": 43.3442,
"longitude": 3.2150,
"price_eur": 1.749,
"observed_at": "2026-09-24 12:00:00",
"distance_km": 1.42,
"price_quality": "official",
"station_url": "https://mapompe.com/station/FR/station-exemple"
}
],
"meta": {
"count": 1,
"fuel": "gazole",
"latitude": 43.3442,
"longitude": 3.2150,
"radius_km": 10,
"limit": 25,
"plan": "free",
"plan_name": "Free"
}
}
04 · ENDPOINT
Ricerca stazioni
/api/v1/search
Ricerca per nome, marca, indirizzo, città, CAP o nome visualizzato da Google.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
q |
string | Sì | 3 à 80 caractères. |
limit |
integer | No | Nombre maximal de résultats selon le plan. |
curl -H "X-API-Key: mp_live_xxx" \
"https://mapompe.com/api/v1/search?q=Béziers&limit=10"
{
"data": [
{
"id": 123,
"country": "FR",
"slug": "station-exemple",
"name": "Station Exemple",
"brand": "TotalEnergies",
"city": "Béziers",
"postcode": "34500",
"latitude": 43.3442,
"longitude": 3.215,
"hours": null,
"services": [],
"updated_at": "2026-09-24 12:00:00",
"station_url": "https://mapompe.com/station/FR/station-exemple"
}
],
"meta": {
"count": 1,
"query": "Béziers",
"limit": 10,
"plan": "free",
"plan_name": "Free"
}
}
05 · ENDPOINT
Storico dei prezzi
/api/v1/stations/{station_id}/history
Restituisce l’evoluzione del prezzo di un carburante presso una stazione. La profondità dello storico dipende dal piano.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
station_id |
integer | Sì | Identifiant de la station dans MaPompe. |
fuel |
string | No | Carburant demandé. |
days |
integer | No | Nombre de jours selon le plan. |
curl -H "X-API-Key: mp_live_xxx" \
"https://mapompe.com/api/v1/stations/123/history?fuel=gazole&days=14"
{
"data": [
{
"price_eur": 1.749,
"observed_at": "2026-09-24 12:00:00"
},
{
"price_eur": 1.739,
"observed_at": "2026-09-23 12:00:00"
}
],
"meta": {
"station_id": 123,
"fuel": "gazole",
"days": 14,
"count": 2,
"plan": "free",
"plan_name": "Free"
}
}
06 · PIANI
Piani e limiti
Starter
19 € / mois
- 25 000 requêtes / mois
- 2 000 requêtes / jour
- 20 requêtes / minute
- Rayon 25 km
- 50 résultats / requête
- Historique 30 jours
- 3 clés actives
Pro
59 € / mois
- 150 000 requêtes / mois
- 10 000 requêtes / jour
- 60 requêtes / minute
- Rayon 50 km
- 100 résultats / requête
- Historique 90 jours
- 5 clés actives
Business
149 € / mois
- 500 000 requêtes / mois
- 30 000 requêtes / jour
- 120 requêtes / minute
- Rayon 100 km
- 150 résultats / requête
- Historique 180 jours
- 10 clés actives
Protezione dall’uso massivo:
Le quote mensili, giornaliere e al minuto sono cumulative. Più chiavi appartenenti allo stesso account condividono la stessa quota. L’API non fornisce esportazioni massive del database.
07 · ERRORI
Codici HTTP
| Code | Errore | Significato |
|---|---|---|
200 |
OK | Richiesta elaborata. |
400 |
Paramètres invalides | Un parametro è assente, non valido o fuori dai limiti. |
401 |
Clé invalide | Chiave assente, errata o revocata. |
404 |
Not found | La stazione non esiste o è inattiva. |
429 |
Limite atteinte | Quota mensile, giornaliera o limite al minuto superato. |
500 |
Server error | Errore interno del servizio. |
{
"error": "quota_exceeded",
"message": "Quota mensuel atteint.",
"limit": 1000,
"used": 1000,
"reset_at": "2026-10-01T00:00:00Z",
"retry_after": 518400
}
BUONE PRATICHE
Usare correttamente l’API
Cache
Metti in cache i risultati lato server quando opportuno. Non serve richiedere più volte la stessa zona in un breve periodo.
Chiave privata
Conserva la chiave in una variabile d’ambiente o in un gestore di segreti. Non inserirla mai in Git.
Rispetta i limiti
Usa gli header X-RateLimit-Remaining e X-Quota-Remaining per gestire l’integrazione.
Niente scraping
L’API è destinata all’integrazione applicativa, non alla creazione di una copia del database MaPompe.