PretCarburant.ro nyilvános API — REST v1

Programozott hozzáférés az aggregált romániai üzemanyagár-adatokhoz. Ugyanaz az adat, amit mi is használunk az oldalon, naponta többször frissül, hitelesítés nélkül. Creative Commons BY 4.0 licenc — szabadon használható forrásmegjelöléssel.

Gyorsindítás — nulláról az első sikeres hívásig

1. Kulcs beszerzése — vagy kezdés kulcs nélkül. Az API kulcs nélkül is azonnal hívható, csökkentett adatkészlettel (részletek a hitelesítés szakaszban). Kereskedelmi kulcs a csomagoldalon igényelhető; a pcro_live_ előtagú kulcs a feliratkozás után néhány percen belül emailben érkezik.

2. Az első hívás. Terminálból, regisztráció nélkül:

   curl -s https://pretcarburant.ro/api/v1/preturi

   Valós válasz (rövidítve: a rezultate és a retele listából csak az első elemet mutatjuk):

   {
     "data": "2026-09-02",
     "nota": "Acces public: top 20 orase. Setul complet (368 orase cu preturi) necesita o cheie API: https://pretcarburant.ro/api-preturi-carburanti",
     "preturi_lipsa": "null",
     "retele": [
       {
         "benzina": 8.92,
         "benzina_premium": 9.4,
         "culoare": "#E31937",
         "gpl": 3.72,
         "logo": "/static/img/brands/petrom.svg",
         "motorina": 9.73,
         "motorina_premium": 10.5,
         "nume": "Petrom",
         "slug": "petrom"
       }
     ],
     "rezultate": [
       {
         "benzina": 8.92,
         "benzina_premium": 9.4,
         "gpl": 4.23,
         "judet": "B",
         "lat": 44.42527,
         "lng": 26.01369,
         "motorina": 9.67,
         "motorina_premium": 10.49,
         "oras": "Bucuresti",
         "slug": "bucuresti"
       }
     ],
     "status": "ok",
     "total": 20
   }

3. Mit jelent, amit kapott? A rezultate tömb minden eleme egy város a jelenleg elérhető legalacsonyabb árakkal, RON/liter egységben: benzina = standard benzin, motorina = standard gázolaj, gpl = LPG; a null azt jelenti, hogy az adott üzemanyagra nincs adatunk (soha nem 0 — lásd az árkonvenciót). A retele tömb a hálózatok országos átlagárait hozza. Kulcs nélkül a top-20 várost kapja, és a nota mező jelzi a korlátozást; az X-Api-Key fejléccel az összes legalább egy árral rendelkező város érkezik (jelenleg 368). Innen a végpont-referencia a következő lépés.

Hitelesítés: az X-Api-Key fejléc

A kereskedelmi kulcsot HTTP-fejlécben kell küldeni, minden egyes kérésnél. A fejléc neve X-Api-Key; query-paraméteres vagy cookie-alapú változat nincs.

curl -s -H "X-Api-Key: pcro_live_A_SAJAT_KULCSOD" \
  https://pretcarburant.ro/api/v1/preturi

Kulcs nélkül a hívás nem bukik el. Ez tudatos döntés: minden végpont válaszol, de csökkentett adatkészlettel vagy szigorúbb korláttal:

• /api/v1/preturi — top-20 város a jelenlegi 368 áras város helyett (a válasz nota mezője jelzi);
• /api/v1/statii — legfeljebb 150 rekordos minta a ~6 000-ből (total_disponibil és nota mezőkkel);
• a heti kvótás végpontokon (lásd a korlátokat) 1 kérés/hét/IP/végpont.

Érvényes kulccsal a teljes adatkészletet és a csomag havi kvótáját kapja, valamint minden válaszon az X-RateLimit-* fejléceket. Érvénytelen vagy visszavont kulcsra viszont a válasz explicit 401 — nem csendes visszaesés a publikus szintre, hogy a hibát azonnal észrevegye. A valós 401-es törzs:

{
  "message": "Invalid or revoked API key.",
  "status": "error"
}

A kulcsot kezelje titokként: ne építse be kliensoldali JavaScriptbe és ne kommitolja repóba — az API-t szerveroldalról hívja.

Elérhető végpontok

Bázis URL: https://pretcarburant.ro/api/v1/. Minden válasz JSON (UTF-8), a nyilvános végpontokon nyitott CORS-szal (Access-Control-Allow-Origin: *). A HTTP-válaszok no-store cache-fejléccel érkeznek — köztes cache nem tárolja őket; maguk az áradatok naponta többször frissülnek, frissességüket az actualizat_la mező és a health check mutatja. Egy /api/ alatti hibás útvonal JSON-törzsű 404-et ad, nem HTML-oldalt.

A specifikáció további, nem a kereskedelmi adatmaghoz tartozó végpontokat is leír: GET /api/v1/reviews/<slug> és POST /api/v1/review (állomásértékelések), GET /api/v1/de-statii (németországi állomások és árak EUR-ban, Tankerkönig/MTS-K forrásból, 30 kérés/perc/IP), valamint a saját weboldalunk által használt /api/v1/push/* végpontok. Teljes leírásuk az openapi.json-ban található.

OpenAPI 3.1 specifikáció

A teljes v1 API-t formálisan leírja egy OpenAPI 3.1 specifikáció, amely a https://pretcarburant.ro/openapi.json címen érhető el (alias: /api/v1/openapi.json). Tartalmazza az összes végpontot, paramétert, válaszformát és hibakódot — közvetlenül importálható a Postmanbe vagy az Insomniába, az openapi-generator segítségével kliens generálható belőle a saját nyelvedre, vagy odaadhatod egy AI kódasszisztensnek, hogy megírja helyetted az integrációt. Korlátozás és kulcs nélkül, nyitott CORS-szal szolgáljuk ki; az /openapi.json Cache-Control: public, max-age=300 (5 perc) fejléccel érkezik, az /api/v1/openapi.json alias pedig no-store-ral, mint az API többi része.

curl -s https://pretcarburant.ro/openapi.json | jq '.info.version'

Végpont-referencia

Minden szakasz ugyanazt a sémát követi: mire való a végpont, milyen paramétereket fogad, egy valós kérés és a hozzá tartozó, az alkalmazásból rögzített valós válasz (a hosszú listák az első elemre rövidítve), végül a válasz mezői. A hiányzó árak mindenhol null-ként érkeznek — a konvenció itt.

GET /api/v1/preturi — árak városonként + hálózati átlagok

Erre a kérdésre válaszol: „melyik városban mennyibe kerül ma az üzemanyag?" — egyetlen hívásban a követett városok legalacsonyabb árai és a hálózatok országos átlagai. A kereskedelmi kulcsok fő végpontja és a beágyazható widget adatforrása.

curl -s "https://pretcarburant.ro/api/v1/preturi?judet=CLUJ"

Valós válasz (kulcs nélkül; a top-20 listából a szűrő után egy Cluj megyei város marad):

{
  "data": "2026-09-02",
  "nota": "Acces public: top 20 orase. Setul complet (368 orase cu preturi) necesita o cheie API: https://pretcarburant.ro/api-preturi-carburanti",
  "preturi_lipsa": "null",
  "retele": [
    {
      "benzina": 8.92,
      "benzina_premium": 9.4,
      "culoare": "#E31937",
      "gpl": 3.72,
      "logo": "/static/img/brands/petrom.svg",
      "motorina": 9.73,
      "motorina_premium": 10.5,
      "nume": "Petrom",
      "slug": "petrom"
    }
  ],
  "rezultate": [
    {
      "benzina": 8.69,
      "benzina_premium": 9.4,
      "gpl": 4.29,
      "judet": "CJ",
      "lat": 46.762296886121476,
      "lng": 23.556419477800848,
      "motorina": 9.27,
      "motorina_premium": 10.29,
      "oras": "Cluj Napoca",
      "slug": "cluj-napoca"
    }
  ],
  "status": "ok",
  "total": 1
}

Kulccsal: az összes legalább egy árral rendelkező város érkezik (jelenleg 368; azok a városok, ahol csak ár nélküli állomásunk van, kimaradnak), a nota mező eltűnik, és a válasz megkapja az X-RateLimit-* fejléceket.

GET /api/v1/preturi/minime — országos minimum / átlag / maximum

Erre a kérdésre válaszol: „mennyi ma a legolcsóbb, az átlagos és a legdrágább ár az országban, üzemanyagtípusonként?" Kulcs és kvóta nélkül, bárhonnan hívható.

curl -s https://pretcarburant.ro/api/v1/preturi/minime

Valós válasz (teljes):

{
  "data": "2026-09-02",
  "preturi": {
    "benzina_premium": {
      "max": 9.9,
      "mediu": 9.6,
      "min": 8.88
    },
    "benzina_standard": {
      "max": 9.42,
      "mediu": 8.98,
      "min": 8.69
    },
    "gpl": {
      "max": 5.0,
      "mediu": 4.34,
      "min": 3.61
    },
    "motorina_premium": {
      "max": 10.89,
      "mediu": 10.53,
      "min": 10.2
    },
    "motorina_standard": {
      "max": 10.49,
      "mediu": 9.74,
      "min": 9.27
    }
  },
  "preturi_lipsa": "null",
  "status": "ok"
}

A kulcs itt nem változtat semmin — a válasz mindig a teljes országos aggregátum.

GET /api/v1/judete/<judet> — megyei átlagárak

Erre a kérdésre válaszol: „mennyi az átlagár egy adott megyében?" — a megye összes követett városa fölött átlagol. Tipikus felhasználás: flottakezelés, ERP/TMS integrációk költségbecslése.

curl -s https://pretcarburant.ro/api/v1/judete/CLUJ

Valós válasz (teljes):

{
  "benzina_premium": 9.55,
  "benzina_standard": 8.92,
  "data": "2026-09-02",
  "gpl": 4.35,
  "judet": "CJ",
  "motorina_premium": 10.52,
  "motorina_standard": 9.65,
  "nr_orase": 15,
  "preturi_lipsa": "null",
  "status": "ok"
}

Figyelem: itt az ármezők a _standard utótagos neveket használják (benzina_standard), míg a /preturi válaszában a rövid benzina/motorina nevek szerepelnek — a két végpont mezőnevei nem cserélhetők fel. Ismeretlen megyére a válasz 404. Kulcs nélkül a heti kvóta alá esik; kulccsal a havi kvótát fogyasztja.

GET /api/v1/retele — hálózatok országos átlagárai

Erre a kérdésre válaszol: „melyik hálózat mennyiért ad ma üzemanyagot országos átlagban?" — árösszehasonlítás márkák között, saját felületre építhető márkaszínnel és logóval.

curl -s https://pretcarburant.ro/api/v1/retele

Valós válasz (rövidítve: a 8 hálózatból az elsőt mutatjuk):

{
  "data": "2026-09-02",
  "preturi_lipsa": "null",
  "retele": [
    {
      "benzina": 8.92,
      "benzina_premium": 9.4,
      "culoare": "#E31937",
      "gpl": 3.72,
      "logo": "/static/img/brands/petrom.svg",
      "motorina": 9.73,
      "motorina_premium": 10.5,
      "nume": "Petrom",
      "slug": "petrom"
    }
  ],
  "status": "ok"
}

GET /api/v1/statii — rekordok állomásszinten

Erre a kérdésre válaszol: „hol tankoljak a közelben, és pontosan mennyiért?" — állomásszintű rekordok koordinátákkal, térképes és útvonaltervező alkalmazásokhoz. Adatmodell: egy fizikai állomás üzemanyagtípusonként külön rekordként jelenik meg; a rekordokat a stabil id mező köti ugyanahhoz az állomáshoz.

curl -s "https://pretcarburant.ro/api/v1/statii?lat=46.77&lon=23.62&raza=5"

Valós válasz (rövidítve: a 98 rekordból az elsőt mutatjuk):

{
  "data": "2026-09-02",
  "statii": [
    {
      "adresa": "str.Teodor Mihali",
      "brand": "Mol",
      "distanta_km": 0.94,
      "id": "7f5f7f40390e",
      "judet": "",
      "lat": 46.77845,
      "lng": 23.62024,
      "oras": "Cluj-Napoca",
      "pret": 9.02,
      "tip": "benzina_standard"
    }
  ],
  "status": "ok",
  "total": 98
}

Kulcs nélkül a válasz legfeljebb 150 rekordos minta — például a ?brand=petrom&tip=motorina_standard szűrőre a rögzítéskor total: 150 és total_disponibil: 397 érkezett. Kulccsal a teljes készlet jön (a rögzítéskor 6 189 rekord). 2026. 09. 28. óta a válaszban nincsenek ár nélküli pontok egy ugyanazon állomás és üzemanyag áras rekordja mellett, és nincsenek tip nélküli rekordok.

GET /api/v1/statie/<station_id>/istoric — egy állomás árelőzményei

Erre a kérdésre válaszol: „hogyan mozgott ennek az állomásnak az ára az elmúlt napokban?" — grafikonhoz, trendfigyeléshez. A station_id a /statii válasz id mezőjéből jön.

curl -s "https://pretcarburant.ro/api/v1/statie/2f4185850d36/istoric?days=30"

Valós válasz (a rögzítés egynapos fejlesztői adatbázisról készült — élesben a labels legfeljebb days elemű, a series listái pedig vele azonos hosszúak):

{
  "labels": [
    "02.09"
  ],
  "series": {
    "benzina_premium": [
      9.4
    ],
    "benzina_standard": [
      8.92
    ],
    "motorina_premium": [
      10.5
    ],
    "motorina_standard": [
      9.73
    ]
  },
  "station_id": "2f4185850d36",
  "status": "ok",
  "variatie": {}
}

Ismeretlen vagy előzmény nélküli station_id-ra a válasz 404.

GET /api/v1/geocode — városnév-kiegészítés

Mire való: egy szabad szöveges bemenetből (kereső, űrlap) a többi híváshoz használható kanonikus városnevet ad. Nem általános geokóder — csak a követett romániai városok között keres.

curl -s "https://pretcarburant.ro/api/v1/geocode?q=cluj"

Valós válasz (teljes):

{
  "results": [
    "Cluj-Napoca"
  ]
}

Ez a válasz nem hordoz status mezőt — a siker jele maga a results lista.

POST /api/v1/traseu/custom — állomások egy A→B útvonal mentén

Erre a kérdésre válaszol: „hol tankoljak útközben?" — geokódolja a két végpontot, kiszámolja az útvonalat, és visszaadja az útvonal menti állomásokat a kért üzemanyag árával. Ez az egyetlen POST végpont az adatmagban.

curl -s -X POST https://pretcarburant.ro/api/v1/traseu/custom \
  -H "Content-Type: application/json" \
  -d '{"start": "Bucuresti", "end": "Brasov", "tip": "motorina_standard"}'

Valós válasz (rövidítve: a 153 állomásból az elsőt, a waypoints-ból az első két pontot mutatjuk):

{
  "duration_min": 165,
  "end": {
    "lat": 45.655,
    "lng": 25.611,
    "name": "Brasov"
  },
  "km": 182.0,
  "ok": true,
  "start": {
    "lat": 44.4268,
    "lng": 26.1025,
    "name": "Bucuresti"
  },
  "statii": [
    {
      "adresa": "Str. Fagarasului 2",
      "brand": "Rompetrol",
      "dist_ruta": 4.0,
      "lat": 45.662296,
      "lng": 25.574169,
      "oras": "Brasov",
      "pret": 9.67,
      "tip": "motorina_standard"
    }
  ],
  "tip": "motorina_standard",
  "total_statii": 153,
  "waypoints": [
    [
      44.425874,
      26.102435
    ],
    [
      44.428773,
      26.103985
    ]
  ]
}

Figyelem: a hibái is a saját formáját követik — {"ok": false, "msg": "..."}, 400-as státusszal, nem a szokásos {status, message} párost (lásd a katalógusban).

GET /api/v1/cheie — a saját kulcs állapota

Erre a kérdésre válaszol: „hol tartok a havi kvótámmal?" — a kliens-dashboard adatforrása. Csak kulccsal hívható, és nem fogyasztja sem a havi, sem a publikus kvótát: a saját fogyasztás ellenőrzése nem kerül semmibe.

curl -s -H "X-Api-Key: pcro_live_A_SAJAT_KULCSOD" \
  https://pretcarburant.ro/api/v1/cheie

Valós válasz (frissen kiállított teszt-kulccsal rögzítve):

{
  "abonament": false,
  "consum_luna": 2,
  "creata": "2026-09-02T20:35:21+00:00",
  "limita_lunara": 10000,
  "plan": "starter",
  "plan_nume": "Starter",
  "status": "ok",
  "total_cereri": 2,
  "ultima_folosire": "2026-09-02T20:35:22+00:00",
  "zilnic": [
    {
      "count": 2,
      "zi": "2026-09-02"
    }
  ]
}

Érvénytelen kulcsra itt is 401 a válasz.

Health check: /api/v1/health

Éles üzem előtti és utáni monitorozáshoz: a GET /api/v1/health hitelesítés és korlátozás nélkül válaszol, Cache-Control: no-store fejléccel — egy cache-ből kiszolgált health check pont azt az incidenst rejtené el, amelyet észlelni szeretnél.

Valós válasz (HTTP 200, 2026.09.25.):

{
  "actualizat_la": "2026-09-24T21:15:07.097831+00:00",
  "inregistrari_total": 6656,
  "observatie_cea_mai_veche": "2026-09-21",
  "preturi_disponibile": 5481,
  "preturi_fara_data_observatie": 0,
  "statii_cu_pret": 5481,
  "statii_cu_pret_unice": 1348,
  "statii_total": 1705,
  "status": "ok",
  "vechime_maxima_descarcare_secunde": 19324,
  "vechime_maxima_secunde": 19324,
  "vechime_secunde": 2816
}

• status — "ok" vagy "degraded".
• actualizat_la — bármely árforrás legutóbbi sikeres írásának időpontja, ISO 8601 időzóna-eltolással; null, ha nem megállapítható. Ugyanaz az érték, mint a /preturi, /preturi/minime, /retele és /judete válaszok actualizat_la mezője.
• vechime_secunde — hány másodperce történt ez a legutóbbi írás. Csak tájékoztató, nem ez dönti el az állapotot.
• vechime_maxima_secunde — hány másodperce volt a szolgálatban lévő árforrások közül a legrégebbi sikeres letöltés; ez dönti el az állapotot.
• vechime_maxima_descarcare_secunde — ugyanez a szám a pontos nevén: a letöltést méri, nem az árak korát.
• observatie_cea_mai_veche — a kiszolgált árak közül a legrégebbi megfigyelés időpontja, ahogy a forrás közli (dátum, vagy dátum és idő); null, ha egyiknek sincs.
• preturi_fara_data_observatie — hány kiszolgált árnak nincs megfigyelési dátuma.
• statii_cu_pret — történeti mező: nem üres árral rendelkező állomás × üzemanyag rekordok, nem fizikai állomások.
• inregistrari_total — az összes állomás × üzemanyag rekord, a hiányzó vagy lejárt árakkal együtt.
• preturi_disponibile — érvényes árral rendelkező rekordok a lejárat után; a 0 azt jelenti, hogy nem szolgálunk ki árat.
• statii_total — a térképen szereplő különböző fizikai állomások, az ár nélküliekkel együtt.
• statii_cu_pret_unice — legalább egy érvényes árral rendelkező különböző fizikai állomások.

A HTTP-státuszkód mindent elmond: 200 = minden szolgálatban lévő árforrás írt az elmúlt 24 órában, és szolgálunk ki árakat; 503 (status: "degraded" értékkel) = legalább egy szolgálatban lévő árforrás 24 óránál régebbi (egy élő forrás nem takar el egy kiesettet), nem maradt szolgálatban lévő árforrás, vagy egyetlen árat sem szolgálunk ki. A szándékosan kivont forrásokat nem vizsgáljuk. Egy olyan monitor, amely csak a státuszkódot nézi, elegendő; 503 esetén a törzs ugyanazt a 12 mezőt tartalmazza.

Hibakatalógus

Az API hibái mindig JSON-törzzsel érkeznek. Az alapforma {"status": "error", "message": "..."}; a kvótahibák további mezőket adnak, a /traseu/custom pedig — történeti okból — {ok, msg} formát használ. A message szövege román nyelvű és nem stabil kontraktus: a kliens a HTTP-státuszkódra és a gépi mezőkre (limit, retry_after_seconds, next_allowed) ágazzon el, soha ne a szövegre.

401 — érvénytelen kulcs (valós törzs):

{
  "message": "Invalid or revoked API key.",
  "status": "error"
}

404 — ismeretlen megye a /api/v1/judete/xyz hívásra (valós törzs):

{
  "message": "Judet necunoscut: xyz",
  "status": "error"
}

404 — ismeretlen állomás vagy nincs előzmény az /istoric végponton (valós törzs):

{
  "message": "Statie necunoscuta sau fara istoric. Foloseste campul `id` din /api/v1/statii.",
  "status": "error"
}

429 — a csomag havi kvótája elfogyott (valós törzs; a válaszon ott vannak az X-RateLimit-Limit: 10000, X-RateLimit-Remaining: 0, X-RateLimit-Reset és Retry-After fejlécek is):

{
  "limit": 10000,
  "message": "Cvota lunara a planului (10000 cereri) a fost depasita.",
  "status": "error",
  "upgrade_url": "https://pretcarburant.ro/api-preturi-carburanti"
}

429 — a publikus heti kvóta elfogyott (valós törzs; a válaszon ott van a Retry-After fejléc és egy rel="payment" típusú Link fejléc a csomagokra):

{
  "message": "Rate limit: 1 cerere pe saptamana. Urmatoarea cerere permisa peste 6z 23h.",
  "message_en": "Rate limit: 1 request per week per IP for this endpoint without an API key. Next request allowed in 6d 23h.",
  "next_allowed": "2026-09-09T23:31:29.780524+03:00",
  "retry_after_seconds": 604799,
  "status": "error",
  "upgrade_mesaj": "O cheie API inlocuieste limita saptamanala cu cota lunara a planului (de la 10.000 cereri/luna).",
  "upgrade_message": "An API key replaces the weekly limit with a monthly plan quota (from 10,000 requests/month).",
  "upgrade_url": "https://pretcarburant.ro/api-preturi-carburanti",
  "upgrade_url_en": "https://pretcarburant.ro/en/fuel-price-api"
}

400 — a /traseu/custom nem találta a helységet (valós törzs — figyelje az eltérő {ok, msg} formát):

{
  "msg": "Nu am gasit locatia",
  "ok": false
}

503 — elavult adatok a /health végponton: a törzs ugyanazt a 12 mezőt tartalmazza, mint 200 esetén (lásd health), status: "degraded" értékkel.

503 — a kulcsok ellenőrzése átmenetileg nem elérhető (pontos törzs; Retry-After: 30 fejléccel érkezik):

{
  "message": "Verificarea cheii API e temporar indisponibila. Reincearca peste 30 de secunde.",
  "message_en": "API key verification is temporarily unavailable. Retry in 30 seconds.",
  "retry_after_seconds": 30,
  "status": "error"
}

404 — nem létező útvonal az /api/ alatt (pontos törzs; a 410 ugyanilyen formájú):

{
  "docs": "https://pretcarburant.ro/api",
  "message": "Endpoint inexistent.",
  "message_en": "Not found.",
  "status": "error"
}

Kódminták — ugyanaz a hívás négy nyelven

Mindegyik minta ugyanazt teszi: lekéri a városonkénti árakat kulccsal, kezeli a 401/429 hibákat, és kiolvassa a kvótafejléceket — nem csak a happy path.

curl

curl -s -D fejlecek.txt -o valasz.json \
  -H "X-Api-Key: pcro_live_A_SAJAT_KULCSOD" \
  https://pretcarburant.ro/api/v1/preturi
grep -i '^x-ratelimit' fejlecek.txt
jq '.total, .preturi_lipsa' valasz.json

Python (requests)

import requests

API_KEY = "pcro_live_A_SAJAT_KULCSOD"

resp = requests.get(
    "https://pretcarburant.ro/api/v1/preturi",
    headers={"X-Api-Key": API_KEY},
    timeout=10,
)

print("Maradék kvóta:", resp.headers.get("X-RateLimit-Remaining"))

if resp.status_code == 429:
    varakozas = int(resp.headers.get("Retry-After", "3600"))
    print(f"Kvóta elfogyott — újrapróbálás {varakozas} s múlva")
elif resp.status_code == 401:
    print("Érvénytelen kulcs:", resp.json()["message"])
else:
    resp.raise_for_status()
    data = resp.json()
    # A hiányzó árak null-ként érkeznek — átlagolás előtt ki kell zárni őket.
    arak = [o["benzina"] for o in data["rezultate"] if o["benzina"] is not None]
    print(f"{data['total']} város, ebből {len(arak)} benzinárral")

JavaScript (fetch, Node 18+)

const API_KEY = "pcro_live_A_SAJAT_KULCSOD";

const resp = await fetch("https://pretcarburant.ro/api/v1/preturi", {
  headers: { "X-Api-Key": API_KEY },
});

console.log("Maradék kvóta:", resp.headers.get("X-RateLimit-Remaining"));

if (resp.status === 429) {
  const s = Number(resp.headers.get("Retry-After") || 3600);
  throw new Error(`Kvóta elfogyott — újrapróbálás ${s} s múlva`);
}
if (!resp.ok) {
  const hiba = await resp.json();
  throw new Error(`API-hiba ${resp.status}: ${hiba.message}`);
}

const data = await resp.json();
// A hiányzó árak null-ként érkeznek — átlagolás előtt szűrje ki őket.
const arak = data.rezultate
  .map((oras) => oras.benzina)
  .filter((ar) => ar !== null);
console.log(`${data.total} város, ebből ${arak.length} benzinárral`);

PHP (curl)

<?php
$apiKey = 'pcro_live_A_SAJAT_KULCSOD';

$ch = curl_init('https://pretcarburant.ro/api/v1/preturi');
$fejlecek = [];
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . $apiKey],
    CURLOPT_HEADERFUNCTION => function ($ch, $sor) use (&$fejlecek) {
        if (stripos($sor, 'X-RateLimit') === 0 || stripos($sor, 'Retry-After') === 0) {
            [$nev, $ertek] = explode(':', trim($sor), 2);
            $fejlecek[$nev] = trim($ertek);
        }
        return strlen($sor);
    },
]);

$torzs = curl_exec($ch);
$statusz = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($torzs === false) {
    exit("Hálózati hiba\n");
}
$data = json_decode($torzs, true);

if ($statusz === 429) {
    exit('Kvóta elfogyott — újrapróbálás ' . ($fejlecek['Retry-After'] ?? '?') . " s múlva\n");
}
if ($statusz !== 200) {
    exit('API-hiba ' . $statusz . ': ' . ($data['message'] ?? '') . "\n");
}

echo 'Maradék kvóta: ' . ($fejlecek['X-RateLimit-Remaining'] ?? 'n/a') . "\n";
// A hiányzó árak null-ként érkeznek — átlagolás előtt zárja ki őket.
$arak = array_filter(
    array_column($data['rezultate'], 'benzina'),
    fn($ar) => $ar !== null
);
printf("%d város, ebből %d benzinárral\n", $data['total'], count($arak));

Válaszformátum

Minden sikeres válasz status: "ok" mezőt hordoz, a legtöbb egy data mezőt (a szerver ISO 8601 dátuma a válasz pillanatában — nem az árak dátuma; azt az actualizat_la adja), az árválaszok pedig a preturi_lipsa konvenciójelzőt is. A teljes, valós válaszok az egyes végpont-szakaszokban láthatók. Hiba esetén a törzs alapformája:

{
  "message": "Judet necunoscut: xyz",
  "status": "error"
}

A kvótahibák további gépi mezőket adnak, a /traseu/custom pedig {ok, msg} formát használ — a teljes lista a hibakatalógusban.

Hiányzó árak: null, nem 0

Ha egy városban vagy egy hálózatnál nincs meg az adott üzemanyag ára, a mező null értékkel érkezik. Egyetlen üzemanyag sem kerül nulla lejbe — a valós sávok: benzin 5,50–12,00 RON/L, dízel 5,50–13,00, LPG 2,50–6,00 —, tehát a 0 nem mérés lenne, hanem kitalált érték, amely lehúzza a válaszunk fölött számolt bármely átlagot. A szabály a /preturi végpontra (a rezultate[] és a retele[] mezőkre egyaránt), a /preturi/minime végpontra (min, mediu, max), a /judete/<judet> és a /retele végpontokra vonatkozik.

Kizárólag az ármezők konvertálódnak. A total, nr_orase, lat vagy lng mezőben a 0 marad 0, mert ott a nulla valódi válasz, nem hiányzó érték. A /statii végpont pret mezője már korábban is null volt.

{
  "oras": "Turda", "slug": "turda", "judet": "CJ",
  "lat": 46.5667, "lng": 23.7833,
  "benzina": 7.15, "benzina_premium": null,
  "motorina": 7.40, "motorina_premium": null, "gpl": null
}

Azoknak az integrációknak, amelyek nem frissíthetők velünk együtt, a ?zeros=1 (a ?zeros=true is működik) pontosan a korábbi viselkedést hozza vissza, null helyett 0 értékkel:

curl -s "https://pretcarburant.ro/api/v1/preturi?zeros=1" | jq '.rezultate[0]'

Minden válasz maga jelzi a használt konvenciót a preturi_lipsa mezőben: "null" (alapértelmezett) vagy "zero" (a ?zeros=1 paraméterrel). Olvassa ki kódból, ne feltételezze — csak így lehet biztosan tudni, mit kapott. A konverzió egyirányú: a null soha nem lesz 0, még ?zeros=1 esetén sem, mert a /judete/<judet> korábban is null értéket adott, ha nem volt miből átlagot számolnia.

Adatkonvenciók

Korlátok és AI bot szabályok

Anonim felhasználóknál a korlátozott végpontokon (/judete, /retele, /statii, /statie/<id>/istoric, /geocode, /traseu/custom) 1 kérés/hét/IP/végpont a limit. A /preturi és /preturi/minime végpontok kvóta nélkül hívhatók, ahogy a /health és az /openapi.json is. Érvényes API-kulccsal a heti kvóta helyébe a csomag havi kvótája lép: Starter 10 000, Pro 100 000, Business 1 000 000 kérés/hó (részletek lent). Kulcsonként rövid távú korlát is érvényes: legfeljebb 5 kérés másodpercenként és 120 kérés percenként, a szerver összes folyamatára közösen; felette 429-es választ kapsz retry_after_seconds mezővel és Retry-After fejléccel, az elutasított kérés pedig nem számít bele a havi kvótába.

Az AI asszisztensek (ChatGPT, Claude, Perplexity, Gemini, Bing Copilot stb.) explicit User-Agent fehérlistán vannak. Ők a heti limit helyett 60 kérés/perc/IP cappal férnek hozzá, hogy közvetlenül idézhessék az adatainkat. Felismert UA-k: GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, anthropic-ai, PerplexityBot, Google-Extended, Googlebot, Applebot-Extended, Bytespider, Meta-ExternalAgent, CCBot, MistralAI, cohere-ai, YouBot, DiffBot, Bravebot és mások. A /statii és a /statie/<id>/istoric végponton a mentességhez fordított DNS-ellenőrzés is kell (forward-confirmed reverse DNS), így ott csak a Google, a Bing, az Apple, a Yandex és a Baidu crawlerei kapják meg; a többi bot ezen a két végponton a heti nyilvános kvótát kapja.

Az X-RateLimit-* kvótafejlécek

Minden érvényes API-kulccsal (X-Api-Key fejléc) küldött kérés három válaszfejlécet kap, amelyek pontosan megmutatják, hol tartasz a havi fogyasztással — minden végponton, a nyilvánosakon is:

• X-RateLimit-Limit — a csomagod havi kvótája (pl. 10000 a Starter csomagon).
• X-RateLimit-Remaining — hány kérésed maradt a visszaállításig (soha nem negatív).
• X-RateLimit-Reset — a visszaállítás pillanatának Unix időbélyege (másodperc, UTC): a következő UTC naptári hónap kezdete, a mérés tényleges ablaka.

A fejlécek a kvótatúllépést jelző 429-es válaszon is megérkeznek — pontosan akkor, amikor a legnagyobb szükséged van rájuk —, a Retry-After fejléccel együtt: ez a kvóta visszaállításáig hátralévő másodpercek száma, valósan kiszámolva, nem fix érték. Kiolvasásuk:

curl -s -D - -o /dev/null -H "X-Api-Key: A_KULCSOD" \
  https://pretcarburant.ro/api/v1/statii

HTTP/2 200
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9977
X-RateLimit-Reset: 1790812800

Az 1790812800 jelentése: 2026. október 1., 00:00 UTC. Amikor az X-RateLimit-Remaining a nullához közelít, ideje nagyobb csomagra váltani — a visszaállítás után a számláló újra a teljes kvótáról indul.

Verziózás és kompatibilitás

Amit garantálunk — és amit nem:

• A /api/v1 útvonalak és a meglévő mezők stabilak: meglévő mezőt nem törlünk, nem nevezünk át, és a típusát sem változtatjuk meg új főverzió nélkül.
• Új mezők külön bejelentés nélkül is megjelenhetnek a válaszokban. Erre a kliensnek felkészültnek kell lennie: az ismeretlen mezőket hagyja figyelmen kívül, és ne a mezők számára vagy sorrendjére építsen (a JSON-kulcsok sorrendje amúgy sem garantált).
• A viselkedést érintő változásokat a verziótörténetben dokumentáljuk ezen az oldalon, és az openapi.json info.version mezője (szemantikus verziószám) is követi őket.
• Az eddigi egyetlen, meglévő klienseket érintő változás (v1.4: hiányzó árak null-ként) kompatibilitási kapcsolót kapott (?zeros=1). Ez a minta a jövőben is: ha egy változás meglévő integrációt törhetne, átmeneti kapcsolót vagy új verziót kap.
• Formális, százalékos rendelkezésre állási SLA-t a nyilvános szinthez nem vállalunk; szerződéses SLA a dedikált csomag része — lásd lent.

Licenc és forrásmegjelölés

Az adatok Creative Commons BY 4.0 licenc alatt vannak közzétéve. Szabadon felhasználhatók kereskedelmi és nem kereskedelmi célokra is, látható forrásmegjelöléssel: „Forrás: PretCarburant.ro (https://pretcarburant.ro)".

A licenc minden /api/v1 válaszra vonatkozik, kulccsal vagy anélkül: az előfizetés a hozzáférést fizeti (teljes adatkészlet és havi kvóta), nem egy másik licencet. Minden válasz a rel="license" típusú Link fejlécben is jelzi.

A teljes adatállomány Zenodo DOI-val is elérhető: 10.5281/zenodo.19560194. A szervezet azonosítója a Wikidatán: Q139285387.

Kereskedelmi / nagy volumenű hozzáférés

Verziótörténet

• v1.0 (2026-04-01) — első 5 nyilvános végpont; 5 perces cache; nyitott CORS.
• v1.1 (2026-04-14) — bot UA fehérlista AI asszisztenseknek; per-IP 60 kérés/perc cap.
• v1.2 (2026-05-07) — formális nyilvános dokumentáció a /api címen (RO/EN/HU).
• v1.3 (2026-07-26) — self-serve kereskedelmi csomagok API-kulcsokkal (X-Api-Key fejléc), csomagonkénti havi kvóták és X-RateLimit-Limit/X-RateLimit-Remaining fejlécek; a /geocode és /traseu/custom végpontok dokumentálva.
• v1.4 (2026-08-16) — a hiányzó árak 0 helyett null értékkel érkeznek a /preturi, /preturi/minime, /judete és /retele végpontokon; a ?zeros=1 paraméter visszahozza a régi formátumot, a preturi_lipsa mező pedig minden válaszban közli a használt konvenciót.
• v1.5 (2026-09-02) — OpenAPI 3.1 specifikáció az /openapi.json címen; GET /api/v1/health health check végpont; az X-RateLimit-Reset fejléc, valamint a kvótafejlécek minden kulcsos válaszon (a 429-esen is), a hónap tényleges visszaállításáig számolt Retry-After értékkel.
• v1.6 (2026-09-23) — a publikus heti kvóta 429-es válasza megmondja, hol kapható kulcs: új, kiegészítő mezők (upgrade_url, upgrade_url_en, message_en, upgrade_mesaj/upgrade_message), valamint Retry-After és rel="payment" típusú Link fejléc. A meglévő mezők nem változnak.
• v1.7 (2026-09-25) — új, kiegészítő actualizat_la mező a /preturi, /preturi/minime, /retele és /judete válaszokban (az adatok időpontja; a data továbbra is a szerver napja); a next_allowed explicit időzóna-eltolással érkezik; elérhetetlen kulcsadatbázis esetén 503 Retry-After fejléccel, nem 401; az /api/ alatti nem létező útvonal JSON 404-et ad; a nem véges paraméterek (nan, inf) és a rossz típusú JSON-törzsek 400-at adnak, nem 500-at; Retry-After fejléc a percenkénti 429-eken.
• v1.8 (2026-09-28) — /statii: új, kiegészítő nesigur, motiv_nesigur és nesigur_din mezők a beragadt, árva vagy régi megfigyelésű árakon, amelyeket az oldal kihagy a minimumokból; actualizat_la itt is; a tip adblue értéke dokumentálva; nincsenek többé ár nélküli duplikált pontok és tip nélküli rekordok; a specifikációban nem szereplő belső mezők nem kerülnek ki (az alkalmazásbeli javaslatoké, geo_dedus, geo_incercat, coord_corectata, added_at); a még ár nélküli jóváhagyott állomások nem jelennek meg tip nélküli sorként. A prémium minimum kihagyja az ugyanazon kút standard árával egyezőként jelentett prémium árakat. A /traseu/custom nem listázza a beragadt vagy árva árakat (a csak régiek maradnak). A /preturi (kulccsal) és a /judete csak a legalább egy árral rendelkező városokat számolja, számukat pedig az oldal az adatokból írja ki, nem kézzel.

Kapcsolat és hibajelentés

Email: contact@pretcarburant.ro. Technikai hibákhoz vagy feature kérésekhez tegyen „[API]" előtagot a tárgyba. Munkanapokon 48 órán belül válaszolunk.

Felelős nyilvánosságra hozatal biztonsági problémák esetén: lásd /.well-known/security.txt.