{"openapi":"3.1.0","info":{"title":"Datamag Public Comparison API","version":"1.0.0","description":"Published Romanian residential energy comparisons. Costs include VAT; fixed charges are annualized over 365 days. Preserve Datamag and original-source attribution. No accounts, API keys or bulk access.","contact":{"email":"office@datamag.ro"}},"servers":[{"url":"https://datamag.ro"}],"paths":{"/api/v1/locations":{"get":{"operationId":"resolve_location","summary":"Resolve a Romanian comparison location","description":"Anonymous residential comparison access. Limit 120 requests per caller per minute. Query strings at most 2048 bytes. No pagination, bulk export or arbitrary sorting. Duplicate and unknown parameters are rejected.","parameters":[{"name":"commodity","in":"query","required":true,"schema":{"type":"string","enum":["electricity","gas"]}},{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"county","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Success. Missing evidence is null; no comparable offers is a valid empty list.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"commodity":{"type":"string","enum":["electricity","gas"]},"locations":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"locationKey":{"type":"string","minLength":1,"maxLength":250},"commodity":{"type":"string","enum":["electricity","gas"]},"county":{"type":"string"},"regionKey":{"type":"string"},"locality":{"type":["string","null"]},"siruta":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"comparisonUrl":{"type":"string","format":"uri"}},"required":["locationKey","commodity","county","regionKey","locality","siruta","comparisonUrl"],"additionalProperties":false}},"refinementNeeded":{"type":"boolean"},"clarification":{"type":["string","null"]}},"required":["commodity","locations","refinementNeeded","clarification"],"additionalProperties":false}}}},"400":{"description":"Invalid, missing, duplicate, unknown or oversized parameters.","headers":{},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Caller limit exceeded. Respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until retry."}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"Published data or enforcement temporarily unavailable.","headers":{},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/compare":{"get":{"operationId":"compare_offers","summary":"Compare up to five eligible offers","description":"Anonymous residential comparison access. Limit 30 requests per caller per minute. Query strings at most 2048 bytes. No pagination, bulk export or arbitrary sorting. Duplicate and unknown parameters are rejected.","parameters":[{"name":"commodity","in":"query","required":true,"schema":{"type":"string","enum":["electricity","gas"]}},{"name":"locationKey","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":250}},{"name":"annualConsumptionKwh","in":"query","required":true,"schema":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"multipleOf":0.001}}],"responses":{"200":{"description":"Success. Missing evidence is null; no comparable offers is a valid empty list.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"provider":{"type":"string","const":"Datamag"},"commodity":{"type":"string","enum":["electricity","gas"]},"location":{"type":"object","properties":{"locationKey":{"type":"string","minLength":1,"maxLength":250},"commodity":{"type":"string","enum":["electricity","gas"]},"county":{"type":"string"},"regionKey":{"type":"string"},"locality":{"type":["string","null"]},"siruta":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"comparisonUrl":{"type":"string","format":"uri"}},"required":["locationKey","commodity","county","regionKey","locality","siruta","comparisonUrl"],"additionalProperties":false},"annualConsumptionKwh":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"multipleOf":0.001},"currency":{"type":"string","const":"RON"},"vatTreatment":{"type":"string","const":"included"},"units":{"type":"object","properties":{"consumption":{"type":"string","const":"kWh/year"},"variableUnitPrice":{"type":"string","const":"RON/kWh"},"fixedDailyCharge":{"type":"string","const":"RON/day"},"annualCost":{"type":"string","const":"RON/year"},"monthlyCost":{"type":"string","const":"RON/month"}},"required":["consumption","variableUnitPrice","fixedDailyCharge","annualCost","monthlyCost"],"additionalProperties":false},"calculatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"comparableOfferCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"methodologyUrl":{"type":"string","format":"uri"},"comparisonUrl":{"type":"string","format":"uri"},"offers":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"offerSlug":{"type":"string"},"offerCode":{"type":["string","null"]},"offerName":{"type":"string"},"supplierSlug":{"type":["string","null"]},"supplierName":{"type":"string"},"estimatedAnnualCost":{"type":"number","minimum":0},"estimatedMonthlyCost":{"type":"number","minimum":0},"variableUnitPrice":{"type":"number"},"fixedDailyCharge":{"type":["number","null"]},"priceType":{"type":"string","enum":["fixed","variable","hybrid","maximum","unknown"]},"validFrom":{"type":"string"},"validTo":{"type":["string","null"]},"contractTerm":{"type":["string","null"]},"conditions":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"sourceFreshnessAt":{"type":["string","null"]},"offerUrl":{"type":"string","format":"uri"}},"required":["offerSlug","offerCode","offerName","supplierSlug","supplierName","estimatedAnnualCost","estimatedMonthlyCost","variableUnitPrice","fixedDailyCharge","priceType","validFrom","validTo","contractTerm","conditions","sourceUrl","sourceFreshnessAt","offerUrl"],"additionalProperties":false}}},"required":["provider","commodity","location","annualConsumptionKwh","currency","vatTreatment","units","calculatedAt","comparableOfferCount","methodologyUrl","comparisonUrl","offers"],"additionalProperties":false}}}},"400":{"description":"Invalid, missing, duplicate, unknown or oversized parameters.","headers":{},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Caller limit exceeded. Respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until retry."}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"Published data or enforcement temporarily unavailable.","headers":{},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/api/offer-alerts/baseline":{"get":{"operationId":"alert_baseline","summary":"Get the standard guide-alert baseline","description":"Anonymous residential comparison access. Limit 30 requests per caller per minute. Query strings at most 2048 bytes. No pagination, bulk export or arbitrary sorting. Duplicate and unknown parameters are rejected.","parameters":[{"name":"commodity","in":"query","required":true,"schema":{"type":"string","enum":["electricity","gas"]}},{"name":"locationKey","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":250}}],"responses":{"200":{"description":"Success. Missing evidence is null; no comparable offers is a valid empty list.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"baseline":{"anyOf":[{"type":"object","properties":{"targetPriceBaniPerKwh":{"type":"number","exclusiveMinimum":0},"comparisonAnnualCostLei":{"type":"number","exclusiveMinimum":0},"comparisonUnitPriceBaniPerKwh":{"type":"number","exclusiveMinimum":0},"comparisonFixedDailyLei":{"type":"number","minimum":0}},"required":["targetPriceBaniPerKwh","comparisonAnnualCostLei","comparisonUnitPriceBaniPerKwh","comparisonFixedDailyLei"],"additionalProperties":false},{"type":"null"}]}},"required":["baseline"],"additionalProperties":false}}}},"400":{"description":"Invalid, missing, duplicate, unknown or oversized parameters.","headers":{},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Caller limit exceeded. Respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until retry."}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"Published data or enforcement temporarily unavailable.","headers":{},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}}}}}}}