openapi: 3.1.0
info:
  title: Hungarian Central Statistical Office - High-Value Datasets API
  description: |
    This API provides access to high-value datasets of the Hungarian Central Statistical Office in various formats.
    Accessing this API from third-party client-side web applications currently not allowed (blocked via CORS Policy).
  version: 1.0.0
  contact:
    name: Hungarian Central Statistical Office
    url: https://data.ksh.hu/

servers:
  - url: https://data.ksh.hu/

tags:
  - name: api

paths:
  /datasets.json:
    get:
      operationId: datasetsList
      tags: [api]
      summary: Retrieve a list of available datasets
      description: A JSON response that lists all avaliable datasets.
      responses:
        '200':
          description: JSON structure that lists the datasets.
          content:
            text/html:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    titles:
                      type: object
                      properties:
                        hu:
                          type: string
                        en:
                          type: string
                    descriptions:
                      type: object
                      properties:
                        hu:
                          type: string
                        en:
                          type: string
                    themes:
                      type: object
                      properties:
                        hu:
                          type: string
                        en:
                          type: array
                          items:
                            type: string
                    tags:
                      type: object
                      properties:
                        hu:
                          type: string
                        en:
                          type: array
                          items:
                            type: string
                  required:
                    - id
                    - title

  /datasets/{identifier}:
    get:
      operationId: datasetLandingPage
      tags: [api]
      summary: Dataset landing page
      description: Returns the HTML landing page of the dataset.
      parameters:
        - name: identifier
          in: path
          required: true
          description: The unique identifier of the dataset.
          schema:
            type: string
      responses:
        '200':
          description: HTML description of the dataset landing page.
          content:
            text/html:
              schema:
                type: string
                description: This is a complete HTML document, not just a fragment.
        '404':
          description: No dataset found with the provided identifier.
          content:
            text/html:
              schema:
                type: string

  /datasets/{identifier}/schema/{resource}.{format}:
    get:
      operationId: datasetSchema
      tags: [api]
      summary: Access the schema of the dataset
      description: Access the schema file of the dataset in the specified format.
      parameters:
        - name: identifier
          in: path
          required: true
          description: The unique identifier of the dataset.
          schema:
            type: string
        - name: resource
          in: path
          required: true
          description: The unique identifier of the resource.
          schema:
            type: string
        - name: format
          in: path
          required: true
          description: The schema format. Certain formats may not be available for specific datasets.
          schema:
            type: string
            enum: [xml, json]
      responses:
        '200':
          description: The schema file in the requested format.
          content:
            application/xml:
              schema:
                type: string
                description: This content is an SDMX Schema XML. For more information visit https://sdmx.org/standards/
            application/json:
              schema:
                type: object
                description: This content is an SDMX Schema JSON. For more information visit https://sdmx.org/standards/
        '404':
          description: No dataset found with the provided identifier or in the specified format.
          content:
            text/html:
              schema:
                type: string

  /datasets/{identifier}/data/{resource}.{format}:
    get:
      operationId: datasetData
      tags: [api]
      summary: Access the data of the dataset
      description: Access the dataset file in the specified format.
      parameters:
        - name: identifier
          in: path
          required: true
          description: The unique identifier of the dataset.
          schema:
            type: string
        - name: resource
          in: path
          required: true
          description: The unique identifier of the resource.
          schema:
            type: string
        - name: format
          in: path
          required: true
          description: The dataset format. Certain formats may not be available for specific datasets.
          schema:
            type: string
            enum: [csv, xlsx]
      responses:
        '200':
          description: The dataset file in the requested format.
          content:
            text/csv:
              schema:
                type: string
                description: This content is an SDMX Data CSV. For more information visit https://sdmx.org/standards/
            application/xml:
              schema:
                type: string
                description: This content is an SDMX Data XML. For more information visit https://sdmx.org/standards/
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
                description: This content is an SDMX Data Excel. For more information visit https://sdmx.org/standards/
        '404':
          description: No dataset found with the provided identifier or in the specified format.
          content:
            text/html:
              schema:
                type: string