PretCarburant.ro Public API — REST v1

Programmatic access to aggregated Romanian fuel price data. Same data we use on the site, refreshed several times a day, no authentication required. Licensed Creative Commons BY 4.0 — free to use with attribution.

Quickstart: from zero to your first call

1. Get a key — or start without one. Every endpoint answers without authentication, with a reduced data set or quota. For the full data set and a monthly quota, subscribe at /en/fuel-price-api — the key (format pcro_live_...) arrives by email within minutes and every plan starts with a 3-day free trial.
2. Make your first call. No key needed for this one:

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

3. Read what you got. The response is JSON: status: "ok", today's date in data, current minimum prices per city in rezultate (in RON per liter — benzina is petrol, motorina is diesel, gpl is LPG) and national network averages in retele. Without a key you get the top 20 cities and a nota field saying so; with a key in the X-Api-Key header the same call returns every city with at least one price (252 right now). A missing price is null, never 0 — see data conventions.

That is the whole loop: one GET, one JSON body, field names in Romanian (they are part of the stable contract — we do not rename them). Everything below is detail.

Authentication

Authentication is a single header, sent on every request: X-Api-Key. There is no OAuth, no token exchange, no expiry dance.

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

Without a key the request does not fail — it succeeds with less: /api/v1/preturi returns the top 20 cities instead of all 252 cities with prices, /api/v1/statii returns a 150-record sample instead of all ~6,000, and the endpoints marked below accept 1 request per week per IP. A valid key removes the truncation and replaces the weekly cap with your plan's monthly quota, plus X-RateLimit-* headers on every response.

A key that is present but invalid or revoked is an explicit 401, not a silent downgrade — a paying client must never be quietly served the public subset. Real response:

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

Keep the key server-side. Never ship it in browser JavaScript or a mobile app binary — anyone can read it there. If a key leaks, write to contact@pretcarburant.ro and we rotate it.

Available Endpoints

Base URL: https://pretcarburant.ro/api/v1/. All responses are JSON; public read endpoints send Access-Control-Allow-Origin: *. Every response carries Cache-Control: no-store: no intermediate cache (CDN, proxy, browser) keeps it, so every request reaches the server — if you need a cache, keep it on your side; prices change several times a day and the actualizat_la field tells you how fresh they are. A wrong path under /api/ answers 404 with a JSON body, not an HTML page. Each row links to the detailed section for that endpoint.

OpenAPI 3.1 Specification

The whole v1 API is formally described in an OpenAPI 3.1 specification, available at https://pretcarburant.ro/openapi.json (alias: /api/v1/openapi.json). It covers every endpoint, parameter, response shape and error code — import it straight into Postman or Insomnia, generate a client in your language with openapi-generator, or hand it to an AI coding assistant to write the integration for you. Served without rate limiting and with open CORS; /openapi.json carries Cache-Control: public, max-age=300 (5 minutes), the /api/v1/openapi.json alias no-store like the rest of the API.

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

Endpoint Reference

One section per endpoint: what it is for, its parameters with real constraints, a runnable request, and the actual response captured from the API (long lists trimmed to their first element — the shape is untouched). Prices are RON per liter unless stated otherwise.

GET /api/v1/preturi — prices per city + network averages

The main endpoint: current minimum prices in each monitored city, plus the national average of each network — everything an app needs to answer "how much is fuel where my user is". No weekly cap (it also feeds the embeddable widget); like the whole API, responses carry Cache-Control: no-store.

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

Real response without a key (lists trimmed to the first element):

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

With a key: the same request returns every city with at least one price ("total": 252 right now; cities where we only have stations without a price are left out), the nota field disappears, and the response carries the X-RateLimit-* headers.

GET /api/v1/preturi/minime — national min / avg / max

The cheapest, average and most expensive price in the country for each fuel type — the numbers behind a "prices today" headline. Fully public: no key, no weekly cap. Only the zeros parameter applies. Real response, complete:

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

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

GET /api/v1/judete/<judet> — county averages

One number per fuel for a whole county — for fleet tools and regional dashboards that do not care about individual cities. Averages over all cities of the county. Weekly public cap without a key.

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

Real response, complete:

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

An unknown county is an explicit 404: {"status": "error", "message": "Judet necunoscut: xx"}.

GET /api/v1/retele — network averages

The current national average of each monitored fuel network — for brand comparisons. Same shape as the retele array of /preturi, without the city data, plus data and actualizat_la with the same meaning. Weekly public cap without a key; only the zeros parameter applies.

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

Real response (trimmed to two of the 8 networks — note the honest null where OMV does not sell LPG):

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

GET /api/v1/statii — station-level records

The granular data set: one record per station per fuel type (a physical station selling four fuels appears four times). This is what you want for maps, "cheapest near me" features and price monitoring.

curl -s -H "X-Api-Key: pcro_live_YOUR_KEY" \
  "https://pretcarburant.ro/api/v1/statii?brand=petrom&tip=motorina_standard"

Real response with a key (trimmed to the first of 397 records):

{
  "status": "ok",
  "data": "2026-09-02",
  "total": 397,
  "statii": [
    {
      "id": "2f4185850d36",
      "brand": "Petrom",
      "oras": "Campeni",
      "judet": "Alba",
      "adresa": "Str. Libertatii 19A, 515500",
      "lat": 46.3618,
      "lng": 23.04885,
      "tip": "motorina_standard",
      "pret": 9.73
    }
  ]
}

With the geo filter (?lat=46.77&lon=23.62&raza=5) each record gains distanta_km (distance from your point, km) and the list is sorted by it. Without a key the response is a sample capped at 150 records, plus two extra fields captured here for real: "total_disponibil": 6189 (how many records exist) and a nota explaining the sample. With a key you get all of them.

The response also carries actualizat_la next to data: the moment of the last successful price update, ISO 8601 with offset, the same value as in /api/v1/health. Since 2026-09-28 it no longer contains price-less pins left next to a priced record of the same station and fuel, nor records without tip.

GET /api/v1/statie/<station_id>/istoric — price history

Daily price series of one station — for trend charts and "did this station just raise prices?" logic. The station_id is the id field from /statii; nothing else is accepted.

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

Real response, complete:

{
  "status": "ok",
  "station_id": "2f4185850d36",
  "labels": ["27.08", "28.08", "29.08", "30.08", "31.08", "01.09", "02.09"],
  "series": {
    "benzina_standard": [9.51, 9.51, 9.51, 9.51, 9.51, 9.51, 9.55],
    "benzina_premium": [9.99, 9.99, 9.99, 9.99, 9.99, 9.99, 10.03],
    "motorina_standard": [10.14, 10.14, 10.14, 10.14, 10.14, 9.97, 9.97],
    "motorina_premium": [10.91, 10.91, 10.91, 10.91, 10.91, 10.74, 10.74]
  },
  "variatie": {
    "benzina_standard": 0.04,
    "benzina_premium": 0.04,
    "motorina_standard": 0.0,
    "motorina_premium": 0.0
  }
}

An unknown id — or a station with no recorded history — is a 404 with a hint in the body: {"status": "error", "message": "Statie necunoscuta sau fara istoric. Foloseste campul `id` din /api/v1/statii."}.

GET /api/v1/geocode — city autocomplete

Turns a partial city name into full names for a search box. At most 10 matches; fewer than 2 characters returns an empty list rather than an error.

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

Real response, complete: {"results": ["Cluj-Napoca"]}. Note this endpoint has no status field — just results, an array of strings.

POST /api/v1/traseu/custom — stations along a route

Geocodes two place names, computes the driving route between them and returns the fuel stations within a corridor along it — the backend of a "where do I refuel on the way" feature. This is the only v1 endpoint that takes a JSON body, and the only one whose errors use {"ok": false, "msg": "..."} instead of the usual status/message shape — handle it separately.

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

Real response (of 153 stations found, statii trimmed to the first — the API itself returns at most 50 — and waypoints to the first two of ~200):

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

A place that cannot be geocoded, an impossible route or an invalid body (not a JSON object, start/end/tip not strings, raza not a positive number) is a 400, in the same {ok, msg} shape: {"ok": false, "msg": "Nu am gasit locatia"}.

GET /api/v1/cheie — your key's status

Self-service introspection for the key you send: plan, quota, consumption, daily breakdown. It never consumes quota and has no public cap — checking your own usage must not cost anything. Requires X-Api-Key; without a valid key it is a 401 (body: {"status": "error", "message": "Cheie invalida sau revocata."}).

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

Real response (zilnic trimmed):

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

GET /api/v1/reviews/<slug> — station reviews

Public rating and up to 20 approved reviews of one station. The slug is the station's URL slug from the site's /statie/... pages. No key, no cap. A slug with no reviews is still a 200 — real response, complete:

curl -s https://pretcarburant.ro/api/v1/reviews/petrom-campeni-1

{
  "status": "ok",
  "avg_rating": 0,
  "review_count": 0,
  "reviews": []
}

Each element of reviews[] carries the reviewer's nickname, the star rating (1–5), the comment text and the submission date.

POST /api/v1/review — submit a rating

Adds a star rating, optionally with a text review, to a station. A rating alone (stars only) is accepted directly; any free text (a comment, or a custom nickname) additionally requires a reCAPTCHA v3 token and goes through moderation before it appears.

curl -s -X POST https://pretcarburant.ro/api/v1/review \
  -H "Content-Type: application/json" \
  -d '{"statie_slug": "petrom-campeni-1", "rating": 5}'

Real response, complete:

{
  "status": "ok",
  "message": "Multumim pentru rating!",
  "avg_rating": 5.0,
  "review_count": 1
}

Errors: 400 for a missing slug, an invalid rating, a body that is not a JSON object or text fields of another type (e.g. {"status": "error", "message": "Slug statie lipsa."} — captured for real), 403 when reCAPTCHA verification fails, 429 when the same IP submits too many reviews.

GET /api/v1/de-statii — stations in Germany

Live station prices in Germany, for the Romanian diaspora — a proxy over Tankerkönig/MTS-K open data (CC BY 4.0). This is a completely separate channel from the Romanian data: prices are in EUR per liter and never mix into the national aggregates. Limited to 30 requests per minute per IP; no weekly cap and no key needed.

curl -s "https://pretcarburant.ro/api/v1/de-statii?lat=52.52&lng=13.40&rad=2"

Real response (trimmed to the first of 3 stations):

{
  "status": "ok",
  "tara": "DE",
  "moneda": "EUR",
  "sursa": "Tankerkönig / MTS-K (CC BY 4.0)",
  "atribuire": "https://www.tankerkoenig.de",
  "lat": 52.52,
  "lng": 13.4,
  "rad_km": 2.0,
  "nr_statii": 3,
  "generat_la": "2026-09-02T23:35+03:00",
  "statii": [
    {
      "nume": "TotalEnergies Berlin",
      "brand": "TotalEnergies",
      "lat": 52.528899,
      "lng": 13.41808,
      "dist_km": 1.6,
      "benzina": 2.249,
      "e10": 2.189,
      "motorina": 2.269,
      "deschis": true,
      "adresa": "Prenzlauer Allee 1-4",
      "oras": "Berlin",
      "cod_postal": 10405
    }
  ]
}

Fields: benzina is E5, e10 is E10, motorina is diesel (all EUR/liter, null when the station does not sell that fuel); deschis = open right now; dist_km = distance from your point. Responses are kept for 10 minutes on the server, keyed on coordinates rounded to 0.01 degrees and the radius rounded to the km — lat/lng may be those of the request that filled the cache, and generat_la says when. Errors: 400 for missing, non-finite (nan, inf) or out-of-Germany coordinates ({"status": "error", "message": "Coordonatele trebuie să fie în Germania."}), 429 over 30 requests/minute (with a Retry-After header), 502 when the upstream source does not answer, 503 when the service is temporarily unavailable.

GET /api/v1/push/vapid-key and POST /api/v1/push/subscribe — web push

These two exist for this site's own service worker (browser price alerts) and are documented for completeness — they are not meant for commercial integrations. GET /api/v1/push/vapid-key returns the public VAPID key (real response: {"status": "ok", "publicKey": "BE7ueOZzVNlQLqeFLGAb8Oq6rLc2sIhf8_j9gcl5FTgYwo9eB2YX8u23O0HaIO9NXJGDLM-ClmPHqeyz3mIAHrQ"}). POST /api/v1/push/subscribe registers a browser push subscription: required body fields endpoint, p256dh, auth; optional pagina — the path of the page the visitor subscribed on, from which the server derives the city and fuel of the subscription (without it, or on a page with no city, the subscription is national). The old fields tip_carburant, prag_pret and oras are accepted but ignored since 2026-09-23. The response returns the derived oras and tip_carburant (null when there is none). Missing required fields → 400 (real body: {"status": "error", "message": "Missing endpoint, p256dh or auth"}).

cURL Examples

City-aggregated prices

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

Filter by county

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

National minimum prices

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

Petrom stations selling diesel

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

Stations within 10 km (lat/lon)

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

County average price

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

Code Samples

The same call in four languages: county-filtered prices with an API key, with error handling and quota-header reading — not just the happy path. Replace pcro_live_YOUR_KEY with your key.

curl

curl -s -w '\nHTTP %{http_code}\n' \
  -H "X-Api-Key: pcro_live_YOUR_KEY" \
  "https://pretcarburant.ro/api/v1/preturi?judet=CJ"

Python (requests)

import requests

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

remaining = resp.headers.get("X-RateLimit-Remaining")
if remaining is not None and int(remaining) < 100:
    print(f"Warning: only {remaining} requests left this month")

if resp.status_code == 401:
    raise SystemExit("API key invalid or revoked")
if resp.status_code == 429:
    retry_after = int(resp.headers.get("Retry-After", "3600"))
    raise SystemExit(f"Quota exceeded, retry in {retry_after} s")
resp.raise_for_status()

body = resp.json()
for city in body["rezultate"]:
    # A missing price is None -- skip it, never treat it as 0
    if city["motorina"] is not None:
        print(city["oras"], city["motorina"], "RON/L")

JavaScript (fetch, Node 18+)

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

const remaining = resp.headers.get("x-ratelimit-remaining");
if (remaining !== null && Number(remaining) < 100) {
  console.warn(`Only ${remaining} requests left this month`);
}

if (resp.status === 401) throw new Error("API key invalid or revoked");
if (resp.status === 429) {
  const retryAfter = resp.headers.get("retry-after");
  throw new Error(`Quota exceeded, retry in ${retryAfter} s`);
}
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);

const body = await resp.json();
for (const city of body.rezultate) {
  // A missing price is null -- skip it, never treat it as 0
  if (city.motorina !== null) {
    console.log(city.oras, city.motorina, "RON/L");
  }
}

PHP (curl)

<?php
$ch = curl_init("https://pretcarburant.ro/api/v1/preturi?judet=CJ");
$headers = [];
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ["X-Api-Key: pcro_live_YOUR_KEY"],
    CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) {
        $parts = explode(":", $line, 2);
        if (count($parts) === 2) {
            $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
        }
        return strlen($line);
    },
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status === 401) { exit("API key invalid or revoked\n"); }
if ($status === 429) {
    exit("Quota exceeded, retry in " . ($headers["retry-after"] ?? "?") . " s\n");
}
if ($status !== 200) { exit("HTTP $status\n"); }

if (isset($headers["x-ratelimit-remaining"]) && (int)$headers["x-ratelimit-remaining"] < 100) {
    fwrite(STDERR, "Only {$headers['x-ratelimit-remaining']} requests left this month\n");
}

$body = json_decode($raw, true);
foreach ($body["rezultate"] as $city) {
    // A missing price is null -- skip it, never treat it as 0
    if ($city["motorina"] !== null) {
        echo $city["oras"] . " " . $city["motorina"] . " RON/L\n";
    }
}

Error Catalog

Every error body below was captured from the API, verbatim (messages are in Romanian — they are part of the observed contract). Route on the HTTP status code, not on message text.

401 — invalid or revoked key

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

404 — unknown county / unknown station

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

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

429 — plan quota exceeded (with a key)

Comes with X-RateLimit-Limit, X-RateLimit-Remaining: 0, X-RateLimit-Reset and Retry-After headers:

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

429 — public weekly quota (without a key)

Comes with a Retry-After header and a Link header with rel="payment" pointing to the plans:

{
  "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:33:07.255254+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"
}

503 — degraded data on /health

The body has the same 12 fields as on 200 (see health), with status: "degraded".

503 — key verification temporarily unavailable (with a key)

Exact body; comes with a Retry-After: 30 header:

{
  "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 — unknown path under /api/

Exact body; 410 has the same shape:

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

One deliberate exception: /traseu/custom reports its errors as {"ok": false, "msg": "Nu am gasit locatia"} — different shape, same 400 status.

Data Conventions

• Unit and currency — all Romanian prices are RON per liter; only /de-statii is EUR per liter (its moneda field says so).
• Decimal separator in JSON is always a point (9.67), regardless of the language of this page — JSON numbers know no locale. Format for display in your own layer.
• Missing prices come as null, never 0 — details, the preturi_lipsa field and the ?zeros=1 escape hatch in the section below. If you compute averages, exclude null values first.
• Dates and timestamps are ISO 8601 — data is YYYY-MM-DD, the server's day when it answered — not the date of the prices (that is actualizat_la); timestamps (actualizat_la, creata, generat_la, next_allowed) carry an explicit offset. One exception: the labels of /istoric are DD.MM display labels.
• Time zone — quota metering runs on the UTC calendar month, and X-RateLimit-Reset is a Unix timestamp in UTC. Timestamps in bodies state their own offset; do not assume Romanian local time.
• Coordinates — WGS84 decimal degrees, fields lat and lng (query parameter lon, with lng accepted as alias).
• Field names are Romanian and stable — oras (city), judet (county), retele (networks), statii (stations), pret (price). They are the contract; we do not translate or rename them.

Rate Limits and AI Bot Policy

Anonymous users hit 1 request/week/IP on rate-limited endpoints (/judete, /retele, /statii, /istoric, /geocode, /traseu/custom). The /preturi and /preturi/minime endpoints are rate-limit-free, and so are /health, /reviews and /openapi.json. A valid API key replaces the weekly cap with your plan's monthly quota on all of them.

AI assistants (ChatGPT, Claude, Perplexity, Gemini, Bing Copilot, etc.) are bypassed via an explicit User-Agent whitelist. They get a 60 req/min/IP cap instead (shared by all server processes; over it, a 429 with Retry-After), so they can cite our data directly in answers. Whitelisted UAs include: GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, anthropic-ai, PerplexityBot, Google-Extended, Googlebot, Applebot-Extended, Bytespider, Meta-ExternalAgent, CCBot, MistralAI, cohere-ai, YouBot, DiffBot, Bravebot and others.

The X-RateLimit-* Quota Headers

Every request carrying a valid API key (X-Api-Key header) gets three response headers telling you exactly where you stand with your monthly usage — on every endpoint, public ones included:

• X-RateLimit-Limit — your plan's monthly quota (e.g. 10000 on Starter).
• X-RateLimit-Remaining — requests left until the reset (never negative).
• X-RateLimit-Reset — Unix timestamp (seconds, UTC) of the reset moment: the start of the next UTC calendar month, the actual metering window.

The headers also come on the quota-exceeded 429 response — exactly when you need them most — together with Retry-After: the number of seconds until the quota resets, computed for real, not a fixed value. Reading them:

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

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

1790812800 means 1 October 2026, 00:00 UTC. When X-RateLimit-Remaining approaches zero, it is time to move to a bigger plan — after the reset the counter starts again from the full quota.

Response Format

All responses share this shape:

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

On error:

{
  "status": "error",
  "message": "Rate limit: 1 request per week...",
  "retry_after_seconds": 543210
}

Missing prices: null, not 0

When we do not have a fuel price for a city or a network, the field comes back as null. No fuel costs zero RON — the real ranges are 5.50–12.00 RON/L for petrol, 5.50–13.00 for diesel and 2.50–6.00 for LPG — so a 0 would not be a measurement but a made-up value that drags down any average computed over our response. The rule applies to /preturi (both rezultate[] and retele[]), /preturi/minime (the min, mediu, max fields), /judete/<judet> and /retele.

Only price fields are converted. A 0 in total, nr_orase, lat or lng stays 0, because there zero is a real answer, not a missing value. The pret field in /statii was already null before this change.

{
  "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
}

For integrations that cannot be updated alongside us, ?zeros=1 (?zeros=true also works) restores the exact previous behaviour, with 0 instead of null:

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

Every response declares its own convention in the preturi_lipsa field: "null" (default) or "zero" (with ?zeros=1). Read it in code instead of assuming — it is the only reliable way to know what you got. The conversion only goes one way: a null never becomes 0, not even with ?zeros=1, because /judete/<judet> already answered null when it had nothing to average.

Health Check: /api/v1/health

For monitoring before and after going to production: GET /api/v1/health answers without authentication, without rate limiting and with Cache-Control: no-store — a cached health check would hide exactly the incident you are trying to detect.

Real response (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" or "degraded".
• actualizat_la — the most recent successful write of any price source, ISO 8601 with offset; null when it cannot be determined. Same value as actualizat_la on /preturi, /preturi/minime, /retele and /judete.
• vechime_secunde — seconds since that most recent write. Informative only: it does not decide the status.
• vechime_maxima_secunde — seconds since the oldest successful download among the price sources in service; this one decides the status.
• vechime_maxima_descarcare_secunde — the same number under its accurate name: it measures downloads, not how old the prices are.
• observatie_cea_mai_veche — the oldest observation moment among the prices served, as the source publishes it (a date, or date and time); null when no served price has one.
• preturi_fara_data_observatie — how many served prices carry no observation date.
• statii_cu_pret — historical field: station×fuel records with a non-empty price, not physical stations.
• inregistrari_total — all station×fuel records, including missing or expired prices.
• preturi_disponibile — records with a valid price after expiry; 0 means no prices are being served.
• statii_total — distinct physical stations on the map, including those without a price.
• statii_cu_pret_unice — distinct physical stations with at least one valid price.

The HTTP status code tells the whole story: 200 = every price source in service wrote within the last 24 hours and prices are being served; 503 (with status: "degraded") = at least one price source in service is older than 24 hours (one live source does not hide a dead one), no price source is in service any more, or no prices are being served. Sources retired on purpose are not judged. A monitor that only checks the status code is enough; on 503 the body keeps the same 12 fields.

License and Attribution

Data is published under Creative Commons BY 4.0. Free to use commercially or non-commercially with visible attribution: "Source: PretCarburant.ro (https://pretcarburant.ro)".

The license covers every /api/v1 response, with or without an API key: a subscription pays for access (the full dataset and the monthly quota), not for a different license. Every response also states it in the Link header with rel="license".

The full dataset is also published on Zenodo with DOI: 10.5281/zenodo.19560194. Organization identity on Wikidata: Q139285387.

Commercial / high-volume access

Versioning and Compatibility

What we promise — and only what we can actually keep:

• /api/v1 is stable. Existing fields keep their names, types and meaning. Code written against this page keeps working.
• We add without notice. New fields in responses, new optional parameters and new endpoints can appear at any time — parse what you know and ignore what you do not (most JSON libraries already do).
• We do not remove or rename inside v1. A breaking change — removing a field, renaming it, changing its type — would ship as a new version under a new path, with the old one kept running through an announced transition period.
• When behaviour changes compatibly (like missing prices becoming null in v1.4 — with the ?zeros=1 escape hatch), we document it in the version history below, bump the info.version of the OpenAPI spec, and email API subscribers.
• No formal SLA on the free tier. We run monitoring and take availability seriously, but uptime percentages are only guaranteed in dedicated enterprise contracts — ask via contact. Use /health to observe data freshness yourself.

Version History

• v1.0 (2026-04-01) — initial 5 public endpoints; 5-min cache; open CORS.
• v1.1 (2026-04-14) — bot UA whitelist for AI assistants; per-IP 60 req/min flood cap.
• v1.2 (2026-05-07) — formal public documentation at /api (RO/EN/HU).
• v1.3 (2026-07-26) — self-serve commercial plans with API keys (X-Api-Key header), per-plan monthly quotas and the X-RateLimit-Limit/X-RateLimit-Remaining headers; /geocode and /traseu/custom endpoints documented.
• v1.4 (2026-08-16) — missing prices are returned as null instead of 0 on /preturi, /preturi/minime, /judete and /retele; the ?zeros=1 parameter restores the old format, and the preturi_lipsa field states which convention each response used.
• v1.5 (2026-09-02) — OpenAPI 3.1 specification at /openapi.json; GET /api/v1/health health-check endpoint; the X-RateLimit-Reset header, plus quota headers on every keyed response (429 included), with Retry-After computed to the actual monthly reset. Full developer manual on this page: quickstart, per-endpoint reference with real captured responses, error catalog, code samples in four languages.
• v1.6 (2026-09-23) — the public weekly-quota 429 now says where to get a key: additive fields upgrade_url, upgrade_url_en, message_en, upgrade_mesaj/upgrade_message, plus the Retry-After header and a Link header with rel="payment". Existing fields are unchanged.
• v1.7 (2026-09-25) — additive actualizat_la field on /preturi, /preturi/minime, /retele and /judete (the moment of the data; data stays the server's day); next_allowed carries an explicit offset; an unavailable key database answers 503 with Retry-After, not 401; an unknown path under /api/ answers a JSON 404; non-finite parameters (nan, inf) and JSON bodies of the wrong type are a 400, not a 500; Retry-After on the per-minute 429s. The documentation now states the real caching: no-store on all of /api/ (the "5-min cache" on /preturi was wrong).
• v1.8 (2026-09-28) — /statii: additive nesigur, motiv_nesigur and nesigur_din fields on stuck, orphaned or stale prices, which the site keeps out of its minimums; actualizat_la there too; the adblue value of tip, now documented; no more price-less duplicate pins and no records without tip; internal fields that were not in the specification are no longer sent (app proposals, geo_dedus, geo_incercat, coord_corectata, added_at); approved stations with no price yet no longer appear as a row without tip. The premium minimum skips premium prices reported equal to the same pump's standard price. /traseu/custom no longer lists stuck or orphaned prices (merely stale ones stay). /preturi (with a key) and /judete count only cities with at least one price, and this page states their number from the data, not by hand.

Contact and Bug Reports

Email: contact@pretcarburant.ro. For technical bugs or feature requests, prefix the subject with „[API]". We reply within 48 business hours.

Responsible disclosure for security issues: see /.well-known/security.txt.