oneapi
Autentificare
Carburanti v1 / Carburanti

Clasamentul țărilor

Ţările ordonate după preţul unui carburant într-o săptămână: unde e cel mai ieftin şi unde cel mai scump, cu diferenţa faţă de medie.

GET
https://oneapi.ro/api/carburanti/v1/clasament

Parametri de interogare

NumeTipDescriereValori acceptate
produsobligatoriu string Codul produsului. Obligatoriu: un clasament ordonează ţările după preţul unui singur produs. benzina95motorinamotorina_incalzirepacura_sulf_micpacura_sulf_maregpl
dataopțional string | null Data de referință, AAAA-LL-ZZ. Implicit: cea mai recentă săptămână. ex. 2026-08-31
ordineopțional string | null crescator (cel mai ieftin întâi, implicit) sau descrescator. crescatordescrescator
limitaopțional integer | null Câte țări să întoarcă, maximum 30. Implicit 30, adică toate. 1 – 30

Cum se comportă

  • Două incoerenţe cunoscute ale sursei, tratate explicit. (1) Buletinul are 2 rânduri cu ambele preţuri 0,00 (Slovacia, păcură, 2006-05-01) — o lipsă de date publicată ca zero. Le servim ca null, nu ca preţ, şi nu construim nimic peste ele. (2) La 32 de rânduri, toate pe păcură, preţul CU taxe e mai mic decât cel FĂRĂ, ceea ce ar da o taxă negativă: 30 pe agregatul EU şi câte unul pe BE şi IE. Cele două preţuri se redau ca atare, dar nu calculăm nimic peste ele — taxe_din_pret_procent e null şi apare un câmp atentionare.
  • Mediile EU și EA sunt excluse din clasament: nu sunt țări, iar un top „cel mai ieftin" în care o medie concurează cu o țară n-ar însemna nimic.
  • Ca la comparație, toate țările sunt din aceeași săptămână de referință. Cine n-a raportat în ea lipsește pur și simplu din clasament.
  • Ordonarea e după prețul cu taxe în euro.

La ce folosește

  • Găsești unde e cel mai ieftin motorina în UE într-o săptămână dată, pentru planificarea alimentărilor pe rute lungi.
  • Ilustrezi într-un articol sau raport poziția unei țări în topul european, cu sursa la vedere.

Structura răspunsului

Toate câmpurile de mai jos sunt în data.

CâmpTipDescriere
produs string Produsul clasat.
ceruta string Data cerută.
saptamana string Săptămâna de referință.
ordine string Ordinea aplicată.
rezultate[].pozitie integer Poziția în clasament, de la 1.
rezultate[] object Restul câmpurilor sunt ca la un element din data.produse[] la GET /preturi.
sursa object Sursa și licența.
rezultate[].tara string Codul țării.
rezultate[].data string Săptămâna la care se referă prețul (luni-ul buletinului).
rezultate[].produs string Codul produsului.
rezultate[].denumire string Denumirea produsului.
rezultate[].unitate string Unitatea în care e cotat produsul: 1.000 de litri la carburanți, 1.000 kg la păcură.
rezultate[].eur.cu_taxe integer Prețul în euro, cu toate taxele incluse, pe unitatea de cotare.
rezultate[].eur.fara_taxe number Prețul în euro, fără taxe.
rezultate[].eur.pe_litru_cu_taxe number Același preț adus la litru — null la produsele cotate pe tonă.
rezultate[].eur.pe_litru_fara_taxe number Prețul fără taxe, pe litru.
rezultate[].national.moneda string Moneda națională a țării la data respectivă. Se schimbă în timp: statele care au adoptat euro au serii în două monede.
rezultate[].national.curs_eur_pe_unitate number Cursul folosit de sursă la conversie. Când lipsește sau e 1,0, țara era deja în euro — de acolo deducem moneda, nu dintr-un tabel.
rezultate[].national.cu_taxe integer Prețul în moneda națională, cu taxe.
rezultate[].national.fara_taxe integer Prețul în moneda națională, fără taxe.
rezultate[].national.pe_litru_cu_taxe number Prețul național pe litru, cu taxe.
rezultate[].national.pe_litru_fara_taxe number Prețul național pe litru, fără taxe.
rezultate[].taxe_din_pret_procent number Cât la sută din prețul final sunt taxe — cifra cea mai citată dintr-un buletin.

Exemple de răspuns

GEThttps://oneapi.ro/api/carburanti/v1/clasament?produs=motorina&limita=5
{
    "data": {
        "produs": "motorina",
        "ceruta": "2026-09-14",
        "saptamana": "2026-09-14",
        "ordine": "crescator",
        "rezultate": [
            {
                "pozitie": 1,
                "tara": "MT",
                "data": "2026-09-14",
                "produs": "motorina",
                "denumire": "Motorină auto",
                "unitate": "1000l",
                "eur": {
                    "cu_taxe": 1210,
                    "fara_taxe": 553.02,
                    "pe_litru_cu_taxe": 1.21,
                    "pe_litru_fara_taxe": 0.553
                },
                "national": null,
                "taxe_din_pret_procent": 54.3,
                "atentionare": null
            }
        ],
        "sursa": {
            "nume": "European Commission — Weekly Oil Bulletin (DG ENER)",
            "licenta": "CC BY 4.0 (Decizia 2011/833/UE)",
            "observatie": "Prețuri medii naționale raportate de statele membre pentru săptămâna indicată, nu prețuri per stație de alimentare."
        }
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareLipsește produs, sau ordine nu e crescator/descrescator.
429cota_depasitaCota lunară a planului a fost depăşită (vezi Retry-After).

Toate erorile au aceeași formă. eroare.cod e stabil și e cel după care trebuie să ramifici în cod — nu după textul din mesaj, care se poate schimba.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "Lipsește produs, sau ordine nu e crescator/descrescator.",
        "detalii": {
            "produs": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}