SDMX API v3

 

 

Structure queries

Overview

Structure queries allow retrieving structural metadata.

Below is a list of popular types of structural metadata, that you will typically find in SDMX web services.

  • Concept schemes: In order to make sense of some statistical data, we need to know the concepts associated with them. For example, on its own, the figure 1.2953 is pretty meaningless, but if we know that this is an exchange rate for the US dollar against the euro on 23 November 2006, it starts making more sense. The various concepts are typically grouped into collections known as concept schemes.
  • Codelists: Some of the concepts can be free text (such as a comment about a particular observation value) but others take their values from a controlled vocabulary list (such as, for example, a list of countries). These are known as codelists in SDMX.
  • Data structure definitions: All the concepts that describe a particular domain (such as exchange rates or inflation) are grouped into a data structure definition (DSD). In a DSD, concepts are divided into dimensions and attributes. Dimensions, when combined, allow to uniquely identify statistical data. Attributes on the other hand do not help identifying statistical data, but add useful information (like the unit of measure or the number of decimals). In order to perform granular data queries, one must know the concepts that are used as dimensions, as well as their allowed values (as defined in the codelists).
  • Dataflows: Dataflows represent the data that cover a particular domain (such as, for example, balance of payments). A dataflow provides a reference to the data structure definition that applies for a particular domain, thereby indicating how the data for that domain will look like.

Structure queries in SDMX allow you to retrieve structural metadata at various levels of granularity, from all structural metadata available in the source to a single code from a particular version of a particular codelist maintained by a particular agency.

Syntax

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/structure/{artefactType}/{agencyID}/{resourceID}/{version}?{detail}&{references}

For item schemes, an additional path parameter (itemID) is permissible.

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/structure/{artefactType}/{agencyID}/{resourceID}/{version}/{itemID}?{detail}&{references}
Parameter Type Description Default Multiple values?
artefactType One of the following types: datastructure, metadatastructure, categoryscheme, conceptscheme, codelist, hierarchy, hierarchyassociation, valuelist, agencyscheme, dataproviderscheme, metadataproviderscheme, dataconsumerscheme, organisationunitscheme, dataflow, metadataflow, reportingtaxonomy, provisionagreement, metadataprovisionagreement, structuremap, representationmap, conceptschememap, categoryschememap, organisationschememap, reportingtaxonomymap, process, categorisation, dataconstraint, metadataconstraint, transformationscheme, rulesetscheme, userdefinedoperatorscheme, customtypescheme, namepersonalisationscheme, vtlmappingscheme The type of structural metadata to be returned. * No
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). * Yes
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). * Yes
version A string compliant with the SDMX semantic versioning rules 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.7). ~ Yes
itemID A string compliant with the SDMX common:NestedNCNameIDType for conceptscheme and agencyscheme, any type for valuelist 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 parameter is valid for item schemes only * Yes
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: (1) full: all available information for all returned artefacts should be returned. Returned extended codelists are to be resolved, i.e. include all inherited codes, and must not include the CodelistExtension property. As the inherited codelists must be resolved, they should not be returned a second time as separated codelists. (2) allstubs: all returned artefacts should be returned as stubs, i.e. only containing identification information and the artefacts' name. (3) referencestubs: same as full with the exception that referenced artefacts should be returned only as stubs, i.e. only containing identification information and the artefacts' name. (4) allcompletestubs: all returned artefacts should be returned as complete stubs, i.e. only containing identification information, the artefacts' name, description and annotations. (5) referencecompletestubs: same as full with the exception that referenced artefacts should be returned as complete stubs, i.e. only containing identification information, the artefacts' name, description and annotations. (6) referencepartial: same as full with the exception that 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 referenced by the content constraint. (7) raw: same as full with the exception that the returned extended codelists are not resolved and must include the CodelistExtension property, and if referenced codelists or descendants are to be returned then they include also all inherited codelists. full No
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), ancestors (the artefacts that use the artefact matching the query, up to any level), 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 Yes

 

Notes about using itemID

As mentioned, itemID can be used for item scheme queries only! These are:

  • categoryscheme
  • conceptscheme
  • codelist

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

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.

The detail parameter allows specifying the amount of details to be retrieved. When itemID is used, the full details of the items requested are the following:

  • Identification
  • Names
  • Descriptions
  • Annotations
  • Other details except Items

Since details are not exactly the same for all Item Schemes, the following table provides these details per Artefact type (@ is used for XML attributes and / for XML elements).

Item flat/nested Details in Item Query
Code flat @id, @urn, @uri, /Annotations, /Name, /Description, /Parent
Concept flat @id, @urn, @uri, /Annotations, /Name, /Description, /Parent, /CoreRepresentation, /ISOConceptReference
Agency flat @id, @urn, @uri, /Annotations, /Name, /Description, /Contact
DataProvider flat @id, @urn, @uri, /Annotations, /Name, /Description, /Contact
DataConsumer flat @id, @urn, @uri, /Annotations, /Name, /Description, /Contact
OrganisationUnit flat @id, @urn, @uri, /Annotations, /Name, /Description, /Parent, /Contact
Category nested @id, @urn, @uri, /Annotations, /Name, /Description
ReportingCategory nested @id, @urn, @uri, /Annotations, /Name, /Description, /StructuralMetadata, /ProvisioningMetadata

While most Item Schemes are flat, hence the above table is easy to interpret, for Category Schemes and Reporting Taxonomies (which have a nested structure) the above table indicates that any child Item(s) of the Item(s) requested must not be included in an Item Query request.

Further to the above, the reference resolution mechanism will be applied to all items returned. For example, querying for a category which has two ancestors in the hierarchy of the category scheme, will result into returning three categories (the requested one and its ancestors), as well as all references of those three categories.

 

Applicability and meaning of references (including referencepartial)

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, artefacts that reference the matching artefact are displayed in Italic and artefacts that can both reference and be referenced by the matching artefact are displayed in bold italic.

Maintainable artefact Artefacts returned
Categorisation All, HierarchyAssociation, Metadataflow, MetadataProvisionAgreement, Process
CategoryScheme AgencyScheme, Categorisation, CategorySchemeMap, Metadataflow, MetadataProvisionAgreement, Process
Codelist AgencyScheme, Categorisation, Codelist, ConceptScheme, DataStructureDefinition, Hierarchy, HierarchyAssociation, Metadataflow, MetadataProvisionAgreement, MetadataStructureDefinition, Process, RepresentationMap, VtlMappingScheme
ConceptScheme AgencyScheme, Categorisation, Codelist, ConceptSchemeMap, DataStructureDefinition, HierarchyAssociation, Metadataflow, MetadataProvisionAgreement, MetadataStructureDefinition, Process, VtlMappingScheme
Dataflow AgencyScheme, Categorisation, DataConstraint, DataStructureDefinition, HierarchyAssociation, Metadataflow, MetadataProvisionAgreement, Process, ProvisionAgreement, ReportingTaxonomy, StructureMap, VtlMappingScheme
DataStructureDefinition AgencyScheme, Categorisation, Codelist, ConceptScheme, DataConstraint, Dataflow, HierarchyAssociation, Metadataflow, MetadataProvisionAgreement, MetadataStructureDefinition, Process, StructureMap, ValueList
Hierarchy AgencyScheme, Categorisation, Codelist, HierarchyAssociation, Metadataflow, MetadataProvisionAgreement, Process
HierarchyAssociation All, Categorisation, Metadataflow, MetadataProvisionAgreement, Process
Metadataflow All, Categorisation, HierarchyAssociation, MetadataConstraint, Metadataflow, MetadataProvisionAgreement, Process, ReportingTaxonomy
MetadataStructureDefinition AgencyScheme, Categorisation, Codelist, ConceptScheme, DataStructureDefinition, HierarchyAssociation, MetadataConstraint, Metadataflow, MetadataProvisionAgreement, Process, ValueList
RepresentationMap AgencyScheme, Categorisation, Codelist, HierarchyAssociation, Metadataflow, MetadataProvisionAgreement, Process, ValueList
StructureMap AgencyScheme, Categorisation, Dataflow, DataStructureDefinition, HierarchyAssociation, Metadataflow, MetadataProvisionAgreement, Process

Also, when returning only partial references (via referencepartial), the filtering applies to any dependency, regardless of its level. The table below describes the impact of using referencepartial on the referenced item schemes.

Maintainable artefact Meaning of detail=referencepartial
CategoryScheme Only the categories referenced by the returned categorisations or structure sets should be included in the returned category scheme(s)
Codelist Only the codes referenced by the returned categorisations, data/metadata constraints, hierarchies or structure sets should be included in the returned codelist(s)
ConceptScheme Only the concepts referenced by the returned categorisations, data structure definitions, metadata structure definitions or structure sets should be included in the returned concept scheme(s)

For example, a dataflow only references a data structure definition and, in addition, it may be referenced by one or more data constraints. In case references is set to all and detail is set to referencepartial, the following should apply to the returned item schemes:

  • The concept scheme(s) should only include the concepts referenced by the data structure referenced by target dataflow;
  • The codelist(s) should only include the codes referenced by the data constraint(s) referencing the target dataflow;

Response types

The following media types can be used with structure queries:

  • application/vnd.sdmx.structure+json;version=2.0.0
  • application/vnd.sdmx.structure+json;version=1.0.0
  • application/vnd.sdmx.structure+xml;version=3.0.0
  • application/vnd.sdmx.structure+xml;version=2.1

The default format is highlighted in bold.

 

 

Data availability queries

Overview

Availability queries allow to see what data are available for a structure (data structure, dataflow or provision agreement), based on a data query. It returns a DataConstraint, 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.

Syntax

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/availability/{context}/{agencyID}/{resourceID}/{version}/{key}/{componentId}?{c}&{updatedAfter}&{references}&{mode}

Parameter Type Description Default Multiple values?
context One of the following: datastructure, dataflow, provisionagreement Data can be reported against a data structure, a dataflow or a provision agreement. This parameter allows selecting the desired context for data retrieval. * No
agencyID A string compliant with the SDMX common:NCNameIDType The agency maintaining the artefact for which data have been reported. * Yes
resourceID A string compliant with the SDMX common:IDType The id of the artefact for which data have been reported. * Yes
version A string compliant with the VersionType defined in the SDMX Open API specification The version of the artefact for which data have been reported. * Yes
key A string compliant with the KeyType defined in the SDMX Open API specification. The combination of dimension values identifying the slice of the cube for which data should be returned. Wildcarding is supported via the * operator. For example, if the following key identifies the bilateral exchange rates for the daily US dollar exchange rate against the euro, D.USD.EUR.SP00.A, then the following key can be used to retrieve the data for all currencies against the euro: D.*.EUR.SP00.A * Yes
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. * Yes
c Map Filter data by component value. For example, if a structure defines a frequency dimension (FREQ) and the code A (Annual) is an allowed value for that dimension, the following can be used to retrieve annual data: c[FREQ]=A. The same applies to attributes (e.g. c[CONF_STATUS]=F) and measures. Multiple values are supported, using a comma (,) as separator: c[FREQ]=A,M. In case of attributes that support multiple values, the plus (+) can be used to list all values that an attribute must have. For example, to indicate that ATTR1 must either be A or (B AND M), use the following: c[ATTR1]=A,B+M. Operators may be used too (see table with operators below). This parameter can be used in addition, or instead of, the key path parameter. This parameter may be used multiple times (e.g. c[FREQ]=A,M&c[CONF_STATUS]=F)   Yes
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.   No
references String This attribute instructs the web service to return (or not) the artefacts referenced by the DataConstraint to be returned. Possible values are: "codelist", "datastructure", "conceptscheme", "dataflow", "dataproviderscheme", "none", "all". 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 DataConstraint 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 DataConstraint. If this results in a partial list, the isPartial attribute will be set to true. none Yes
mode String This attribute instructs the web service to return a DataConstraint 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 No

Notes:

  • Default values do not need to be supplied if they are the last element in the path.
  • Operators can be used to refine the applicability of the c query parameter:
Operator Meaning Note
eq Equals Default if no operator is specified and there is only one value (e.g. c[FREQ]=M is equivalent to c[FREQ]=eq:M)
ne Not equal to  
lt Less than  
le Less than or equal to  
gt Greater than  
ge Greater than or equal to  
co Contains  
nc Does not contain  
sw Starts with  
ew Ends with  

Operators appear as prefix to the component value(s) and are separated from it by a : (e.g. c[TIME_PERIOD]=ge:2020-01+le:2020-12).

As already mentioned, the response from the Data Availability API is an SDMX DataConstraint containing a CubeRegion which defines the distinct Values for each Dimension of the data. These distinct values contained in the CubeRegion are determined by the server based on the data query presented to this API. The meaning of the distinct values depends on the response mode.

Response Mode

The API response to the data query depends on the mode the API is called with. mode is a query parameter to the API, and if not provided defaults to exact. Depending on the mode, the returned values represent either:

  • The distinct values which will be contained in the resultant dataset, should the data query be run against the Data API (mode=exact);
  • The valid future selections that could be passed to the Data API based on the current data query selections (mode=available).

To highlight the difference between the response mode, consider the following dataset.

Reference Area Employment Status Sex
UK EMP M
FR EMP M
FR UEMP F

The client calls the availability API with the query Reference Area=FR and Sex=F.

With mode=exact, the response is:

Dimension Values
Reference Area FR
Employment Status UEMP
SEX F

Mode exact has found only one series matches this query, and returned to the client the distinct values per dimension. In this case there is only one distinct value per dimension.

With mode=available, the response is:

Dimension Values
Reference Area FR
Employment Status UEMP
SEX M, F

Mode available has determined that the UK is no longer a valid selection. If the UK were chosen, no data would be returned for that Reference Area. If the user were to include Employment Status=EMP this would result in no data being returned at all. The difference in this mode is that the service has determined that SEX=M is a valid selection, if this was to be added to the data query it would result in more series being returned.

If the user was to add to their query Sex=M, the query becomes Reference Area=FR and Sex=M + F and the response would change as follows.

With mode=exact:

Dimension Values
Reference Area FR
Employment Status EMP, UEMP
SEX M, F

The service has detected two series that match the query criteria, and responded with the distinct code values for each dimension for those matches.

With mode=available:

Dimension Values
Reference Area UK, FR
Employment Status EMP, UEMP
SEX M, F

Reference Area UK has now become available, this is because if the user were to now select Reference Area=UK they would add additional series to the query response. In addition both Employment Status values are available. The Employment Status dimension currently has no query selections on it, this means the dimension has no filters imposed. The service has determined that the user can impose a filter for either EMP or UEMP and the inclusion of these filters will not result in an empty dataset being returned.

 

Temporal coverage

For DSDs that have a time dimension, temporal coverage can be included in the DataConstraint's ReferencePeriod element. The ReferencePeriod is used to indicate the earliest and latest observation dates available for the sub-cube of data based on the current data query.

This information may not be included in the response if the service does not have access to this information.

Metrics

The DataConstraint may define up to two additional Annotations used to capture the metrics for the number of series and the number of observations which will be returned if the data query presented to this API were run against the data API.

The Metrics annotations are attached to the DataConstraint, and have AnnotationType of sdmx_metrics an Id of series_count or obs_count depending on the metric being reported, and the annotation title is used to report the count, which is a positive integer value.

Metrics are only included if the service has the information available to provide the count. A request for metrics may include only series counts, or no metrics at all depending on the service.

Availability for a single dimension

If a client application is only interested in the data available for a single dimension of the dataset, for example if the client is building a code picker form for only the 'Reporting Country' dimension, then the client is able to specify that this using the componentId path parameter. If this is the case, the CubeRegion will only include information of the distinct values for the specified dimension.

Referenced structures

The client is able to include referenced structures used by the constraint by using the references parameter, for example if a dimension is coded, and references are returned, the dimension's codelist will be included in the response. Importantly the codelist will only include codes which are part of the constraint.

Included references are:

  • Dataflow - referenced directly by the constraint
  • Data Structure Definition - referenced by the dataflow
  • Codelist - which contain only the codes identified in the constraint, with any parent codes also included even if they are not included in the constraint
  • Concept Scheme - which contain only the concepts used by the constraint
  • Data Provider Scheme - which contain only the data providers who have provided data for the dataflow

 

Response types

The following media types can be used with availability queries:

  • application/vnd.sdmx.structure+json;version=2.0.0
  • application/vnd.sdmx.structure+xml;version=3.0.0
  • application/vnd.sdmx.structure+xml;version=2.1
  • application/vnd.sdmx.structure+json;version=1.0.0

The default format is highlighted in bold.

 

 

Data queries

Overview

Data queries allow retrieving statistical data. Entire datasets, individual observations, or anything in between, can be retrieved using filters on dimensions (including time), attributes and/or measures. All data matching a query can be retrieved or only the data that has changed since the last time the same query was performed. Using the includeHistory parameter, it is also possible to retrieve previous versions of the data. Last but not least, the data retrieved can be packaged in different ways (as time series, cross-sections or as a table), in a variety of formats (JSON, XML, CSV, etc.).

Syntax

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/data/{context}/{agencyID}/{resourceID}/{version}/{key}?{c}&{updatedAfter}&{firstNObservations}&{lastNObservations}&{dimensionAtObservation}&{attributes}&{measures}&{includeHistory}

Parameter Type Description Default Multiple values?
context One of the following: datastructure, dataflow, provisionagreement Data can be reported against a data structure, a dataflow or a provision agreement. This parameter allows selecting the desired context for data retrieval. * Yes
agencyID A string compliant with the SDMX common:NCNameIDType The agency maintaining the artefact for which data have been reported. * Yes
resourceID A string compliant with the SDMX common:IDType The id of the artefact for which data have been reported. * Yes
version A string compliant with the allowed SDMX versioning schemes The version of the artefact for which data have been reported. * Yes
key A string compliant with the KeyType defined in the SDMX Open API specification. The combination of dimension values identifying the slice of the cube for which data should be returned. Wildcarding is supported via the * operator. For example, if the following key identifies the bilateral exchange rates for the daily US dollar exchange rate against the euro, D.USD.EUR.SP00.A, then the following key can be used to retrieve the data for all currencies against the euro: D.*.EUR.SP00.A. Any dimension value omitted at the end of the Key is assumed as equivalent to a wildcard, e.g. D.USD is equivalent to D.USD.*.*.* * Yes
c Map Filter data by component value. For example, if a structure defines a frequency dimension (FREQ) and the code A (Annual) is an allowed value for that dimension, the following can be used to retrieve annual data: c[FREQ]=A. The same applies to attributes (e.g. c[CONF_STATUS]=F) and measures. Multiple values are supported, using a comma (,) as separator: c[FREQ]=A,M. The comma effectively acts as an OR statement (i.e. FREQ is A OR FREQ is M). The plus (+) can be used whenever an AND statement is required, such as for example, for attributes with multiple values or for time ranges. For example, to indicate that ATTR1 must either be A or (B AND M), use the following: c[ATTR1]=A,B+M. Operators may be used too (see table with operators below). This parameter can be used in addition, or instead of, the key path parameter. This parameter may be used multiple times (e.g. c[FREQ]=A,M&c[CONF_STATUS]=F), but only once per Component.   Yes
updatedAfter xs:dateTime The last time the query was performed by the client in the database. If this parameter 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).   No
firstNObservations Positive integer The maximum number of observations to be returned for each of the matching series, starting from the first observation   No
lastNObservations Positive integer The maximum number of observations to be returned for each of the matching series, counting back from the most recent observation   No
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 / table 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, or else, to default to AllDimensions. Depends on DSD No
attributes String This parameter specifies the attributes to be returned. Possible options are: dsd (all the attributes defined in the data structure definition), msd (all the reference metadata attributes), dataset (all the attributes attached to the dataset-level), series (all the attributes attached to the series-level), obs (all the attributes attached to the observation-level), all (all attributes), none (no attributes), {attribute_id}: The ID of one or more attributes the caller is interested in. dsd Yes
measures String This parameter specifies the measures to be returned. Possible options are: all (all measures), none (no measure), {measure_id}: The ID of one or more measures the caller is interested in. all Yes
includeHistory Boolean This parameter 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 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. false No

The following rules apply:

  • Multiple values for a parameter must be separated using a comma (,).
  • Two additional operators are supported for the version parameter: the +, to indicate the latest stable version of an artefact, and ~, to indicate the latest version of an artefact regardless of its status (draft vs. stable).
  • Default values do not need to be supplied if they are the last element in the path.
  • Operators can be used to refine the applicability of the c query parameter:
Operator Meaning Note
eq Equals Default if no operator is specified and there is only one value (e.g. c[FREQ]=M is equivalent to c[FREQ]=eq:M)
ne Not equal to  
lt Less than  
le Less than or equal to  
gt Greater than  
ge Greater than or equal to  
co Contains  
nc Does not contain  
sw Starts with  
ew Ends with  

Operators appear as prefix to the component value(s) and are separated from it by a : (e.g. c[TIME_PERIOD]=ge:2020-01+le:2020-12).

Response types

The following media types can be used with data queries:

  • application/vnd.sdmx.data+json;version=2.0.0
  • application/vnd.sdmx.data+xml;version=3.0.0
  • application/vnd.sdmx.data+csv;version=2.0.0;labels=[id|name|both];timeFormat=[original|normalized];keys=[none|obs|series|both]
  • application/vnd.sdmx.genericdata+xml;version=2.1
  • application/vnd.sdmx.structurespecificdata+xml;version=2.1
  • application/vnd.sdmx.generictimeseriesdata+xml;version=2.1
  • application/vnd.sdmx.structurespecifictimeseriesdata+xml;version=2.1
  • application/vnd.sdmx.data+json;version=1.0.0
  • application/vnd.sdmx.data+csv;version=1.0.0;labels=[id|both];timeFormat=[original|normalized]

The default format is highlighted in bold.

SDMX-CSV offers the possibility to set the value for two parameters via the media-type. These parameters are label and timeFormat; both are optional. The default values for these parameters are marked with * in the above media-type (i.e. id and original respectively). For additional information about these parameters, please refer to the SDMX-CSV specification.

 

Developers who update their local databases should make use of the updatedAfter parameter as it is likely to significantly improve performance. Instead of systematically downloading data that may not have changed, you would only receive the consolidated changes to be made in your database since the last time your client performed the same query.

An alternative, less efficient than the solution described above, but more efficient than downloading everything all the time, would be to use HTTP Conditional GET requests (i.e. the If-Modified-Since or If-None-Match HTTP Request headers). Using this mechanism, everything will be returned but only if something has changed since the previous query.

A sample response message is provided below. In the response the action attribute of the Dataset element is of importance whereas the validFromDate is just there for information purposes.

<?xml version="1.0" encoding="UTF-8"?>
<message:GenericData xmlns:message="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message" xmlns:common="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:generic="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/data/generic" xsi:schemaLocation="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message http://sdw-wsrest.ecb.europa.eu:80/vocabulary/sdmx/2_1/SDMXMessage.xsd http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common http://sdw-wsrest.ecb.europa.eu:80/vocabulary/sdmx/2_1/SDMXCommon.xsd http://www.sdmx.org/resources/sdmxml/schemas/v2_1/data/generic http://sdw-wsrest.ecb.europa.eu:80/vocabulary/sdmx/2_1/SDMXDataGeneric.xsd">
    <message:Header>
        <message:ID>388d1c9a-d187-4f6a-8792-e117cf34047f</message:ID>
        <message:Test>false</message:Test>
        <message:Prepared>2016-12-20T16:19:56.398+01:00</message:Prepared>
        <message:Sender id="ECB"/>
        <message:Structure structureID="ECB_RTD1" dimensionAtObservation="TIME_PERIOD">
            <common:Structure>
                <URN>urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=ECB:ECB_RTD1(1.0)</URN>
            </common:Structure>
        </message:Structure>
    </message:Header>
    <message:DataSet action="Replace" validFromDate="2016-12-20T16:19:56.398+01:00" structureRef="ECB_RTD1">[...]</message:DataSet>
    <message:DataSet action="Delete" validToDate="2016-12-20T16:19:56.440+01:00" structureRef="ECB_RTD1">[...]</message:DataSet>
</message:GenericData>

 

A sample response message is provided below. In the response the action & the validFromDate attributes of the Dataset element are both equally important. While the action attribute indicates what needs to be done, the validFromDate attribute allows defining the validity periods of the reported data.

<?xml version="1.0" encoding="UTF-8"?>
<message:GenericData xmlns:message="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message" xmlns:common="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:generic="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/data/generic" xsi:schemaLocation="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message http://sdw-wsrest.ecb.europa.eu:80/vocabulary/sdmx/2_1/SDMXMessage.xsd http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common http://sdw-wsrest.ecb.europa.eu:80/vocabulary/sdmx/2_1/SDMXCommon.xsd http://www.sdmx.org/resources/sdmxml/schemas/v2_1/data/generic http://sdw-wsrest.ecb.europa.eu:80/vocabulary/sdmx/2_1/SDMXDataGeneric.xsd">
    <message:Header>
        <message:ID>a2c99026-00c8-4f9a-a3d4-1891f89bd2b0</message:ID>
        <message:Test>false</message:Test>
        <message:Prepared>2016-12-20T17:16:51.578+01:00</message:Prepared>
        <message:Sender id="ECB"/>
        <message:Structure structureID="ECB_RTD1" dimensionAtObservation="TIME_PERIOD">
            <common:Structure>
                <URN>urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=ECB:ECB_RTD1(1.0)</URN>
            </common:Structure>
        </message:Structure>
    </message:Header>
    <message:DataSet action="Replace" validFromDate="2014-12-03T15:30:00.000+01:00" structureRef="ECB_RTD1">[...]</message:DataSet>
    <message:DataSet action="Replace" validFromDate="2015-06-02T15:30:00.000+02:00" structureRef="ECB_RTD1">[...]</message:DataSet>
    <message:DataSet action="Replace" validFromDate="2015-10-21T15:30:00.000+02:00" structureRef="ECB_RTD1">[...]</message:DataSet>
    <message:DataSet action="Replace" validFromDate="2016-06-01T15:30:00.000+02:00" structureRef="ECB_RTD1">[...]</message:DataSet>
    <message:DataSet action="Delete" validToDate="2014-11-05T15:30:00.000+01:00" structureRef="ECB_RTD1">[...]</message:DataSet>
</message:GenericData>

 

 

Metadata queries

By metadataset

Overview

These queries enable clients to find metadatasets by the identification of the metadataset, enabling clients to checkout specific reports.

Syntax

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/metadata/metadataset/{providerID}/{metadatasetID}/{version}?{detail}

Parameter Type Description Default Multiple values
providerID A string compliant with the SDMX common:NestedNCNameIDType for MetadataProvider The id of the data provider who maintains the Metadata Set. It is possible to set more than one id, using , as separator (e.g. UK1,UK2) * Yes
metadatasetID A string compliant with the SDMX common:NestedNCNameIDType for MetadataSet The Id of the Metadata Set to be returned. It is possible to set more than one id, using , as separator (e.g. MS1,MS2) * Yes
version A string compliant with the SDMX semantic versioning rules 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.7). * Yes
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 metadataset (i.e.: id, dataprovider id, version and name). Most notably, metadata attributes of a metadataset will not be returned Possible values are: (1) full: all available information for all returned metadatasets should be returned. (2) allstubs: all returned metadatasets should be returned as stubs, i.e. only containing identification information and the metadataset' name. full No

Notes:

  • Default values do not need to be supplied if they are the last element in the path.

 

By metadataflow

Overview

These queries enable clients to find metadatasets by the collection (metadataflow), optionally filtered by the metadata provider.

Syntax

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/metadata/metadataflow/{flowAgencyID}/{flowID}/{flowVersion}/{providerRef}?{detail}

Parameter Type Description Default Multiple values
flowAgencyID A string compliant with the SDMX common:NCNameIDType The agency maintaining the metadataflow for which metadata have been reported. * Yes
flowID A string compliant with the SDMX common:IDType The id of the metadataflow for which metadata have been reported. * Yes
flowVersion A string compliant with the VersionType defined in the SDMX Open API specification The version of the metadataflow for which data have been reported. * Yes
providerRef A string identifying the metadata 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 metadataset should be provided by the Swiss National Bank (CH2) or Central Bank of Norway (NO2): CH2+NO2. * Yes
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 metadataset (i.e.: id, dataprovider id, version and name). Most notably, metadata attributes of a metadataset will not be returned Possible values are: (1) full: all available information for all returned metadatasets should be returned. (2) allstubs: all returned metadatasets should be returned as stubs, i.e. only containing identification information and the metadataset' name. full No

Notes:

  • Default values do not need to be supplied if they are the last element in the path.

 

By structure

Overview

These queries enable clients to request all metadata sets which are reported against one or more structures, as such the syntax for defining which structures to find metadata for follows the same syntax as the structure resource.

Syntax

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/metadata/structure/{artefactType}/{agencyID}/{resourceID}/{version}?{detail}

Parameter Type Description Default Multiple values?
artefactType One of the following types: datastructure, metadatastructure, categoryscheme, conceptscheme, codelist, hierarchy, hierarchyassociation, valuelist, organisationscheme, agencyscheme, dataproviderscheme, dataconsumerscheme, organisationunitscheme, dataflow, metadataflow, reportingtaxonomy, provisionagreement, structuremap, representationmap, conceptschememap,categoryschememap, organisationschememap, process, categorisation, dataconstraint, metadataconstraint, transformationscheme, rulesetscheme, userdefinedoperatorscheme, customtypescheme, namepersonalisationscheme, vtlmappingscheme The type of structural metadata to be returned. * No
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). * Yes
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). * Yes
version A string compliant with the SDMX semantic versioning rules 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.7). ~ Yes
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 metadataset (i.e.: id, dataprovider id, version and name). Most notably, metadata attributes of a metadataset will not be returned Possible values are: (1) full: all available information for all returned metadatasets should be returned. (2) allstubs: all returned metadatasets should be returned as stubs, i.e. only containing identification information and the metadataset' name. full No

 

Response types

The following media types can be used with reference metadata queries:

  • application/vnd.sdmx.metadata+json;version=2.0.0
  • application/vnd.sdmx.metadata+xml;version=3.0.0
  • application/vnd.sdmx.metadata+csv;version=1.0.0
  • application/vnd.sdmx.genericmetadata+xml;version=2.1
  • application/vnd.sdmx.structurespecificmetadata+xml;version=2.1

The default format is highlighted in bold.