openapi: 3.1.0
info:
  title: returnsview data API
  description: |
    Free, keyless, read-only market history. Returns and price data for
    cryptocurrencies, stocks, ETFs and world indices, precomputed into static
    JSON — daily, weekly, monthly and quarterly returns plus seasonality and
    drawdown statistics.

    Coverage reaches back to 1927 for equities and 2010 for crypto.

    There is no rate limit and no key. These are static files on a CDN, so the
    practical guidance is simply to cache: the data changes once a day, after
    the UTC close, and `meta.json` tells you when it was last built.

    Attribution is requested rather than enforced — a link back to
    returnsview.com if you publish something built on this.
  version: "1.0.0"
  contact:
    name: returnsview
    url: https://returnsview.com/contact/
  license:
    name: Terms of use
    url: https://returnsview.com/terms/
servers:
  - url: https://returnsview.com
    description: Production
tags:
  - name: crypto
  - name: stocks
  - name: site
paths:
  /data/meta.json:
    get:
      tags: [site]
      summary: Build metadata
      description: When the export was last generated, and how many coins it covers. Poll this to decide whether to refetch anything else.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated_at: { type: string, format: date-time }
                  coins: { type: integer }
  /data/coins.json:
    get:
      tags: [crypto]
      summary: All tracked coins
      description: One row per coin with market cap, latest close and trailing returns. Trailing returns are null when the feed is stale or the latest close failed a data-quality check.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/CoinIndexRow" }
  /data/coins/{cg_id}.json:
    get:
      tags: [crypto]
      summary: Full history for one coin
      description: Monthly, quarterly, weekly and daily return matrices, seasonality, risk statistics and summary stats.
      parameters:
        - name: cg_id
          in: path
          required: true
          description: CoinGecko id, as published in coins.json
          schema: { type: string }
          example: bitcoin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AssetPayload" }
        "404": { description: Unknown coin }
  /data/stocks.json:
    get:
      tags: [stocks]
      summary: All tracked stocks, ETFs and indices
      description: One row per instrument. Index membership flags (sp500, ndx, ftse100 …) mark which lists it belongs to; `benchmark` marks a world index, `commodities` a futures series.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/StockIndexRow" }
  /data/stocks/{ticker}.json:
    get:
      tags: [stocks]
      summary: Full history for one instrument
      description: Same shape as the coin payload. Prices are split- and dividend-adjusted.
      parameters:
        - name: ticker
          in: path
          required: true
          description: URL-safe slug from stocks.json — dots become dashes (BRK-B, AZN-L)
          schema: { type: string }
          example: AAPL
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AssetPayload" }
        "404": { description: Unknown ticker }
  /data/recaps.json:
    get:
      tags: [site]
      summary: Monthly market recaps
      description: Per-month breadth, index moves, biggest movers and a written recap for every month on record.
      responses:
        "200": { description: OK }
  /data/cycles.json:
    get:
      tags: [crypto]
      summary: Bitcoin halving-cycle series
      responses:
        "200": { description: OK }
  /data/news.json:
    get:
      tags: [site]
      summary: Latest crypto and markets headlines
      responses:
        "200": { description: OK }
components:
  schemas:
    CoinIndexRow:
      type: object
      properties:
        cg_id: { type: string, example: bitcoin }
        symbol: { type: string, example: BTC }
        name: { type: string, example: Bitcoin }
        rank: { type: integer }
        market_cap: { type: number, description: USD }
        category: { type: [string, "null"] }
        last_close: { type: [number, "null"], description: Latest settled UTC daily close }
        last_day: { type: string, format: date }
        ret_24h: { type: [number, "null"], description: Percent }
        ret_7d: { type: [number, "null"] }
        ret_30d: { type: [number, "null"] }
        ret_ytd: { type: [number, "null"] }
        ret_1y: { type: [number, "null"] }
        history_start: { type: string, format: date }
    StockIndexRow:
      type: object
      properties:
        ticker: { type: string, example: AAPL }
        name: { type: string }
        sector: { type: [string, "null"] }
        currency: { type: string, description: "Quote symbol. £ means the raw value is in pence." }
        benchmark: { type: boolean }
        market_cap: { type: [number, "null"], description: USD }
        last_close: { type: [number, "null"] }
        last_day: { type: string, format: date }
        ret_24h: { type: [number, "null"] }
        ret_7d: { type: [number, "null"] }
        ret_30d: { type: [number, "null"] }
        ret_ytd: { type: [number, "null"] }
        ret_1y: { type: [number, "null"] }
        history_start: { type: string, format: date }
    AssetPayload:
      type: object
      description: Return matrices keyed by year; each row holds 12 monthly, 4 quarterly or 52 weekly values, with null where no data exists.
      properties:
        monthly:
          type: object
          additionalProperties:
            type: array
            items: { type: [number, "null"] }
        monthly_partial:
          type: object
          description: Marks the first and in-progress periods so consumers can grey them. A completed month yields [0,0].
        quarterly:
          type: object
          additionalProperties:
            type: array
            items: { type: [number, "null"] }
        weekly_matrix:
          type: object
          additionalProperties:
            type: array
            items: { type: [number, "null"] }
        daily:
          type: array
          items:
            type: object
            properties:
              day: { type: string, format: date }
              ret: { type: number }
        seasonality:
          type: object
          description: Average return per calendar month, keyed 1-12.
        stats:
          type: object
          properties:
            ret_24h: { type: [number, "null"] }
            ret_7d: { type: [number, "null"] }
            ret_30d: { type: [number, "null"] }
            ret_ytd: { type: [number, "null"] }
            ret_1y: { type: [number, "null"] }
            last_close: { type: [number, "null"] }
            last_day: { type: string, format: date }
            history_start: { type: string, format: date }
            best_month: { type: [object, "null"] }
            worst_month: { type: [object, "null"] }
            risk:
              type: object
              properties:
                max_drawdown: { type: [number, "null"] }
                vol_m: { type: [number, "null"] }
                pos_month_pct: { type: [number, "null"] }