# dataseries.org

> Open Swiss economic data — SNB, SECO, KOF, FSO and more — unified, charted and downloadable in one place.

Base URL: https://dataseries.org

## How to read a series

Every dataset has a crawlable page with the recent numbers inline, a chart, and a ready CSV link:
  https://dataseries.org/d/<dataset_id>

Compare or pick specific series with query params (comma-separated level codes of the split dimension):
  https://dataseries.org/d/<dataset_id>?series=<codeA>,<codeB>

Raw data (no page) as tidy CSV or JSON. Optional from=/to= bound the dates
(YYYY-MM-DD, inclusive); the ONLY other accepted params are dataset and dims,
and any other name is a 400, so a wrong guess corrects itself:
  https://dataseries.org/series.csv?dataset=<dataset_id>&dims=<dim>=<codeA>,<codeB>&from=<date>&to=<date>
  https://dataseries.org/series?dataset=<dataset_id>&dims=<dim>=<codeA>,<codeB>&from=<date>&to=<date>

A COMPLETE, working example — real dataset, real dimensions, real codes:
  https://dataseries.org/series.csv?dataset=ch_seco_gdp&dims=type=real;structure=gdp;seas_adj=cssa
  (Swiss GDP, chain-linked volumes, seasonally/calendar/sports-event adjusted.)
  Change seas_adj to na (raw), csa (seasonal+calendar) or nasa (sports-event only).

Get the codes for any dataset from https://dataseries.org/dataset/<dataset_id>/meta — the
`dimensions` object lists every dimension and every level code within it. Do NOT
guess codes from the labels on the page; they are short forms like `nasa` and
`cssa` that you cannot derive. A wrong code or dimension name now returns 400
with the valid ones listed, so read the error rather than trying variations.
`;` separates dimensions and `=` binds a code to one; `:` also works if that is
easier to write (dims=structure:gdp is the same as dims=structure=gdp).

Natural-language lookup (returns the best dataset + ready URLs as JSON):
  https://dataseries.org/resolve?q=<your question>
  The reply also carries `matched` and `unmatched`: the words of your query we
  did and did not recognise, plus a one-line `note` when they differ. CHECK
  `unmatched` BEFORE trusting the results — "youth unemployment" answers on
  `unemployment` alone and reports `youth` as unmatched, which means we hold no
  youth breakdown, NOT that the results are about youth. Common words are
  ignored and appear in neither list.

A branded chart image you can embed directly (best for chat/markdown answers):
  ![chart](https://dataseries.org/chart.png?dataset=<dataset_id>)

For a web page, embed the LIVE interactive chart as an iframe (append &embed=1):
  <iframe src="https://dataseries.org/d/<dataset_id>?embed=1" width="680" height="680" style="border:0"></iframe>
  (oEmbed-aware platforms auto-embed a pasted /d/<id> link: https://dataseries.org/oembed?url=<page_url>)

Embed options:
  Theme: the embed follows the viewer's prefers-color-scheme by default. Add
    &theme=dark or &theme=light to pin it. To drive it from a page whose own
    dark mode the visitor can toggle, LEAVE theme OFF the URL (an explicit
    theme wins over everything) and use the message handshake: the embed posts
    {type:"dataseries:ready"} to its parent when it can be themed, and applies
    {type:"dataseries:theme", theme:"dark"|"light"} sent back to it.
  Height: the frame's ideal height depends on its width (680 suits 580px+,
    ~744 at 420px, ~784 at 330px). The embed posts
    {type:"dataseries:height", height:<px>} to its parent on load and whenever
    it changes, so a host that listens can size the frame exactly.

## Client libraries

For code, prefer these over building URLs by hand — same interface in both:

R (CRAN):
  install.packages("dataseries")
  library(dataseries)
  ds("ch_fso_cpi", item = "100_100")           # one series, as a data.frame
  ds("ch_fso_cpi", item = "100_100", from = "2020-01-01")
  ds_search("unemployment")                    # find a series across datasets

Python (PyPI):
  pip install dataseries
  import dataseries
  dataseries.ds("ch_fso_cpi", item="100_100")  # one series, as a pandas DataFrame
  dataseries.ds("ch_fso_cpi", item="100_100", start="2020-01-01")
  dataseries.ds_search("unemployment")

Both also expose ds_catalog() (every dataset) and ds_meta(<dataset_id>) (a
dataset's dimensions and the codes within them).
Source: https://github.com/cynkra/dataseries and .../dataseries-py

## Worked example — Swiss CPI, tobacco vs total

Page:  https://dataseries.org/d/ch_fso_cpi?series=100_100,100_2408
CSV:   https://dataseries.org/series.csv?dataset=ch_fso_cpi&dims=item=100_100,100_2408
(100_100 = total index, 100_2408 = tobacco. Both URLs work as written.)

## Browse by topic

Every dataset, grouped into the twelve topics the catalog uses, as one page:
  https://dataseries.org/datasets            (also /de/datasets, /fr/datasets, /it/datasets)
Each topic is an anchor, e.g. https://dataseries.org/datasets#prices

## About the data

Who publishes it, and under what terms:
  https://dataseries.org/about       who runs this and where the numbers come from
  https://dataseries.org/libraries   the API, the R and Python packages, CSV for any tool
  https://dataseries.org/licenses    each provider's terms and how to attribute

## Full catalog

https://dataseries.org/llms-full.txt