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
Programadores
API MaPompe
Integre postos e preços de combustíveis da MaPompe numa aplicação, site ou serviço.
01 · PRIMEIROS PASSOS
URL base
https://mapompe.com/api/v1
A API comercial utiliza autenticação por chave API. As chamadas destinam-se a utilização servidor-a-servidor.
Importante:
O endpoint /api/stations utilizado pelo site público da MaPompe é uma API interna. Não faz parte da API comercial e o acesso está protegido.
02 · AUTENTICAçãO
Chave API
Crie uma chave em A minha conta → API para programadores. A chave completa é apresentada apenas uma vez.
X-API-Key: mp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
O esquema Bearer também é aceite:
Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Nunca coloque uma chave API em JavaScript distribuído para o navegador, numa aplicação móvel sem proteção ou num repositório Git público.
03 · ENDPOINT
Postos à volta de um ponto
/api/v1/stations
Devolve os postos ativos mais próximos, ordenados por preço e depois por distância.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
lat |
number | Sim | Latitude du centre. |
lng |
number | Sim | Longitude du centre. |
radius |
number | Não | Rayon en kilomètres selon le plan. |
fuel |
string | Não | gazole, e10, sp95, sp98, e85 ou gplc. |
limit |
integer | Não | 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
Pesquisa de postos
/api/v1/search
Pesquise por nome, marca, morada, cidade, código postal ou nome apresentado pelo Google.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q |
string | Sim | 3 à 80 caractères. |
limit |
integer | Não | 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
Histórico de preços
/api/v1/stations/{station_id}/history
Devolve a evolução do preço de um combustível num posto. O histórico disponível depende do plano.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
station_id |
integer | Sim | Identifiant de la station dans MaPompe. |
fuel |
string | Não | Carburant demandé. |
days |
integer | Não | 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 · PLANOS
Planos e limites
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
Proteção contra utilização massiva:
As quotas mensais, diárias e por minuto são cumulativas. Várias chaves pertencentes à mesma conta partilham a mesma quota. A API não disponibiliza exportações em massa da base de dados.
07 · ERROS
Códigos HTTP
| Code | Erro | Significado |
|---|---|---|
200 |
OK | Pedido processado. |
400 |
Paramètres invalides | Falta um parâmetro, é inválido ou está fora dos limites. |
401 |
Clé invalide | Chave ausente, incorreta ou revogada. |
404 |
Not found | O posto não existe ou está inativo. |
429 |
Limite atteinte | Quota mensal, diária ou limite por minuto ultrapassado. |
500 |
Server error | Erro interno do serviço. |
{
"error": "quota_exceeded",
"message": "Quota mensuel atteint.",
"limit": 1000,
"used": 1000,
"reset_at": "2026-10-01T00:00:00Z",
"retry_after": 518400
}
BOAS PRÁTICAS
Utilizar a API corretamente
Cache
Coloque os resultados em cache no servidor quando for adequado. Não é necessário pedir várias vezes a mesma zona num período curto.
Chave privada
Guarde a chave numa variável de ambiente ou gestor de segredos. Nunca a coloque no Git.
Respeitar os limites
Utilize os cabeçalhos X-RateLimit-Remaining e X-Quota-Remaining para controlar a integração.
Sem scraping
A API destina-se à integração de aplicações e não à criação de uma cópia da base de dados da MaPompe.