One indicator as a clean time series

Endpoint#

GET /api/series/{series_id}

One row per period, oldest first, with previous_value. origin=archive is a release we watched appear (release_date, revised); origin=backfill is older history from the published CSVs (provenance). Where both exist and disagree, both values are published (archive_value, backfill_value) and backfill_disagrees is true; a monthly or policy release keeps the archive, a daily quote takes the publisher-dated backfill, and an archive monthly row first seen before its month ended is rejected (archive_rejected). The tier history window bounds the earliest period (x-api-tiers): Pro reads the full series, e.g. CPI YoY from 2008-01. Over the tier row ceiling the newest rows are kept and truncated is true.

Authentication#

[]

An empty security requirement means this operation does not declare authentication. Read operation notes for entitlement and protocol-method requirements.

Parameters#

Name	In	Required	Description
series_id	path	Yes	From /api/series, e.g. cpi-yoy.
from	query	No	Earliest reference period, YYYY-MM or YYYY-MM-DD.
to	query	No	Latest reference period, inclusive.
format	query	No	CSV returns the same observations as UTF-8 with BOM.

Responses and errors#

HTTP status	Meaning
200	The series.
400	Invalid series_id, period or format.
404	Unknown series, or no observations in the caller history window.
429	Rate limit exceeded.
503	Archive unavailable; retry later.

Response examples#

No response example is supplied by OpenAPI for this operation. The complete response schemas are preserved below; use an actual response for observed values.

Retry guidance#

See errors and retries. Honor operation-specific response headers. A POST may create state; do not replay it automatically.

Complete operation contract#

The expanded contract below includes all parameter constraints, response headers, schemas and examples from OpenAPI.

{
  "path": "/api/series/{series_id}",
  "method": "GET",
  "parameters": [
    {
      "name": "series_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
      },
      "description": "From /api/series, e.g. cpi-yoy."
    },
    {
      "name": "from",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
      },
      "description": "Earliest reference period, YYYY-MM or YYYY-MM-DD."
    },
    {
      "name": "to",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
      },
      "description": "Latest reference period, inclusive."
    },
    {
      "name": "format",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "csv"
        ],
        "default": "json"
      },
      "description": "CSV returns the same observations as UTF-8 with BOM."
    }
  ],
  "operationId": "getSeries",
  "summary": "One indicator as a clean time series",
  "description": "One row per period, oldest first, with previous_value. origin=archive is a release we watched appear (release_date, revised); origin=backfill is older history from the published CSVs (provenance). Where both exist and disagree, both values are published (archive_value, backfill_value) and backfill_disagrees is true; a monthly or policy release keeps the archive, a daily quote takes the publisher-dated backfill, and an archive monthly row first seen before its month ended is rejected (archive_rejected). The tier history window bounds the earliest period (x-api-tiers): Pro reads the full series, e.g. CPI YoY from 2008-01. Over the tier row ceiling the newest rows are kept and truncated is true.",
  "tags": [
    "data",
    "Inspect observations",
    "Export"
  ],
  "security": [],
  "responses": {
    "200": {
      "description": "The series.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "series_id",
              "observations",
              "truncated"
            ]
          }
        },
        "text/csv": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "400": {
      "description": "Invalid series_id, period or format."
    },
    "404": {
      "description": "Unknown series, or no observations in the caller history window."
    },
    "429": {
      "description": "Rate limit exceeded."
    },
    "503": {
      "description": "Archive unavailable; retry later."
    }
  },
  "x-codeSamples": [
    {
      "lang": "curl",
      "label": "curl",
      "source": "curl -s 'https://china-snapshot.com/api/series/pmi-manufacturing'"
    },
    {
      "lang": "curl",
      "label": "curl",
      "source": "curl -s -o pmi.csv 'https://china-snapshot.com/api/series/pmi-manufacturing?from=2025-01&format=csv'"
    }
  ]
}