SDMX API v2.1

 

Resources

The following resources are defined:

  • datastructure (This has been shortened from DataStructureDefinition to allow for shorter URLs)
  • metadatastructure (This has been shortened from MetadataStructureDefinition to allow for shorter URLs)
  • categoryscheme
  • conceptscheme
  • codelist
  • dataflow
  • metadataflow
  • categorisation
  • structure (This type can be used to retrieve any type of structural metadata matching the supplied parameters)

 

Parameters

Parameters used for identifying a resource

The following parameters are used for identifying resources:

Parameter Type Description
agencyID A string compliant with the SDMX common:NCNameIDType The agency maintaining the artefact to be returned. It is possible to set more than one agency, using + as separator (e.g. BIS+ECB).
resourceID A string compliant with the SDMX common:IDType The id of the artefact to be returned. It is possible to set more than one id, using + as separator (e.g. CL_FREQ+CL_CONF_STATUS).
version A string compliant with the SDMX common:VersionType The version of the artefact to be returned. It is possible to set more than one version, using + as separator (e.g. 1.0.0+2.1.0).

The parameters mentioned above are specified using the following syntax:

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/2.1/{resource}/{agencyID}/{resourceID}/{version}

 

Furthermore, some keywords may be used:

Keywords Scope Description
all agencyID Returns artefacts maintained by any maintenance agency
all resourceID Returns all resources of the type defined by the resource parameter
all version Returns all versions of the resource
latest version Returns the latest version in production of the resource

As all is a reserved keyword in the SDMX RESTful API, it is recommended not to use it as an identifier for agencies, resources or a specific version.

The following rules apply:

  • If no version is specified, the version currently used in production should be returned. It is therefore equivalent to using the keyword latest.
  • If no agencyID is specified, the matching artefacts maintained by any maintenance agency should be returned. It is therefore equivalent to using the keyword all. This would potentially return more than one artefact, if different agencies give the same identifier to a resource (for example, https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/2.1/codelist/all/CL_FREQ, could return more than one codelist if more than one agency is maintaining a codelist with id "CL_FREQ").
  • If no resourceID is specified, all matching artefacts (according to the other criteria used) should be returned. It's is therefore equivalent to using the keyword all.
  • If no parameters are specified, the latest version of all resources of the type identified by the resource parameter, maintained by any maintenance agency should be returned.

 

Additional parameter used for identifying a resource, for item scheme types

SDMX uses the item scheme pattern to model SDMX collections of items. These are:

  • categoryscheme
  • conceptscheme
  • codelist

Although it is not following the item scheme pattern, hierarchicalcodelist is also a collection, i.e. a collection of hierarchies.

For these collections (those following the item scheme pattern or the hierarchicalcodelist), it is possible to use a 4th parameter for identifying a resource. The rules for the 3 other parameters, as defined in the section above, remain valid.

Parameter Type Description
itemID A string compliant with the SDMX common:NestedNCNameIDType for conceptscheme and agencyscheme, SDMX common:IDType for hierarchicalcodelist or with the SDMX common:NestedIDType in all other cases The id of the item to be returned. It is possible to set more than one id, using + as separator (e.g. A+Q+M).

This 4th parameter is used as follows:

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/2.1/{resource}/{agencyID}/{resourceID}/{version}/{itemID}

 

Furthermore, a keyword may be used:

Keyword Scope Description
all itemID Returns all items belonging to the item scheme

The following rules apply:

  • If no itemID is specified, all the items belonging to the item scheme should be returned. It is therefore equivalent to using the keyword all.
  • If itemID is set and is a top-level id (e.g.: Code A (Annual) in the Frequency Codelist), and such an item exists in the matching item scheme, the item scheme returned should contain only the matching item and its isPartial parameter should be set to true.
  • If itemID is set and is a nested id (e.g.: Category A.1.1, belonging to Category A.1, belonging to Category A in a Category Scheme), and such an item exists in the matching item scheme, the item scheme returned should contain the matching item and its ancestors, and its isPartial parameter should be set to true.

 

Parameters used to further describe the desired results

The following parameters are used to further describe the desired results, once the resource has been identified. As mentioned in 3.2, these parameters appear in the query string part of the URL.

Parameter Type Description  
detail String This attribute specifies the desired amount of information to be returned. For example, it is possible to instruct the web service to return only basic information about the maintainable artefact (i.e.: id, agency id, version and name). Most notably, items of item schemes will not be returned (for example, it will not return the codes in a code list query). Possible values are: allstubs (all artefacts should be returned as stubs, containing only identification information, as well as the artefacts' name), referencestubs (referenced artefacts should be returned as stubs, containing only identification information, as well as the artefacts' name), referencepartial (referenced item schemes should only include items used by the artefact to be returned. For example, a concept scheme would only contain the concepts used in a DSD, and its isPartial flag would be set to true. Likewise, if a dataflow has been constrained, then the codelists referenced by the DSD referenced by the dataflow should only contain the codes allowed by the content constraint), allcompletestubs (all artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information), referencecompletestubs (referenced artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information) and full (all available information for all artefacts should be returned). full
references String This attribute instructs the web service to return (or not) the artefacts referenced by the artefact to be returned (for example, the code lists and concepts used by the data structure definition matching the query), as well as the artefacts that use the matching artefact (for example, the dataflows that use the data structure definition matching the query). Possible values are: none (no references will be returned), parents (the artefacts that use the artefact matching the query), parentsandsiblings (the artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts), children (artefacts referenced by the artefact to be returned), descendants (references of references, up to any level, will also be returned), all (the combination of parentsandsiblings and descendants). In addition, a concrete type of resource may also be used (for example, references=codelist). none

 

Applicability and meaning of references attribute

The table below lists the 1st level artefacts (one level up, one level down) that will be returned if the references parameter is set to all. Artefacts referenced by the matching artefact are displayed in regular style, while the artefacts that reference the matching artefact are displayed in Italic.

Maintainable artefact Artefacts returned
Categorisation All
CategoryScheme Categorisations
Codelist Categorisation, ConceptScheme, DataStructureDefinition, MetadataStructureDefinition
ConceptScheme Categorisation, Codelist, DataStructureDefinition, MetadataStructureDefinition
Dataflow Categorisation, DataStructureDefinition
DataStructureDefinition Categorisation, Codelist, ConceptScheme, Dataflow
Metadataflow Categorisation, MetadataStructureDefinition
MetadataStructureDefinition Categorisation, ConceptScheme, Codelist, AgencyScheme, Metadataflow

 

Examples

Data and Metadata Queries

Resources

The following resources should be supported:

  • data
  • metadata

 

Parameters

Parameters used for identifying a resource

The following parameters are used for identifying resources in data queries:

Parameter Type Description
flowRef A string identifying the dataflow. The syntax is agency id, artefact id, version, separated by a ",". For example: AGENCY_ID,FLOW_ID,VERSION. In case the string only contains one out of these 3 elements, it is considered to be the flow id, i.e. all,FLOW_ID,latest. In case the string only contains two out of these 3 elements, they are considered to be the agency id and the flow id, i.e. AGENCY_ID,FLOW_ID,latest. The data (or metadata) flow of the data (or metadata) to be returned. Its a common use case in SDMX-based web services that the flow id is sufficient to uniquely identify a dataflow. Should this not be the case, the agency id and the dataflow version, can be used, in conjunction with the flow id, in order to uniquely identify a dataflow.
key A string compliant with the KeyType defined in the SDMX WADL. The key of the artefact to be returned. Wildcarding is supported by omitting the dimension code for the dimension to be wildcarded. For example, if the following series key identifies the bilateral exchange rates for the daily US dollar exchange rate against the euro, D.USD.EUR.SP00.A, then the following series key can be used to retrieve the data for all currencies against the euro: D..EUR.SP00.A.The OR operator is supported using the + character. For example, the following series key can be used to retrieve the exchange rates against the euro for both the US dollar and the Japanese Yen: D.USD+JPY.EUR.SP00.A.
providerRef A string identifying the provider. The syntax is agency id, provider id, separated by a ",". For example: AGENCY_ID,PROVIDER_ID. In case the string only contains one out of these 2 elements, it is considered to be the provider id, i.e. all,PROVIDER_ID. The provider of the data (or metadata) to be retrieved. If not supplied, the returned message will contain data (or metadata) provided by any provider. Its a common use case in SDMX-based web services that the provider id is sufficient to uniquely identify a data provider. Should this not be the case, the agency can be used, in conjunction with the provider id, in order to uniquely identify a data provider. The OR operator is supported using the + character. For example, the following value can be used to indicate that the data should be provided by the Swiss National Bank (CH2) or Central Bank of Norway (NO2): CH2+NO2.

The parameters mentioned above are specified using the following syntax:

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/2.1/resource/flowRef/key/providerRef

 

Furthermore, some keywords may be used:

Keywords Scope Description
all key Returns all data belonging to the specified dataflow and provided by the specified provider.
all providerRef Returns all data matching the supplied key and belonging to the specified dataflow that has been provided by any data provider. As all is a reserved keyword in the SDMX RESTful API, it is recommended not to use it as an identifier for providers.

The following rules apply:

  • If no key is specified, all data (or metadata) belonging to the dataflow (or metadataflow) identified by the flowRef should be supplied. It is therefore equivalent to using the keyword all.
  • If no providerRef is specified, the matching data (or metadata) provided by any data provider should be returned. It is therefore equivalent to using the keyword all.

 

Parameters used to further filter the desired results

The following parameters are used to further describe (or filter) the desired results, once the resource has been identified. As mentioned in 3.2, these parameters go in the query string part of the URL.

Parameter Type Description
startPeriod common:StandardTimePeriodType, as defined in the SDMXCommon.xsd schema. Can be expressed using dateTime (all data that falls between the calendar dates will be matched), Gregorian Period (all data that falls between the calendar dates will be matched) or Reporting Period (all data reported as periods that fall between the specified periods will be returned. When comparing reporting weeks and days to higher order periods (e.g. quarters) one must account for the actual time frames covered by the periods to determine whether the data should be included. Data reported as Gregorian periods or distinct ranges will be returned if it falls between the specified reporting periods, based on a reporting year start day of January 1). In case the : or + characters are used, the parameter must be percent-encoded by the client. Note that this value is assumed to be inclusive to the range of data being sought. For additional information about the formats, see section 4.2.14 of Section 06 (SDMX Technical Notes). The start period for which results should be supplied (inclusive).
endPeriod Same as above The end period for which results should be supplied (inclusive).
updatedAfter xs:dateTime The last time the query was performed by the client in the database. If this attribute is used, the returned message should only include the latest version of what has changed in the database since that point in time (updates and revisions). This should include observations that have been added since the last time the query was performed (INSERT), observations that have been revised since the last time the query was performed (UPDATE) and observations that have been deleted since the last time the query was performed (DELETE). If no offset is specified, default to local time of the web service. If the information about when the data has been updated is not available at the observation level, the web service should return either the series that have changed (if the information is attached at the series level) or the dataflows that have changed (if the information is attached at the dataflow level).
firstNObservations Positive integer Integer specifying the maximum number of observations to be returned for each of the matching series, starting from the first observation
lastNObservations Positive integer Integer specifying the maximum number of observations to be returned for each of the matching series, counting back from the most recent observation
dimensionAtObservation A string compliant with the SDMX common:NCNameIDType The ID of the dimension to be attached at the observation level. This parameter allows the client to indicate how the data should be packaged by the service. The options are TIME_PERIOD (a timeseries view of the data), the ID of any other dimension used in that dataflow (a cross-sectional view of the data) or the keyword AllDimensions (a flat view of the data where the observations are not grouped, neither in time series, nor in sections). In case this parameter is not set, the service is expected to: Default to TimeDimension, if the data structure definition has one; If not, default to MeasureDimension, if the data structure definition has one; If none of the above is true, default to AllDimensions.
detail String This attribute specifies the desired amount of information to be returned. For example, it is possible to instruct the web service to return data only (i.e. no attributes). Possible options are: full (all data and documentation, including annotations - This is the default), dataonly (attributes and therefore groups will be excluded from the returned message), serieskeysonly (returns only the series elements and the dimensions that make up the series keys. This is useful for performance reasons, to return the series that match a certain query, without returning the actual data) and nodata (returns the groups and series, including attributes and annotations, without observations).
includeHistory Boolean This attribute allows retrieving previous versions of the data, as they were disseminated in the past (history or timeline functionality). When the value is set to true, the returned SDMX-ML data message should contain one or two datasets per data dissemination, depending on whether a dissemination also deleted observations from the data source. The validFromDate and/or validToDate attributes of the dataset should be used to indicate the periods of validity for the data contained in the data set. See below for an example on how to handle the includeHistory parameter. Default to false.

The table below defines the meaning of parameters combinations:

Combination Meaning
startPeriod with no endPeriod Until the most recent
endPeriod and no startPeriod From the beginning
startPeriod and endPeriod Within the supplied time range
lastNObservations + startPeriod/endPeriod The specified number of observations, starting from the end, within the supplied time range
firstNObservations + startPeriod/endPeriod + updatedAfter The specified number of observations, starting from the beginning, that have changed since the supplied timestamp, within the supplied time range
updatedAfter + startPeriod/endPeriod The observations, within the supplied time range, that have changed since the supplied timestamp.

 

Examples

Example: How to handle the includeHistory parameter

For example, for a particular series, there were, so far, 3 disseminations:

  • In February 2012, there was the initial dissemination, with 2 periods: 2011-12 and 2012-01.
  • In March, the decision was taken to delete all observations before 2012 (so, 2011-12). In addition, a new observation has been published for 2012-02.
  • In April, the value for February has been revised, and the value for March has been published.

If the value of the includeHistory is set to true, the web service should return 4 datasets:

  • The first dataset contains the data disseminated in February, so 2 observations (2011-12 and 2012-01). The dataset action flag is Replace.
  • The second dataset contains the new data disseminated in March. It will contain one observation (2012-02). The dataset action flag is also Replace.
  • The third dataset contains the deleted data, removed with the March dissemination. It will contain one observation (2011-12). The dataset action flag is Delete.
  • The fourth dataset contains the data disseminated in April. It will contain the revised observation (2012-02) and the new one (2012-03). The dataset action flag is Replace.

The validFrom and validTo flags should be used as follows:

  • For datasets whose action flag is Replace, the validFromDate is used to indicate from which point in time the values are considered valid.
  • For datasets whose action flag is Delete, the validToDate is used to indicate until which point in time the values were considered valid.

Other Queries

Data availability

The availableconstraint resource defines what data are available for a Dataflow, based on a data query. It returns a ContentConstraint, i.e. structural metadata, and is therefore similar to the other structural metadata queries but the query itself is more akin to a data query.

 

Parameters

Parameters used for identifying a resource

The following parameters are used for identifying resources:

Parameter Type Description
flowRef A string identifying the dataflow. The syntax is agency id, artefact id, version, separated by a ",". For example: AGENCY_ID,FLOW_ID,VERSION. In case the string only contains one out of these 3 elements, it is considered to be the flow id, i.e. all,FLOW_ID,latest. In case the string only contains two out of these 3 elements, they are considered to be the agency id and the flow id, i.e. AGENCY_ID,FLOW_ID,latest. The dataflow of the data for which the data availability information is to be returned. Its a common use case in SDMX-based web services that the flow id is sufficient to uniquely identify a dataflow. Should this not be the case, the agency id and the dataflow version, can be used, in conjunction with the flow id, in order to uniquely identify a dataflow.
key A string compliant with the KeyType defined in the SDMX WADL. The key of the artefact to be returned. Wildcarding is supported by omitting the dimension code for the dimension to be wildcarded. For example, if the following series key identifies the bilateral exchange rates for the daily US dollar exchange rate against the euro, D.USD.EUR.SP00.A, then the following series key can be used to retrieve the data for all currencies against the euro: D..EUR.SP00.A.The OR operator is supported using the + character. For example, the following series key can be used to retrieve the exchange rates against the euro for both the US dollar and the Japanese Yen: D.USD+JPY.EUR.SP00.A.
providerRef A string identifying the provider. The syntax is agency id, provider id, separated by a ",". For example: AGENCY_ID,PROVIDER_ID. In case the string only contains one out of these 2 elements, it is considered to be the provider id, i.e. all,PROVIDER_ID. The provider of the data for which the data availability information should be retrieved on. This can be used in cases where multiple Data Providers provide data for a single Dataflow, and information is required about the data available from only one of the Data Providers for the Dataflow identified. If not supplied, the returned message will contain information about the data provided by all providers. It is a common use case in SDMX-based web services that the provider id is sufficient to uniquely identify a data provider. Should this not be the case, the agency can be used, in conjunction with the provider id, in order to uniquely identify a data provider.
componentId A string compliant with the SDMX common: IDType The id of the Dimension for which to obtain availability information about. In the case where this information is not provided, data availability will be provided for all Dimensions.

The parameters mentioned above are specified using the following syntax:

Furthermore, some keywords may be used:

Keywords Scope Description
all key Returns data availability information pertaining to all the data belonging to the specified dataflow and provided by the specified provider.
all providerRef Returns data availability information matching the supplied key and belonging to the specified dataflow that has been provided by any data provider. As all is a reserved keyword in the SDMX RESTful API, it is recommended not to use it as an identifier for providers.
all componentId Returns data availability information matching the supplied key and belonging to the specified dataflow that has been provided by the specified data providers for all Dimensions. As all is a reserved keyword in the SDMX RESTful API, it is recommended not to use it as an identifier for providers. As all is a reserved keyword in the SDMX RESTful API, it is recommended not to use it as an identifier for Dimension Ids.

The following rules apply:

  • If no key is specified, it is equivalent to using the keyword all.
  • If no providerRef is specified, it equivalent to using the keyword all.
  • If no componentId is specified, it equivalent to using the keyword all.

 

Parameters used to further filter the desired results

The following query string parameters are used to further describe (or filter) the desired results, once the resource has been identified.

Parameter Type Description Default
startPeriod common:StandardTimePeriodType, as defined in the SDMXCommon.xsd schema. Can be expressed using dateTime (all data that falls between the calendar dates will be matched), Gregorian Period (all data that falls between the calendar dates will be matched) or Reporting Period (all data reported as periods that fall between the specified periods will be returned. When comparing reporting weeks and days to higher order periods (e.g. quarters) one must account for the actual time frames covered by the periods to determine whether the data should be included. Data reported as Gregorian periods or distinct ranges will be returned if it falls between the specified reporting periods, based on a reporting year start day of January 1). In case the : or + characters are used, the parameter must be percent-encoded by the client. Note that this value is assumed to be inclusive to the range of data being sought. For additional information about the formats, see section 4.2.14 of Section 06 (SDMX Technical Notes). The start period for which results should be supplied (inclusive).  
endPeriod Same as above The end period for which results should be supplied (inclusive).  
updatedAfter xs:dateTime The last time the query was performed by the client. If this attribute is used, the returned message should only include the dimension values for the data that have changed since that point in time (updates and revisions). This should include the dimension values for data that have been added since the last time the query was performed (INSERT), data that have been revised since the last time the query was performed (UPDATE) and data that have been deleted since the last time the query was performed (DELETE). If no offset is specified, default to local time of the web service.  
references String This attribute instructs the web service to return (or not) the artefacts referenced by the ContentConstraint to be returned possible values are: "codelist", "datastructure", "conceptscheme", "dataflow", "dataproviderscheme", "none", "all" none. The keyword "all" is used to indicate the inclusion of dataflow, datastructure, conceptschemes, dataproviderschemes and codelists. Note, in the case ItemSchemes are returned (i.e. Codelists, ConceptSchemes and DataProviderSchemes), only the items used by the ContentConstraint will be included (i.e. concepts used by the constrained dimensions; codes for which data are available; data providers that have provided data available according to the CubeRegion). Additionally for Codelists parent codes will be included in the response if the child codes are in the returned codelist, irrespective of whether they are referenced by the ContentConstraint. If this results in a partial list, the isPartial attribute will be set to true.
mode String This attribute instructs the web service to return a ContentConstraint which defines a Cube Region containing values which will be returned by executing the query (mode="exact") vs a Cube Region showing what values remain valid selections that could be added to the data query (mode="available"). A valid selection is one which results in one or more series existing for the selected value, based on the current data query selection state defined by the current path parameters. exact

The table below defines the meaning of parameters combinations:

Combination Meaning
startPeriod with no endPeriod Until the most recent
endPeriod and no startPeriod From the beginning
startPeriod and endPeriod Within the supplied time range
updatedAfter + startPeriod/endPeriod Available data within the supplied time range, that have changed since the supplied timestamp

 

Examples