API public Datamag

Compară ofertele publicate de energie electrică și gaze naturale pentru clienți casnici din România. Accesul este anonim, fără cont sau cheie API.

Contract OpenAPI · Metodologie · llms.txt

Locația și consumul

Folosește GET /api/v1/locations cu commodity=electricity sau gas și q de minimum două caractere. Poți restrânge căutarea prin county. Primești cel mult zece locații. Cere clarificări când refinementNeeded este adevărat; nu alege automat dintre rezultate ambigue.

GET /api/v1/locations?commodity=gas&q=Cluj-Napoca
GET /api/v1/compare?commodity=gas&locationKey=<returned-key>&annualConsumptionKwh=7200

GET /api/v1/compare necesită commodity, locationKey și annualConsumptionKwh. Consumul trebuie să fie pozitiv, finit, cel mult 1.000.000 kWh/an, cu maximum trei zecimale. Limita este tehnică, nu o estimare a consumului unei locuințe. Nu există valori implicite.

Parametrii necunoscuți, lipsă sau repetați sunt respinși. Șirul de interogare are limita de 2 KiB, identificatorii 250 de caractere, iar numele de locuri 100. Nu oferim paginare, sortare arbitrară sau export în masă.

Costuri, surse și valabilitate

Răspunsul include cel mult cinci oferte, ordonate după costul anual estimat. Sumele sunt în RON, cu TVA inclus. Prețul variabil este în RON/kWh, taxa fixă în RON/zi, anualizată la 365 de zile. Costul lunar este media costului anual.

Fiecare ofertă include sursa și data ei, când sunt disponibile. Valorile necunoscute sunt null. Data calculului nu este data verificării sursei. Valabilitatea se aplică după calendarul Europe/Bucharest. Păstrează atribuirea către sursa originală și identifică Datamag drept furnizorul comparației, cu legături către ofertă și rezultate.

Limite și erori

Comparațiile REST și MCP împart limita de 30 de cereri pe minut pentru un apelant. Căutările de locații au limita de 120/minut. MCP are suplimentar 120 de cereri de transport/minut. Adresele de ieșire comune ale platformelor AI împart limitele. Numele clientului și user-agent nu oferă excepții.

200 poate conține o listă goală validă. 400 înseamnă parametri invalizi, 429 limită depășită, cu Retry-After în secunde, iar 503 indisponibilitate temporară. Comparațiile și erorile sunt no-store; locațiile pot fi memorate privat cinci minute. CORS fără credențiale este permis pentru citirile REST.

Formularele proprii folosesc GET /api/offer-alerts/baseline, cu commodity și locationKey. Consumul de referință este stabilit pe server. Vechile API-uri /api/electricity/search, /api/gas/search și /api/offers/[slug] răspund 410 Gone.

Conectare prin MCP

Adresa serviciului este https://datamag.ro/mcp, cu Streamable HTTP și acces fără autentificare. Adaugă această adresă ca server MCP personalizat în ChatGPT sau Claude. Instrumentele disponibile sunt resolve_location și compare_offers. Cere consumul anual înaintea comparației. Serviciul nu creează alerte, nu trimite solicitări către furnizori și nu schimbă contracte.

Corpul JSON are limita de 32 KiB. Sunt acceptate cereri fără Origin de la servere; un Origin prezent trebuie să fie permis de configurația Datamag. Nu sunt necesare sesiuni persistente, OAuth sau widgeturi. Disponibilitatea în directoarele platformelor se stabilește separat de conectarea unui server personalizat.

Contact: office@datamag.ro.