{ "openapi": "3.1.0", "info": { "title": "FuelAzores public prices and articles", "version": "1.0.0", "description": "FuelAzores is an independent guide to official maximum fuel prices in the Azores and Madeira, including Porto Santo. These are regional caps, not individual station quotes. One approved official source with an exact amount and effective date is sufficient. Conflicting or ambiguous official evidence stays under review. Reports cannot override or block valid official prices. No forecast is presented as an announced change. Petrol 98 is not covered. Amounts use integer thousandths of EUR per litre (priceMillsPerLitre); divide by 1000 for EUR/litre. Effective dates use the region's time zone. A last verified price can be retained while a later period is pending or under review: inspect pendingStatus and freshness before calling it current. generatedAt is retrieval time, not publisher or verification time. Preserve official source links, dates, and the FuelAzores citation URL. Missing data is unknown, never zero. History is paginated and coverage gaps do not imply an unchanged price. Price and history data are published under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); attribute \"FuelAzores (www.fuelazores.com)\". Official source documents remain the works of their publishers.", "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }, "contact": { "name": "FuelAzores", "email": "hello@perf.website", "url": "https://www.fuelazores.com/developers" } }, "servers": [ { "url": "https://www.fuelazores.com" } ], "security": [], "paths": { "/api/v1/prices": { "get": { "operationId": "get_fuel_prices", "summary": "Official fuel prices", "description": "Read the latest verified and confirmed upcoming official maximum fuel prices, effective dates, review/freshness status, and sources. Optionally choose a region and fuel.", "parameters": [ { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "azores", "madeira" ], "description": "Region whose official maximum prices to read." } }, { "name": "fuel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "petrol95", "diesel", "agriculturalDiesel", "fishingDiesel", "marineDiesel", "markedDiesel" ], "description": "Exact regulated fuel category. Specialist fuels are not interchangeable with road diesel." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv", "markdown" ], "default": "json" } } ], "responses": { "200": { "description": "Public data. Inspect freshness, coverage and review state before citing prices.", "content": { "application/json": { "schema": { "type": "object", "required": [ "license" ], "properties": { "license": { "type": "object", "description": "Data license and the attribution to give when reusing the data.", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string", "const": "CC BY 4.0" }, "url": { "type": "string", "format": "uri", "const": "https://creativecommons.org/licenses/by/4.0/" }, "attribution": { "type": "string", "const": "FuelAzores (www.fuelazores.com)" } } } } } }, "text/csv": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid, unsupported, unknown or repeated parameters." }, "404": { "description": "No matching article." }, "429": { "description": "Shared dynamic-route limit: 120 requests/minute/IP per edge region. Honor Retry-After if present; otherwise wait at least 60 seconds. Edge response may be plain text." }, "503": { "description": "Upstream unavailable; retry after 60 seconds. No substitute prices are returned." } } } }, "/api/v1/history": { "get": { "operationId": "get_price_history", "summary": "Fuel price history", "description": "Read a bounded page of verified historical official fuel prices. Follow nextCursor until isDone; gaps mean missing evidence, not unchanged prices.", "parameters": [ { "name": "region", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "azores", "madeira" ], "description": "Region whose official maximum prices to read." } }, { "name": "fuel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "petrol95", "diesel", "agriculturalDiesel", "fishingDiesel", "marineDiesel", "markedDiesel" ], "description": "Exact regulated fuel category. Specialist fuels are not interchangeable with road diesel." } }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv", "markdown" ], "default": "json" } } ], "responses": { "200": { "description": "Public data. Inspect freshness, coverage and review state before citing prices.", "content": { "application/json": { "schema": { "type": "object", "required": [ "license" ], "properties": { "license": { "type": "object", "description": "Data license and the attribution to give when reusing the data.", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string", "const": "CC BY 4.0" }, "url": { "type": "string", "format": "uri", "const": "https://creativecommons.org/licenses/by/4.0/" }, "attribution": { "type": "string", "const": "FuelAzores (www.fuelazores.com)" } } } } } }, "text/csv": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid, unsupported, unknown or repeated parameters." }, "404": { "description": "No matching article." }, "429": { "description": "Shared dynamic-route limit: 120 requests/minute/IP per edge region. Honor Retry-After if present; otherwise wait at least 60 seconds. Edge response may be plain text." }, "503": { "description": "Upstream unavailable; retry after 60 seconds. No substitute prices are returned." } } } }, "/api/v1/articles": { "get": { "operationId": "find_fuel_articles", "summary": "Fuel price guides", "description": "Find Portuguese and English guides to Azores and Madeira fuel prices, official sources, regional comparisons, refill calculations, refuelling as a visitor and using FuelAzores. Use an article id and language to retrieve its complete Markdown. Dated examples are not live prices.", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pt", "en" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 150 } }, { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "azores", "madeira", "comparison", "evidence", "refill", "fuelazores", "travel" ] } } ], "responses": { "200": { "description": "Public data. Inspect freshness, coverage and review state before citing prices.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid, unsupported, unknown or repeated parameters." }, "404": { "description": "No matching article." }, "429": { "description": "Shared dynamic-route limit: 120 requests/minute/IP per edge region. Honor Retry-After if present; otherwise wait at least 60 seconds. Edge response may be plain text." }, "503": { "description": "Upstream unavailable; retry after 60 seconds. No substitute prices are returned." } } } } } }