Statistics Finland Data API

openapi: 3.2.0
info:
  title: Stat Fi Data API
  version: v1
  contact:
    name: Statistics Finland
    url: https://stat.fi
    email: tietokannat@stat.fi
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/deed
  description: 'Operations tagged Data across 2 of this provider''s published API definitions: stat-fi-pxapi-beta-openapi.json, stat-fi-pxapi-beta-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.stat.fi/px/beta
  description: Primary API server
tags:
- name: Data
paths:
  /data/databases/{database}/tables/{table}:
    get:
      tags:
      - Data
      summary: Retrieves data using query string filters.
      description: 'Accept header options: application/json (JSON-stat), text/csv (CSV), */* treated as JSON-stat. Unsupported media types yield 406.'
      operationId: getData
      parameters:
      - name: database
        in: path
        description: Database identifier containing the table.
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: PX table identifier.
        required: true
        schema:
          type: string
      - name: filters
        in: query
        description: 'Array of filter specs: ''dimension:filterType=value''. Types: code | from | to | first | last. Wildcard ''*'' matches zero or more characters. Single filter per dimension. first/last require integer > 0. from/to accept single value (wildcards allowed). code accepts one or more comma-separated values (wildcards allowed). Escaping ''*'' not supported; literal asterisk must be matched exactly if no wildcard semantics desired.'
        schema:
          type: array
          items:
            type: string
        examples:
          code-filter:
            summary: Code filter
            description: Single gender, multiple ages, full wildcard region, partial wildcard category.
            value:
            - gender:code=1
            - age:code=25-34,35-44
            - region:code=*
            - category:code=*manufacturing*
          from-filter:
            summary: From filter
            description: Years from 2020 onward; time codes starting with 202.
            value:
            - year:from=2020
            - time:from=202*
          to-filter:
            summary: To filter
            description: Years up to 2023; time codes up to first match starting with 2022.
            value:
            - year:to=2023
            - time:to=2022*
          first-filter:
            summary: First filter
            description: First 10 region codes.
            value:
            - region:first=10
          last-filter:
            summary: Last filter
            description: Last 5 region codes.
            value:
            - region:last=5
          combined-filters:
            summary: Combined filters
            description: Multiple types together.
            value:
            - gender:code=1,2
            - year:from=2020
            - age:to=81-90
            - region:first=3
            - rooms:last=2
      - name: lang
        in: query
        description: Optional language code (ISO 639-1). Defaults to table's default language. Must be one of the table's AvailableLanguages.
        schema:
          type: string
      responses:
        '200':
          description: Successful query returning data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonStat2'
              examples:
                default:
                  value:
                    version: '2.0'
                    class: dataset
                    id:
                    - vuosi
                    - sukupuoli
                    - ika
                    - tiedot
                    label: Population according to age (5-year) and sex, 2014-2023
                    source: Statistics Finland, population structure
                    updated: '2024-04-26T08:00:00Z'
                    dimension:
                      vuosi:
                        label: Year
                        category:
                          index:
                          - '2014'
                          - '2015'
                          - '2016'
                          - '2017'
                          - '2018'
                          - '2019'
                          - '2020'
                          - '2021'
                          - '2022'
                          - '2023'
                          label:
                            '2014': '2014'
                            '2015': '2015'
                            '2016': '2016'
                            '2017': '2017'
                            '2018': '2018'
                            '2019': '2019'
                            '2020': '2020'
                            '2021': '2021'
                            '2022': '2022'
                            '2023': '2023'
                      sukupuoli:
                        label: Sex
                        category:
                          index:
                          - SSS
                          - '1'
                          - '2'
                          label:
                            SSS: Total
                            '1': Males
                            '2': Females
                      ika:
                        label: Age
                        category:
                          index:
                          - SSS
                          label:
                            SSS: Total
                      tiedot:
                        label: Information
                        category:
                          index:
                          - vaesto
                          label:
                            vaesto: Population 31 Dec
                          unit:
                            vaesto:
                              label: ''
                              decimals: 0
                    value:
                    - 5471753
                    - 2691863
                    - 2779890
                    - 5487308
                    - 2701490
                    - 2785818
                    - 5503297
                    - 2712327
                    - 2790970
                    - 5513130
                    - 2719131
                    - 2793999
                    - 5517919
                    - 2723290
                    - 2794629
                    - 5525292
                    - 2728262
                    - 2797030
                    - 5533793
                    - 2733808
                    - 2799985
                    - 5548241
                    - 2743101
                    - 2805140
                    - 5563970
                    - 2753477
                    - 2810493
                    - 5603851
                    - 2773898
                    - 2829953
                    extension: null
                    size:
                    - 10
                    - 3
                    - 1
                    - 1
                    role:
                      time:
                      - Vuosi
                      metric:
                      - Tiedot
            text/csv:
              schema:
                type: string
                description: CSV dataset (UTF-8, comma separated, header row). Column order follows dimension order then metric.
        '400':
          description: Invalid filters, duplicate dimensions, or invalid language.
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Database or table not found.
          content:
            application/json:
              schema:
                type: string
        '406':
          description: Requested media type not supported by endpoint.
        '413':
          description: Request exceeds maximum allowed cell count.
          content:
            application/json:
              schema:
                type: string
        '415':
          description: Unsupported Content-Type header.
          content:
            application/json:
              schema:
                type: string
        '503':
          description: The request is valid but the data is temporarily unavailable due to a database update.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                type: string
        '499':
          description: Client closed the request before the server could respond.
    post:
      tags:
      - Data
      summary: Retrieves data using a JSON body of filter objects
      description: 'Accept header options: application/json (JSON-stat), text/csv (CSV), */* treated as JSON-stat. Unsupported media types yield 406.'
      operationId: postData
      parameters:
      - name: database
        in: path
        description: Database identifier containing the table.
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: PX table identifier.
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: Optional language code (ISO639-1). Defaults to table's default language. Must be one of the table's AvailableLanguages.
        schema:
          type: string
      requestBody:
        description: Dictionary of filters keyed by dimension code. Each value defines type and associated query data.
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/Filter'
              description: Dictionary mapping dimension codes to filter objects (one per dimension).
              example:
                gender:
                  type: Code
                  query:
                  - '1'
                  - '2'
                year:
                  type: From
                  query: '2020'
                region:
                  type: First
                  query: 5
            examples:
              code-filter:
                summary: Code filter
                description: Specific codes, full wildcard, partial wildcard.
                value:
                  gender:
                    type: Code
                    query:
                    - '1'
                  age:
                    type: Code
                    query:
                    - 25-34
                    - 35-44
                  region:
                    type: Code
                    query:
                    - '*'
                  category:
                    type: Code
                    query:
                    - '*manufacturing*'
              from-filter:
                summary: From filter
                description: Inclusive start at value or pattern.
                value:
                  year:
                    type: From
                    query: '2020'
                  time:
                    type: From
                    query: 202*
              to-filter:
                summary: To filter
                description: Inclusive end at value or pattern.
                value:
                  year:
                    type: To
                    query: '2023'
                  time:
                    type: To
                    query: 2022*
              first-filter:
                summary: First filter
                description: First N values (N > 0).
                value:
                  region:
                    type: First
                    query: 10
              last-filter:
                summary: Last filter
                description: Last N values (N > 0).
                value:
                  region:
                    type: Last
                    query: 5
              combined-filters:
                summary: Combined filters
                description: Multiple filter types in one request.
                value:
                  gender:
                    type: Code
                    query:
                    - '1'
                    - '2'
                  year:
                    type: From
                    query: '2020'
                  age:
                    type: To
                    query: 81-90
                  region:
                    type: First
                    query: 3
                  rooms:
                    type: Last
                    query: 2
      responses:
        '200':
          description: Successful query returning data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonStat2'
              examples:
                default:
                  value:
                    version: '2.0'
                    class: dataset
                    id:
                    - vuosi
                    - sukupuoli
                    - ika
                    - tiedot
                    label: Population according to age (5-year) and sex, 2014-2023
                    source: Statistics Finland, population structure
                    updated: '2024-04-26T08:00:00Z'
                    dimension:
                      vuosi:
                        label: Year
                        category:
                          index:
                          - '2014'
                          - '2015'
                          - '2016'
                          - '2017'
                          - '2018'
                          - '2019'
                          - '2020'
                          - '2021'
                          - '2022'
                          - '2023'
                          label:
                            '2014': '2014'
                            '2015': '2015'
                            '2016': '2016'
                            '2017': '2017'
                            '2018': '2018'
                            '2019': '2019'
                            '2020': '2020'
                            '2021': '2021'
                            '2022': '2022'
                            '2023': '2023'
                      sukupuoli:
                        label: Sex
                        category:
                          index:
                          - SSS
                          - '1'
                          - '2'
                          label:
                            SSS: Total
                            '1': Males
                            '2': Females
                      ika:
                        label: Age
                        category:
                          index:
                          - SSS
                          label:
                            SSS: Total
                      tiedot:
                        label: Information
                        category:
                          index:
                          - vaesto
                          label:
                            vaesto: Population 31 Dec
                          unit:
                            vaesto:
                              label: ''
                              decimals: 0
                    value:
                    - 5471753
                    - 2691863
                    - 2779890
                    - 5487308
                    - 2701490
                    - 2785818
                    - 5503297
                    - 2712327
                    - 2790970
                    - 5513130
                    - 2719131
                    - 2793999
                    - 5517919
                    - 2723290
                    - 2794629
                    - 5525292
                    - 2728262
                    - 2797030
                    - 5533793
                    - 2733808
                    - 2799985
                    - 5548241
                    - 2743101
                    - 2805140
                    - 5563970
                    - 2753477
                    - 2810493
                    - 5603851
                    - 2773898
                    - 2829953
                    extension: null
                    size:
                    - 10
                    - 3
                    - 1
                    - 1
                    role:
                      time:
                      - Vuosi
                      metric:
                      - Tiedot
            text/csv:
              schema:
                type: string
                description: CSV dataset (UTF-8, comma separated, header row). Column order follows dimension order then metric.
        '400':
          description: Invalid filter body or invalid language.
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Database or table not found.
          content:
            application/json:
              schema:
                type: string
        '406':
          description: Requested media type not supported by endpoint.
        '413':
          description: Request exceeds maximum allowed cell count.
          content:
            application/json:
              schema:
                type: string
        '415':
          description: Unsupported Content-Type for request body.
          content:
            application/json:
              schema:
                type: string
        '503':
          description: The request is valid but the data is temporarily unavailable due to a database update.
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                type: string
        '499':
          description: Client closed the request before the server could respond.
    options:
      tags:
      - Data
      summary: Returns allowed HTTP methods for the data resource
      operationId: optionsData
      parameters:
      - name: database
        in: path
        description: Database identifier containing the table.
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: PX table identifier.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns allowed methods in the Allow response header.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                type: string
    head:
      tags:
      - Data
      summary: HEAD endpoint returning only headers (no body) for the data query target.
      operationId: headData
      parameters:
      - name: database
        in: path
        description: Database identifier containing the table.
        required: true
        schema:
          type: string
      - name: table
        in: path
        description: PX table identifier.
        required: true
        schema:
          type: string
      - name: lang
        in: query
        description: Optional language code.
        schema:
          type: string
      responses:
        '200':
          description: Resource exists.
        '400':
          description: Invalid language requested.
        '404':
          description: Database or table not found.
        '500':
          description: Unexpected server error.
        '499':
          description: Client closed the request before the server could respond.
    servers:
    - url: https://api.stat.fi/px/beta
      description: Primary API server
components:
  schemas:
    JsonStat2:
      required:
      - class
      - dimension
      - id
      - label
      - size
      - source
      - updated
      - value
      - version
      type: object
      properties:
        version:
          minLength: 1
          type: string
          description: The JSON-stat version string.
        class:
          minLength: 1
          type: string
          description: The object class of the JSON-stat response. For data queries this is always 'dataset'.
          readOnly: true
        id:
          type: array
          items:
            type: string
          description: Ordered list of dimension identifiers. The order defines the major-to-minor traversal used to produce the PxApi.Models.JsonStat.JsonStat2.Value array.
        label:
          minLength: 1
          type: string
          description: Short, language-dependent dataset label.
        note:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Optional annotations about the dataset (language dependent).
        source:
          type:
          - string
          - 'null'
          description: The source of the dataset. Language-dependent.
        updated:
          type:
          - string
          - 'null'
          description: Timestamp indicating when the dataset was last updated (ISO 8601, UTC recommended).
        dimension:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Dimension'
          description: Map from dimension identifier to its metadata (categories, labels, units, etc.).
        value:
          type: array
          items:
            type:
            - number
            - 'null'
            format: double
          description: Flattened array of data values following the Cartesian product of dimensions in the order given by PxApi.Models.JsonStat.JsonStat2.Id. Missing values are encoded as null.
        status:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: Optional status information for data values. Keys are zero-based indexes into PxApi.Models.JsonStat.JsonStat2.Value; values are arbitrary status codes.
        extension:
          type:
          - object
          - 'null'
          additionalProperties: {}
          description: Optional extension object for additional, non-standard metadata. Keys and value types are unrestricted.
        size:
          type: array
          items:
            type: integer
            format: int32
          description: Size of each dimension in the same order as PxApi.Models.JsonStat.JsonStat2.Id. Product of all elements equals PxApi.Models.JsonStat.JsonStat2.Value length.
        role:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          description: Optional mapping declaring special roles for certain dimensions (e.g. time, metric). Each role maps to a list of dimension identifiers.
      additionalProperties: false
      description: Represents a JSON-stat 2.0 dataset response. See https://json-stat.org/ for full specification details.
    Dimension:
      required:
      - category
      - label
      type: object
      properties:
        label:
          minLength: 1
          type: string
          description: The label of the dimension.
        note:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Annotations about the dimension. Language-dependent.
        category:
          $ref: '#/components/schemas/Category'
      additionalProperties: false
      description: Represents a dimension in the JSON-stat format.
    Category:
      required:
      - index
      - label
      type: object
      properties:
        index:
          type: array
          items:
            type: string
          description: The index array of the category.
        label:
          type: object
          additionalProperties:
            type: string
          description: The labels for each category value.
        note:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          description: Possible annotations related to some category values.
        unit:
          type:
          - object
          - 'null'
          additionalProperties:
            $ref: '#/components/schemas/Unit'
          description: The unit of measurement for each category.
      additionalProperties: false
      description: Represents a category in a dimension.
    Filter:
      required:
      - type
      type: object
      properties:
        type:
          enum:
          - Code
          - From
          - To
          - First
          - Last
          type: string
          description: Filter type. Code | From | To | First | Last
        query:
          oneOf:
          - type: array
            items:
              type: string
            description: 'Code filter: list of codes or wildcard patterns. Comma list in GET; array in POST body. ''*'' matches zero or more characters.'
          - type: string
            description: 'From / To filters: single inclusive boundary value; wildcard ''*'' allowed.'
          - minimum: 1
            type: integer
            description: 'First / Last filters: positive count (N > 0).'
          description: 'Filter-specific query value. Code: array[string] (supports ''*'' wildcard). From/To: string (supports ''*''). First/Last: positive integer.'
      additionalProperties: false
      description: Represents a base class for filters that process a collection of dimension value codes.
      example:
        type: Code
        query:
        - A01
        - A02
        - '*MANUF*'
    Unit:
      required:
      - decimals
      - label
      type: object
      properties:
        label:
          minLength: 1
          type: string
          description: Localized label of the unit (e.g., Persons).
        symbol:
          type:
          - string
          - 'null'
          description: Optional symbol for the unit (e.g., %, �).
        position:
          type:
          - string
          - 'null'
          description: 'Optional symbol position relative to value. Allowed values: start, end.'
        decimals:
          type: integer
          description: Number of decimals to display for this unit (>= 0).
          format: int32
      additionalProperties: false
      description: Represents a unit of measurement in the JSON-stat format.
x-refined-from:
- stat-fi-pxapi-beta-openapi.json
- stat-fi-pxapi-beta-openapi.yml