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, 2 óránként frissül, hitelesítés nélkül. Creative Commons BY 4.0 licenc — szabadon használható forrásmegjelöléssel.

Többre van szükséged az ingyenes keretnél? Kereskedelmi csomagok 19 €/hó-tól — 10 000–1 000 000 kérés/hó, 3 napos próba. Csomagok megtekintése →

Elérhető végpontok

Bázis URL: https://pretcarburant.ro/api/v1/. Az összes válasz JSON, Cache-Control: public, max-age=300 és Access-Control-Allow-Origin: * fejlécekkel a nyilvános végpontokon.

REST v1 végpontok
Végpont	Leírás	Korlát
`GET /api/v1/preturi`	Városonként aggregált árak (opcionális szűrő `?judet=CLUJ`)	Nincs (5 perces cache)
`GET /api/v1/preturi/minime`	Országos minimum/átlag/maximum árak üzemanyagtípusonként	Nincs (5 perces cache)
`GET /api/v1/judete/<judet>`	Megyei szintű aggregált átlagár (pl. `/api/v1/judete/CLUJ`)	1 kérés/hét/IP
`GET /api/v1/retele`	Figyelt hálózatok márkaszintű átlagárakkal	1 kérés/hét/IP
`GET /api/v1/statii`	Állomáslista koordinátákkal, márkával, árakkal (szűrők: `?brand=`, `?tip=`, `?lat=&lon=&raza=` a sugáron belüli állomásokhoz, km) Minden rekord tartalmaz egy stabil `id`-t az állomáshoz.	1 kérés/hét/IP
`GET /api/v1/statie/<station_id>/istoric`	Egy töltőállomás árelőzményei (`station_id` = az `id` mező a `/api/v1/statii` válaszból; ismeretlen id → 404)	1 kérés/hét/IP
`GET /api/v1/geocode`	Városnév-kiegészítés (`?q=cluj`, min. 2 karakter)	1 kérés/hét/IP
`POST /api/v1/traseu/custom`	Töltőállomások egy A→B útvonal mentén (JSON body: `start`, `end`, `tip`)	1 kérés/hét/IP

cURL példák

Városonként aggregált árak

curl -s https://pretcarburant.ro/api/v1/preturi | jq '.rezultate[0]'

Megye szerinti szűrés

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

Országos minimum árak

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

Petrom állomások gázolajjal

curl -s "https://pretcarburant.ro/api/v1/statii?brand=petrom&tip=motorina_standard" | jq '.statii | length'

Állomások 10 km-es sugárban (lat/lon)

curl -s "https://pretcarburant.ro/api/v1/statii?lat=46.77&lon=23.62&raza=10" | jq '.total'

Megyei átlagár

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

Korlátok és AI bot szabályok

Anonim felhasználóknál a korlátozott végpontokon (/retele, /statii, /istoric) 1 kérés/hét/IP a limit. A /preturi és /preturi/minime végpontok limit nélküliek (5 perces cache).

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.

Válaszformátum

Minden válasz közös szerkezete:

{
  "status": "ok",
  "data": "2026-05-07",
  "preturi_lipsa": "null",
  "rezultate": [...]
}

Hiba esetén:

{
  "status": "error",
  "message": "Rate limit: 1 kérés hetente...",
  "retry_after_seconds": 543210
}

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.

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

Az ingyenes CC-BY 4.0 szint változatlan marad: 1 kérés/hét/IP a korlátozott végpontokon, látható forrásmegjelöléssel. Nem zárjuk le és nem plafonáljuk — a nyilvános adat nyilvános marad.

Alkalmazások, flották, szerkesztőségek és bármilyen nagy volumenű integráció számára azonnal aktiválható kereskedelmi csomagok állnak rendelkezésre — az API-kulcs a feliratkozás után néhány percen belül emailben érkezik:

Starter — 19 €/hó, 10 000 kérés/hó
Pro — 49 €/hó, 100 000 kérés/hó
Business — 149 €/hó, 1 000 000 kérés/hó, elsőbbségi támogatás

Mindegyik csomag tartalmaz 3 napos ingyenes próbát, hozzáférést az összes végponthoz heti kvóta nélkül, valamint az X-RateLimit-* fejléceket a fogyasztás nyomon követéséhez. Csomagok és előfizetés →

Egyedi igények (szerződéses SLA, bulk export, történeti pillanatképek, kiterjesztett jogok forrásmegjelölés nélkül)? Írjon nekünk dedikált ajánlatért.

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.

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.