{
  "openapi": "3.1.0",
  "info": {
    "title": "wagepriceindex.com public API",
    "version": "1.0.0",
    "description": "Australia's Wage Price Index (WPI) and Consumer Price Index (CPI), computed and cited. Free, no keys, open CORS. The front door is /calculate: it returns this site's computed figures with the method, full ABS citations, and a cite_url reproducing the identical result on the human calculator page. Raw published series JSON is available for research-shaped use. Data © Australian Bureau of Statistics, CC BY 4.0; wagepriceindex.com is an independent tool, not affiliated with or endorsed by the ABS.",
    "contact": { "url": "https://wagepriceindex.com/api/" },
    "license": { "name": "CC BY 4.0 (data)", "url": "https://creativecommons.org/licenses/by/4.0/" }
  },
  "servers": [{ "url": "https://wagepriceindex.com/api/v1" }],
  "paths": {
    "/calculate": {
      "get": {
        "operationId": "calculate",
        "summary": "Grow a wage between two quarters with the WPI, and compare against the CPI",
        "description": "Two-point index ratios on the latest published vintages: grown_value = wage × index[to] ÷ index[from] per flow, real = wpi_factor ÷ cpi_factor − 1. Quarter boundaries only, no interpolation. from later than to is allowed (the ratio runs backwards). Deterministic per vintage; responses are edge-cached.",
        "parameters": [
          { "name": "wage", "in": "query", "required": true, "schema": { "type": "number", "exclusiveMinimum": 0 }, "description": "Annual wage in AUD, e.g. 70000. $ and , are tolerated." },
          { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-Q[1-4]$" }, "description": "Starting calendar quarter, e.g. 2022-Q2 (the June quarter of 2022)." },
          { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-Q[1-4]$" }, "description": "Ending calendar quarter, e.g. 2026-Q1." },
          { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional state/industry/sector slug (see /scopes), e.g. queensland or construction. Scopes the WPI series; the CPI comparison stays national. State and industry series are original (not seasonally adjusted) — the response's method.constraints say so when it applies." }
        ],
        "responses": {
          "200": {
            "description": "Computed figures with method, ABS citations, cite_url, licence and disclaimer.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculateResponse" } } }
          },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/scopes": {
      "get": {
        "operationId": "listScopes",
        "summary": "Valid calculate scopes (slug → ABS series)",
        "responses": { "200": { "description": "8 states/territories, 18 industries, 2 sectors, each with its ABS series key, seasonal-adjustment status, raw series URL and entity page." } }
      }
    },
    "/latest": {
      "get": {
        "operationId": "latestVintages",
        "summary": "Which release vintage each flow is currently serving",
        "responses": { "200": { "description": "Per-flow vintage, coverage end and update time." } }
      }
    },
    "/catalog/{flow}": {
      "get": {
        "operationId": "catalog",
        "summary": "Every published series in a flow (latest vintage)",
        "parameters": [{ "name": "flow", "in": "path", "required": true, "schema": { "type": "string", "enum": ["wpi", "cpi"] } }],
        "responses": { "200": { "description": "Series directory: key, label, coverage, ABS table/series id where joined." }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/series/{flow}/{vintage}/{key}.json": {
      "get": {
        "operationId": "series",
        "summary": "Raw published series JSON (observations + full ABS provenance)",
        "description": "vintage is a release like mar-2026 (immutable path) or 'latest' (follows the current pointer). Keys are SDMX keys — find them in /catalog/{flow} or /scopes.",
        "parameters": [
          { "name": "flow", "in": "path", "required": true, "schema": { "type": "string", "enum": ["wpi", "cpi"] } },
          { "name": "vintage", "in": "path", "required": true, "schema": { "type": "string" }, "description": "'latest' or e.g. mar-2026" },
          { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SDMX series key, e.g. 1.THRPEB.7.TOT.20.AUS.Q" }
        ],
        "responses": { "200": { "description": "label, dims, observations ([quarter, index] pairs), provenance (catalogue, release_url, table, abs_series_id, spreadsheet_url, api_url), license." }, "404": { "$ref": "#/components/responses/Error" } }
      }
    }
  },
  "components": {
    "responses": {
      "Error": {
        "description": "Machine-readable error",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "docs": { "type": "string" } } } } } } }
      }
    },
    "schemas": {
      "CalculateResponse": {
        "type": "object",
        "properties": {
          "inputs": { "type": "object", "description": "Echo of wage/from/to/scope plus the resolved scope name." },
          "result": {
            "type": "object",
            "properties": {
              "wpi": { "type": "object", "properties": { "grown_value": { "type": "integer", "description": "Wage grown with the WPI, whole AUD — matches the calculator page." }, "growth_pct": { "type": "number" }, "factor": { "type": "number", "description": "Unrounded index ratio." } } },
              "cpi": { "type": "object", "description": "Same shape; what delivers the same buying power at the destination quarter." },
              "real": { "type": "object", "properties": { "growth_pct": { "type": "number", "description": "WPI relative to CPI over the period." } } },
              "backwards": { "type": "boolean" },
              "summary": { "type": "string", "description": "Self-contained quotable sentence with the key figures and periods." }
            }
          },
          "method": { "type": "object", "properties": { "formula": { "type": "string" }, "constraints": { "type": "array", "items": { "type": "string" } } } },
          "citations": { "type": "array", "description": "One per series used (WPI, CPI): key, label, vintage, the two observations used, and full ABS provenance links.", "items": { "type": "object" } },
          "cite_url": { "type": "string", "description": "Stable share URL reproducing the identical result on the human calculator page. Cite this." },
          "license": { "type": "object" },
          "disclaimer": { "type": "string" }
        }
      }
    }
  }
}