Data sets

EconData data sets are laid out in a hierarchical structure

Image: data set structure

The allowable attributes (at each level) are defined by the data structure definition (DSD) which can also be queried through the API. OpenAPI documentation for the full API including the endpoints discussed in this topic can be found here.

The observation attributes are slightly different from the rest of the data message in the way they are handled and stored by EconData. The data contained in each observation are immutable and are stored as a snapshot when the data is periodically released. Consequently data set observations can be queried as they were for a particular timestamp/vintage.

In order to save a snapshot of the observation data (commit/release a data set) it is first staged. The staged data can be queried and validated before each release by ommitting the release query parameter in the data set query. Once released the staged data is deleted.

Data set and series attributes are, on the other hand, not saved with any particular snapshot of obervation data and are as a consequence the same for all releases.

List of relevant endpoints

Create data set

POST /sdmx-codera/v1/datasets

Parameters

body (required)

The body must consist of a tagged JSON object. A JSON tag is a string (starting with the hash symbol) that is prepended to a vector enclosing an object, i.e. [#object.Tag, {tagged-object}]. Tags allow for deserialisation on the backend, the set of tags understood by the API constitute the custom MIME type application/vnd.sdmx-codera.data+json. All JSON data sent to the API is expected to be of the tagged JSON form with the correct content type header set, data can be requested as tagged JSON (application/vnd.sdmx-codera.data+json) or regular JSON as required (application/json).

For example

[
  "#sdmx.infomodel.message.SDMXMessage",
  {
    "header": {
      "id": "EconData",
      "prepared": "2025-04-22T07:44:19.612725638",
      "sender": "EconData web application",
      "receiver": "114c82b8-4071-704b-5378-5ce588960e49"
    },
    "structures": null,
    "data-sets": [
      [
        "#sdmx.infomodel.dataset.DataSet",
        {
          "agencyid": "ECONDATA",
          "id": "MINING",
          "version": "1.0.0",
          "name": [
            "en",
            "Mining"
          ],
          "provision-agreement": [
            "#sdmx.infomodel.registry.ProvisionAgreementRef",
            {
              "agencyid": "ECONDATA",
              "id": "MINING_ECONDATA_STATSSA",
              "version": "1.0.0"
            }
          ],
          "SOURCE_DATASET": "P2041",
          "RELEASE": "Unreleased",
          "series": [
            {
              "MNEMONIC": "MIN002",
              "obs": [
                {
                  "TIME_PERIOD": "2022-01-01",
                  "OBS_VALUE": 91
                },
                {
                  "TIME_PERIOD": "2022-02-01",
                  "OBS_VALUE": 85
                },
                {
                  "TIME_PERIOD": "2022-03-01",
                  "OBS_VALUE": 103.1
                },
                {
                  "TIME_PERIOD": "2022-04-01",
                  "OBS_VALUE": 93.2
                }
              ],
              "FREQ": "M",
              "BASE_PER": "2015",
              "series-key": "MIN002.I.N",
              "MEASURE": "I",
              "SEASONAL_ADJUST": "N",
              "UNIT_MEASURE": "Index",
              "SOURCE_IDENTIFIER": "FMP20001",
              "LABEL": "Total, gold excluded"
            },
            {
              "MNEMONIC": "MIN001",
              "obs": [
                {
                  "TIME_PERIOD": "2022-01-01",
                  "OBS_VALUE": 84.2
                },
                {
                  "TIME_PERIOD": "2022-02-01",
                  "OBS_VALUE": 80
                },
                {
                  "TIME_PERIOD": "2022-03-01",
                  "OBS_VALUE": 94.7
                },
                {
                  "TIME_PERIOD": "2022-04-01",
                  "OBS_VALUE": 85
                }
              ],
              "FREQ": "M",
              "BASE_PER": "2015",
              "series-key": "MIN001.I.N",
              "MEASURE": "I",
              "SEASONAL_ADJUST": "N",
              "UNIT_MEASURE": "Index",
              "SOURCE_IDENTIFIER": "FMP20000",
              "LABEL": "Total, gold included"
            }
          ]
        }
      ]
    ]
  }
]

Read data sets

GET /sdmx-codera/v1/datasets

Parameters

agencyids
ids
versions
relations

All data and metadata in EconData is owned/managed by an entity linked to an agency ID, as such, any reference to an artefact within EconData starts with an agencyid. The agency ID is followed by the resource ID and version - as a result the complete, unique reference is given as agencyid:id(version), eg. ECONDATA:MINING(1.0.0).

The above endpoint is designed to return all available data sets including data up to the data set level (while excluding the series and observation data). The purpose of which is to allow for data discovery (a catalogue of available data sets). Authorisation for this endpoint requires the user to be authenticated.

The first three query parameters are filters restricting the data returned to a comma seperated list of agency IDs, IDs, and versions respectively.

The relations parameter specifies which (if any) related data and metadata structures should be returned with the query. Either those structures that the queried structure references or alternatively, those that the queried structure is referenced by.

Read (specific/single) data set

GET /sdmx-codera/v1/datasets/{dataset-ref}

Parameters

dataset-ref (required)
detail
series-key
relations
release
limit
offset
start
end

The data-set-ref path parameter formats the data set reference agencyid:id(version) as agencyid-id-version, for example, a query of the ECONDATA:MINING(1.0.0) data would be represented by the relative path, /sdmx-codera/v1/datasets/ECONDATA-MINING-1.0.0.

This endpoint is designed as the primary way of retrieving the full data from a particular data set. Using the detail parameter, however, you can restrict the data returned to the data set level by setting it to stub. Authorisation for this endpoint requires the user to be authenticated and to be a member of an organisation with a consumption agreement to consume this resource (see the Authorisation topic for details).

The series key allows filtering of the query such that it returns only the series of interest. Each series key is made up of a n dimensions, these dimensions are ordered to make up the series key where each dimension is seperated by the period symbol, i.e. dim-1.dim-2…dim-n. Each dimension is in turn enumerated by a codelist, i.e. dim-1 = {code-1, code-2, …, code_a, …, code-m}. Each series is uniquely represented by a single code for each dimension, i.e. code-a.code-b…code-c, in words: code a of the first dimension, b of the second, and so on, with code c of the last dimension. By adding multiple codes to a single dimension (seperated by the plus symbol) the user a can specify an additive set of series to be returned, i.e code-x+code-y.code-b…code-c, in words: return all series with the first dimension containing codes x or y, the second dimension with code b, and so on with the last dimension having code c.

The release parameter is a South African Standard Time (SAST) datetime string with the format YYYY-MM-DDThh:mm:ss. The date and time provided will return the data as it was at that time. If no date and time are provided the unreleased/staged data will be returned (provided it exists), else a data set with no observations is returned.

The limit and offset parameters provide pagination facilities for the case where the data exceeds a certain size. The maximum number of series that can be returned by a single request is 1000 (the minimum being 1). The link header in the response to a request can be followed to request the next page with the appropriate offset and limit.

The start and end parameters are date strings with the format YYYY-MM-DD they specify the start and end dates of the observation data to be returned.

Update data set

PUT /sdmx-codera/v1/datasets/{dataset-ref}

Parameters

dataset-ref (required)
body (required)

This endpoint is used to update a data set, namely the data set and series atttributes. As previously mentioned, observation data are immutable and cannot be updated using this endpoint. Observation data must be managed through staging, committing, and rolling back as described below. Authorisation for this endpoint requires the user to be authenticated and to be a member of an organisation with a provision agreement to provide (or in this case modify) this resource (see the Authorisation topic for details).

The data-set-ref path parameter formats the data set reference agencyid:id(version) as agencyid-id-version, for example, to update the ECONDATA:MINING(1.0.0) data set the relative path would be, /sdmx-codera/v1/datasets/ECONDATA-MINING-1.0.0.

This operation is idempotent.

Delete data set

DELETE /sdmx-codera/v1/datasets/{dataset-ref}

Parameters

dataset-ref (required)

This endpoint is used to delete a data set along with all structures that reference it. Authorisation for this endpoint requires the user to be authenticated and to be a member of an organisation with a provision agreement to provide (or in this case remove) this resource (see the Authorisation topic for details).

The data-set-ref path parameter formats the data set reference agencyid:id(version) as agencyid-id-version, for example, to delete the ECONDATA:MINING(1.0.0) data set the relative path would be, /sdmx-codera/v1/datasets/ECONDATA-MINING-1.0.0.

Stage new observations

POST /sdmx-codera/v1/datasets/{dataset-ref}/stage

Parameters

dataset-ref (required)
body (required)

This endpoint is used to stage new observations before they are released. Staging observations will replace already staged observations. Once the staged observations have been verified they can be released with a description and timestamp as appropriate. Authorisation for this endpoint requires the user to be authenticated and to be a member of an organisation with a provision agreement to provide this resource (see the Authorisation topic for details).

The data-set-ref path parameter formats the data set reference agencyid:id(version) as agencyid-id-version, for example, to stage observations for the ECONDATA:MINING(1.0.0) data set the relative path would be, /sdmx-codera/v1/datasets/ECONDATA-MINING-1.0.0.

Reset staged (unstage) observations

POST /sdmx-codera/v1/datasets/{dataset-ref}/reset

This endpoint is used to unstage already staged observations before they are released. Unstaging observations will delete them and subsequently no staged observations will be available for this data set. Authorisation for this endpoint requires the user to be authenticated and to be a member of an organisation with a provision agreement to provide this resource (see the Authorisation topic for details).

The data-set-ref path parameter formats the data set reference agencyid:id(version) as agencyid-id-version, for example, to unstage observations for the ECONDATA:MINING(1.0.0) data set the relative path would be, /sdmx-codera/v1/datasets/ECONDATA-MINING-1.0.0.

Commit/release staged observations

POST /sdmx-codera/v1/datasets/{dataset-ref}/commit

Parameters

release
description

This endpoint is used to release already staged observations. Staged observations should be verified before they are released with a description and timestamp as appropriate. The release parameter is a South African Standard Time (SAST) datetime string with the format YYYY-MM-DDThh:mm:ss. The release description is a string. Authorisation for this endpoint requires the user to be authenticated and to be a member of an organisation with a provision agreement to provide this resource (see the Authorisation topic for details).

The data-set-ref path parameter formats the data set reference agencyid:id(version) as agencyid-id-version, for example, to commit a release for the ECONDATA:MINING(1.0.0) data set the relative path would be, /sdmx-codera/v1/datasets/ECONDATA-MINING-1.0.0.

Rollback (delete) latest/last release

POST /sdmx-codera/v1/datasets/{dataset-ref}/rollback

This endpoint is used to roll back previously released observations (to the prior release). This is a desctructive operation and cannot be undone. Authorisation for this endpoint requires the user to be authenticated and to be a member of an organisation with a provision agreement to provide this resource (see the Authorisation topic for details).

The data-set-ref path parameter formats the data set reference agencyid:id(version) as agencyid-id-version, for example, to roll back the ECONDATA:MINING(1.0.0) data set the relative path would be, /sdmx-codera/v1/datasets/ECONDATA-MINING-1.0.0.

Query available release (dates)

GET /sdmx-codera/v1/datasets/{dataset-ref}/release

Parameters

after
before

This endpoint returns a list of dates of when there was a release for a particular data set. The query parameters before and after specify a date range filter for the returned releases. Both parameters are South African Standard Time (SAST) datetime strings with the format YYYY-MM-DDThh:mm:ss.

The data-set-ref path parameter formats the data set reference agencyid:id(version) as agencyid-id-version, for example, to fetch the releases for the ECONDATA:MINING(1.0.0) data set the relative path would be, /sdmx-codera/v1/datasets/ECONDATA-MINING-1.0.0.

Generated by Codox

EconData 3.0.0

Project

Topics

Namespaces

Data sets

List of relevant endpoints

Create data set

Parameters

Read data sets

Parameters

Read (specific/single) data set

Parameters

Update data set

Parameters

Delete data set

Parameters

Stage new observations

Parameters

Reset staged (unstage) observations

Commit/release staged observations

Parameters

Rollback (delete) latest/last release

Query available release (dates)

Parameters