Skip to content

Period Codes & Column Resolution

CBS Statline uses internal encodings for time periods and column names. cbspy automatically decodes these to human-readable labels. This page explains how the decoding works, with interactive examples you can try in your browser.

Period code formats

CBS encodes time periods as strings with a specific format:

Pattern Example Decoded
YYYYJJnn 2023JJ00 2023 (yearly)
YYYYKWnn 2023KW01 2023 Q1 (quarterly)
YYYYMMnn 2023MM03 2023 March (monthly)

Try the period decoder

Type a CBS period code below to see how cbspy decodes it:

Try these examples:

  • 2023JJ00 (yearly)
  • 2023KW03 (quarterly -- Q3)
  • 2023MM12 (monthly -- December)
  • 1990JJ00 (older data)

Batch decoding

Here is a batch of period codes and their decoded values:

How period decoding works

cbspy uses three regular expressions to match period codes:

  1. Yearly: ^\d{4}JJ00$ -- matches codes like 2023JJ00. Extracts the four-digit year.
  2. Quarterly: ^\d{4}KW0[1-4]$ -- matches codes like 2023KW01. Extracts year and quarter number.
  3. Monthly: ^\d{4}MM\d{2}$ -- matches codes like 2023MM03. Extracts year and month number, then maps to the month name.

If none of the patterns match, the original string is returned unchanged. This ensures that unexpected formats pass through without raising errors.

Column resolution

When you call client.get_data(), cbspy renames columns from CBS internal IDs to human-readable titles. For example:

CBS internal ID Resolved column name
TotalPopulation_1 Total population
Males_2 Males
Females_3 Females
LiveBornChildren_4 Live born children
Periods Periods

This mapping is built from the table's DataProperties resource, which contains a Key (internal ID) and Title (display name) for each column.

The resolution flow

  1. cbspy fetches DataProperties for the requested table
  2. Builds a mapping: {Key: Title} for each column
  3. Identifies period columns (those with Type == "TimeDimension")
  4. Fetches the raw data from TypedDataSet
  5. Renames each column using the mapping
  6. Decodes period values in period columns
  7. Removes the internal ID column
  8. Returns a Polars DataFrame with clean column names