oneapi
Autentificare
Carburanti v1 / Carburanti

Seria unui produs

Istoricul preţului unui carburant din 2005 încoace, săptămână cu săptămână, pentru o ţară sau pentru mai multe deodată.

GET
https://oneapi.ro/api/carburanti/v1/preturi/serie

Parametri de interogare

NumeTipDescriereValori acceptate
taraopțional string | null Codul de țară. Implicit RO. Nu se combină cu tari. ATBEBGCYCZDEDKEEESFIFRGRHRHUIEITLTLULVMTNLPLPTROSESISKUKEUEA
tariopțional string | null Mai multe țări, separate prin virgulă, cel mult 10. Cu exact două apare și diferenta. max 60 car.
granularitateopțional string | null saptamana (implicit), luna ori an: media cotațiilor săptămânale pe perioadă. saptamanalunaan
produsobligatoriu string Codul produsului. Obligatoriu — o serie „a tuturor produselor" ar fi patru serii amestecate. benzina95motorinamotorina_incalzirepacura_sulf_micpacura_sulf_maregpl
de_laopțional string | null Prima săptămână inclusă, AAAA-LL-ZZ. ex. 2020-01-01
pana_laopțional string | null Ultima săptămână inclusă, AAAA-LL-ZZ. ex. 2026-08-31
limitaopțional integer | null Câte săptămâni ori perioade să întoarcă pe țară, maximum 1200. Implicit 260 de săptămâni, 60 de luni ori 20 de ani. 1 – 1200

Cum se comportă

  • Seria săptămânală are goluri, şi sunt ale sursei. Din 1.082 de săptămâni publicate între 2005 şi azi, 37 de intervale sar peste o săptămână sau două: 17 se reiau în ianuarie şi 15 în aprilie — Comisia nu publică buletinul în săptămânile de Crăciun şi de Paşte. Nu sunt importuri ratate. Dacă desenezi un grafic săptămânal, aşteaptă-te la pauze şi nu le umple prin interpolare: n-a existat o cotaţie în săptămânile alea.
  • 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.
  • Ordinea e descrescătoare după dată — cea mai recentă săptămână prima. Cu limita mic, primești deci capătul recent al seriei, nu începutul ei.
  • Seria completă a unui produs are peste 1.100 de săptămâni. Implicit se întorc 260 (aproximativ cinci ani); maximul e 1.200, adică toată seria.
  • România intră în serie din 2008-01-07; alte țări au serii care încep în 2005. Marea Britanie e prezentă până la 2020-12-21 și apoi se oprește.
  • Fiecare element are aceeași formă ca un produs din /preturi, inclusiv blocurile eur și national.
  • Media pe lună ori pe an (granularitate=luna|an) e media simplă a cotațiilor săptămânale din perioadă, pe fiecare bloc separat. Elementul poartă atunci perioada în locul lui data, plus saptamani și partiala. limita numără perioadele: implicit 60 de luni ori 20 de ani.
  • La medie, blocul national apare doar când toată perioada e în aceeași monedă: în anul trecerii unei țări la euro (Bulgaria, 2026) e null, fiindcă o medie între leva și euro n-ar fi un preț. Blocul eur e mereu comparabil.
  • Mai multe țări pe aceeași axă: tari=RO,BG (cel mult 10) în locul lui tara. Rândurile au fiecare tara, ordonate după dată, apoi după țară; limita se aplică pe fiecare țară. Cu exact două țări, diferenta dă direct evoluția diferenței dintre ele.

La ce folosește

  • Trasezi evoluția prețului motorinei pe cinci ani, ca să justifici o renegociere de tarif de transport.
  • Calculezi o medie pe trimestru pentru o raportare de costuri, pornind de la cifre publice.
  • Alimentezi un grafic dintr-un dashboard intern fără să scrapezi nimic.

Structura răspunsului

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

CâmpTipDescriere
tara string Țara pentru care e seria, la tara.
tari string[] Țările, la tari.
produs string Produsul.
granularitate string saptamana | luna | an.
inregistrari integer Câte rânduri conține răspunsul.
serie[] object Aceeași structură ca un element din data.produse[] la GET /preturi; la medie, cu perioada, saptamani, partiala.
diferenta[] object[] Doar cu exact două țări în tari: diferența dintre prima și a doua, pe fiecare săptămână ori perioadă în care au publicat amândouă.
sursa object Sursa și licența.
serie[].tara string Codul țării.
serie[].data string Săptămâna la care se referă prețul (luni-ul buletinului); doar la granularitatea saptamana.
serie[].perioada string Luna (AAAA-LL) ori anul (AAAA) mediei; doar la luna și an.
serie[].saptamani integer Pe câte cotații săptămânale s-a făcut media; doar la luna și an.
serie[].partiala boolean true când perioada iese din săptămânile aduse — luna în curs, începutul seriei ori o margine tăiată de de_la/pana_la. O medie parțială nu e media lunii ori a anului.
serie[].produs string Codul produsului.
serie[].denumire string Denumirea produsului.
serie[].unitate string Unitatea în care e cotat produsul: 1.000 de litri la carburanți, 1.000 kg la păcură.
serie[].eur.cu_taxe number Prețul în euro, cu toate taxele incluse, pe unitatea de cotare.
serie[].eur.fara_taxe number Prețul în euro, fără taxe.
serie[].eur.pe_litru_cu_taxe number Același preț adus la litru — null la produsele cotate pe tonă.
serie[].eur.pe_litru_fara_taxe number Prețul fără taxe, pe litru.
serie[].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.
serie[].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.
serie[].national.cu_taxe number Prețul în moneda națională, cu taxe.
serie[].national.fara_taxe number Prețul în moneda națională, fără taxe.
serie[].national.pe_litru_cu_taxe number Prețul național pe litru, cu taxe.
serie[].national.pe_litru_fara_taxe number Prețul național pe litru, fără taxe.
serie[].taxe_din_pret_procent number Cât la sută din prețul final sunt taxe — cifra cea mai citată dintr-un buletin.
diferenta[].perioada string Săptămâna, luna ori anul.
diferenta[].eur_cu_taxe number Prima țară minus a doua, în euro cu taxe, pe unitatea de cotare.
diferenta[].procent number Aceeași diferență, ca procent din prețul celei de-a doua țări.

Exemple de răspuns

GEThttps://oneapi.ro/api/carburanti/v1/preturi/serie?produs=motorina&limita=52
{
    "data": {
        "tara": "RO",
        "produs": "motorina",
        "granularitate": "saptamana",
        "inregistrari": 52,
        "serie": [
            {
                "tara": "RO",
                "data": "2026-09-14",
                "produs": "motorina",
                "denumire": "Motorină auto",
                "unitate": "1000l",
                "eur": {
                    "cu_taxe": 1999.6937,
                    "fara_taxe": 1252.5434,
                    "pe_litru_cu_taxe": 1.9997,
                    "pe_litru_fara_taxe": 1.2525
                },
                "national": {
                    "moneda": "RON",
                    "curs_eur_pe_unitate": 0.1902297976,
                    "cu_taxe": 10511.99,
                    "fara_taxe": 6584.37,
                    "pe_litru_cu_taxe": 10.512,
                    "pe_litru_fara_taxe": 6.5844
                },
                "taxe_din_pret_procent": 37.36,
                "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, limita depășește 1200, tari are un cod necunoscut ori peste 10 țări, tara e combinat cu tari ori granularitate nu e saptamana/luna/an.
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, limita depășește 1200, tari are un cod necunoscut ori peste 10 țări, tara e combinat cu tari ori granularitate nu e saptamana/luna/an.",
        "detalii": {
            "tara": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}