API BenzynaMAPA – dokumentacja JSON

Name: Aktualne ceny paliw w Polsce – BenzynaMAPA dataset
Creator: BenzynaMAPA.pl
License: https://opendatacommons.org/licenses/odbl/1-0/

Otwarte API z aktualnymi cenami paliw na 8 600+ stacjach w Polsce. Darmowe do użytku niekomercyjnego, aktualizacja 3× dziennie, licencja ODbL.

JSON endpointów

3×

dziennie

FREE

bez API key

ODbL

licencja

Szybki start

API jest pre-rendered jako statyczne pliki JSON serwowane z CDN Vercel. Brak rejestracji, brak API key, brak rate limit dla normalnego użytku.

curl https://benzynamapa.pl/data/stats_latest.json

Response: JSON z aktualnymi średnimi krajowymi (Pb95, Pb98, ON, LPG), trendem 7-dniowym i licznikiem stacji.

Endpointy

GET/data/stats_latest.json

~~2 KB

Aktualne średnie ceny + statystyki rynku

Schema (JSON)

{
  "last_updated": "ISO 8601 timestamp",
  "averages": {
    "pb95": "number (zł/l)",
    "pb98": "number",
    "on": "number",
    "lpg": "number"
  },
  "cheapest_today": {
    "pb95": "{ price, station_id, city }",
    "...": "..."
  },
  "trend_7d": {
    "pb95": "number (zmiana w zł/l)",
    "on": "number",
    "lpg": "number"
  },
  "total_stations": "number",
  "stations_updated_today": "number"
}

→ Otwórz endpoint live

GET/data/prices_latest.json

~~2 MB

Wszystkie aktualne ceny paliw (jeden rekord per stacja)

Schema (JSON)

{
  "prices": "[{ station_id, pb95, pb98, on, lpg, source, reported_at }]"
}

→ Otwórz endpoint live

GET/data/stations_latest.json

~~5 MB

Pełna baza stacji paliw (GPS, adres, sieć, usługi)

Schema (JSON)

{
  "stations": "[{ id, name, brand, lat, lng, address, city, region, services[], opening_hours }]"
}

→ Otwórz endpoint live

GET/data/history_90d.json

~~50 KB

90-dniowa historia średnich cen krajowych

Schema (JSON)

{
  "history": "[{ date, pb95, pb98, on, lpg }]"
}

→ Otwórz endpoint live

GET/data/map_data.json

~~3 MB

GeoJSON dla mapy (stacje + cluster data)

Schema (JSON)

{
  "type": "\"FeatureCollection\"",
  "features": "[GeoJSON Feature]"
}

→ Otwórz endpoint live

Przykłady użycia

JavaScript (fetch)

const stats = await fetch('https://benzynamapa.pl/data/stats_latest.json')
  .then(r => r.json());

console.log(`Średnia Pb95: ${stats.averages.pb95} zł/l`);
console.log(`Trend 7 dni: ${stats.trend_7d.pb95 > 0 ? '+' : ''}${stats.trend_7d.pb95.toFixed(2)} zł`);

Python (requests)

import requests

stats = requests.get('https://benzynamapa.pl/data/stats_latest.json').json()
print(f"Średnia Pb95: {stats['averages']['pb95']} zł/l")
print(f"Liczba stacji: {stats['total_stations']:,}")

curl

# Aktualne średnie
curl https://benzynamapa.pl/data/stats_latest.json | jq '.averages'

# Najtańsza Pb95 dziś
curl https://benzynamapa.pl/data/stats_latest.json | jq '.cheapest_today.pb95'

PHP

<?php
$stats = json_decode(file_get_contents('https://benzynamapa.pl/data/stats_latest.json'));
echo "Średnia Pb95: {$stats->averages->pb95} zł/l\n";

Licencja i atrybucja

Dane stacji (lokalizacje, adresy): ODbL (Open Database License) - z OpenStreetMap.
Ceny paliw: agregacja z publicznych źródeł, nasza praca - wymagana atrybucja.
Wymagana atrybucja: "Źródło: BenzynaMAPA.pl + OpenStreetMap" + aktywny link do https://benzynamapa.pl
Użytek niekomercyjny (osobisty, edukacyjny, badawczy, open-source): za darmo
Komercyjny: kontakt z operatorem - kontakt@benzynamapa.pl

CORS & Cache

Access-Control-Allow-Origin: * - dostępne z każdej domeny
Cache-Control: public, max-age=3600, stale-while-revalidate=7200 - 1h fresh, 2h SWR
Content-Type: application/json; charset=utf-8
CDN: Vercel Edge Network - latency < 100 ms z Europy

FAQ

Czy API jest darmowe?▼

Tak, do użytku niekomercyjnego (osobistego, edukacyjnego, badawczego, jednostkowych projektów open-source). Wymagane podanie źródła: "Źródło: BenzynaMAPA.pl" + link do https://benzynamapa.pl. Komercyjne wykorzystanie - kontakt: kontakt@benzynamapa.pl.

Jak często aktualizowane są dane?▼

Wszystkie endpointy są regenerowane 3× dziennie (6:00, 10:00, 15:00 CET) przez automatyczne pipeline GitHub Actions. Każdy rekord ma znacznik czasu (last_updated, reported_at).

Jaka jest licencja danych?▼

Dane stacji (lokalizacje, adresy) pochodzą z OpenStreetMap - licencja ODbL (Open Database License). Ceny są naszą agregacją z publicznych źródeł. Wymagamy podania atrybucji "Źródło: BenzynaMAPA.pl + OpenStreetMap".

Czy jest rate limit?▼

Endpointy są serwowane jako statyczne pliki JSON z CDN Vercel - brak rate limit dla normalnego użytku. Prosimy o cache po stronie aplikacji (Cache-Control: max-age=3600 jest ustawiony).

CORS - czy mogę używać z przeglądarki?▼

Tak. Wszystkie endpointy mają Access-Control-Allow-Origin: * - dostępne z każdej domeny w przeglądarce (fetch, axios, jQuery).

Czy jest webhook / powiadomienia?▼

Aktualnie nie. Polecamy polling raz na 6 godzin lub subskrypcję IndexNow (Bing). Dla komercyjnych klientów rozważamy webhook za opłatą - kontakt.

Czy API obsługuje filtrowanie po GPS / mieście?▼

Aktualnie nie - serwujemy pełne snapshoty. Aby filtrować, pobierz stations_latest.json i przefiltruj po lat/lng/city w aplikacji. Dla flot z dużą ilością zapytań rozważamy graphql endpoint - kontakt.

Co to są historyczne ceny?▼

history_90d.json zawiera średnie krajowe per dzień przez ostatnie 90 dni. Historia per stacja nie jest publicznie dostępna - tylko snapshot bieżący. Dłuższa historia dla klientów komercyjnych.

→ O nas → Jak działa BenzynaMAPA → Regulamin → GitHub repo