openapi: 3.0.3
info:
  title: The Gold Barometer
  version: "1"
  description: |
    Free JSON data for The Gold Barometer, a daily 0-100 score of gold buying
    conditions for the US market. The score compares seven measured things with
    their own recorded past, back to 1971 where the record reaches that far.
    No key, no signup, CORS enabled on every endpoint.

    The data is free to reuse under CC BY 4.0 with the credit line
    "Source: The Gold Barometer, thegoldbarometer.com".

    It measures conditions. It is not advice, and it does not predict the price.
  contact:
    name: The Gold Barometer
    url: https://thegoldbarometer.com/data/
    email: hello@thegoldbarometer.com
  license:
    name: CC BY 4.0 (data)
    url: https://creativecommons.org/licenses/by/4.0/
  termsOfService: https://thegoldbarometer.com/terms/
externalDocs:
  description: Human-readable data page, methodology and archive
  url: https://thegoldbarometer.com/data/
servers:
  - url: https://thegoldbarometer.com
paths:
  /data/latest.json:
    get:
      operationId: getLatestReading
      summary: Today's reading
      description: The current score, its zone, and the state of each of the seven parts. Updated once a day after the US market closes.
      responses:
        "200":
          description: The current reading.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Latest"
  /data/history.json:
    get:
      operationId: getHistoryJson
      summary: Published readings, JSON
      description: Every published reading plus reconstructed month-end context rows. Rows with backfilled true are monthly reconstructions, not daily publications.
      responses:
        "200":
          description: Array of readings, oldest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HistoryRow"
  /data/history.csv:
    get:
      operationId: getHistoryCsv
      summary: Published readings, CSV
      description: The same series as history.json, one row per reading. Header is date,score,zone,version,pillars_used,backfilled.
      responses:
        "200":
          description: CSV file, oldest first.
          content:
            text/csv:
              schema:
                type: string
components:
  schemas:
    Latest:
      type: object
      required: [date, score, zone, version]
      properties:
        date:
          type: string
          format: date
          description: Trading day the reading describes.
        score:
          type: integer
          minimum: 0
          maximum: 100
          description: The reading, rounded.
        score_precise:
          type: number
          description: The reading before rounding.
        zone:
          type: string
          enum: ["Historically very unfavorable", "Unfavorable", "Mixed", "Favorable", "Historically very favorable"]
          description: Zone the score falls in. Bands are 0-19, 20-39, 40-59, 60-79, 80-100.
        version:
          type: string
          description: Methodology version.
        engine_build:
          type: string
          description: Build date of the engine that computed this reading.
        api_version:
          type: integer
        pillars_used:
          type: integer
          description: How many of the seven parts had usable data.
        pillars_total:
          type: integer
        weights_nominal:
          type: object
          additionalProperties:
            type: number
          description: Design weight of each part, in points.
        weights_effective:
          type: object
          additionalProperties:
            type: number
          description: Weight actually applied after unavailable parts are dropped.
        pillars:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Pillar"
          description: State of each part, keyed by part name.
        computed_at_utc:
          type: string
      additionalProperties: true
    Pillar:
      type: object
      required: [name, available]
      properties:
        name:
          type: string
        available:
          type: boolean
          description: False when the part had no usable data and was dropped for the day.
        subscore:
          type: number
          description: The part's own 0-100 reading. Absent when unavailable.
        latest_date:
          type: string
          format: date
          description: Date of the newest source figure.
        latest_value:
          type: number
          nullable: true
          description: The newest raw figure, when the source licence allows publishing it.
        unit:
          type: string
        source:
          type: string
        frequency:
          type: string
        staleness_days:
          type: integer
        stale_limit_days:
          type: integer
        history_points:
          type: integer
        publishable_raw:
          type: boolean
        weight_nominal:
          type: number
        weight_effective:
          type: number
        staleness_flag:
          type: string
      additionalProperties: true
    HistoryRow:
      type: object
      required: [date, score, zone]
      properties:
        date:
          type: string
          format: date
        score:
          type: integer
          minimum: 0
          maximum: 100
        zone:
          type: string
        version:
          type: string
        pillars_used:
          type: integer
        backfilled:
          type: boolean
          description: True for reconstructed month-end context rows, false for readings published the day they happened.
      additionalProperties: true