RESTful web services

The OSP SDMX 2.1 RESTful web service offers programmatic access to the statistical data and metadata disseminated via the OSP Database of Indicators. The web service complies with the SDMX 2.1 RESTful web service specification.

It offers two modes of requests:

  • Data retrieval (data queries): You know the data you want to retrieve.
  • Data discovery (structural metadata queries): Using a metadata-driven approach, you want to discover the data exposed by the web service.

The response message provided in two different formats:

  • XML format for the exchange of SDMX-structured data and metadata.
  • JSON format for the dissemination of SDMX-structured data and metadata on the web. JSON data message combines structure (e.g. dimensions and attributes) and data (observation and attribute values) in the same message.

In general, every response message in SDMX follows common format of:

  • Header
  • Payload (0..n)
  • Footer (0..1)

Payload is specific functionality of the messages. The footer is used to convey any error, information, or warning messages.

SDMX information model overview

Let's first start with a brief introduction of the SDMX information model.

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.

There are two types of concepts: dimensions and attributes. Dimensions, when combined, allow uniquely identifying statistical data. Attributes, on the other hand, do not help identifying statistical data, but they add useful information (like the unit of measure or the number of decimals). Dimensions and attributes are known as "components".

The measurement of some phenomenon (e.g. the figure 1.2953 mentioned above) is known as an "observation" in SDMX. Observations are grouped together into a "data set". However, there can also be an intermediate grouping (series and groups). These intermediate groupings are entirely optional and you may simply decide to have a flat list of observations in your data set.

The SDMX information model is much richer than this limited introduction; however, the above should be sufficient to understand the sdmx-json format. For additional information, please refer to the SDMX documentation.

Data queries

The format for creating a data REST request is:

protocol://ws-entry-point/resource/flowRef/key/providerRef?queryStringParameters,

where:

  • protocol – the web service is available over https
  • ws-entry-point – the web service entry point is available at the following location: osp-rs.stat.gov.lt/rest_xml or osp-rs.stat.gov.lt/json_xml
  • resource – the resource for data queries is data
  • flowRef – a reference to the dataflow describing the data that needs to be returned. The syntax is: <AGENCY_ID>, <FLOW_ID>, <VERSION> or <AGENCY_ID>, <FLOW_ID> or <FLOW_ID>, where AGENCY_ID is identifier of the agency maintaining the dataflow, FLOW_ID is the identifier of the dataflow and VERSION is the dataflow version.
  • key – key of the series to be returned. Parameter not supported at this time. Always return all data.
  • providerRef – data provider. Parameter not supported at this time.
  • queryStringParameters – only parameters startPeriod and endPeriod are supported at this time. The supported formats are:
    - YYYY for annual data (e.g.: 2013).
    - YYYY-S[1-2] for semi-annual data (e.g.: 2013-S1).
    - YYYY-Q[1-4] for quarterly data (e.g.: 2013-Q1).
    - YYYY-MM for monthly data (e.g.: 2013-01).

Examples:

Structural metadata queries

The format for creating a structural metadata REST request is:

protocol://ws-entry-point/resource/agencyID/resourceID/version?queryStringParameters,

where:

  • protocol – the web service is available over https
  • ws-entry-point – the web service entry point is available at the following location: osp-rs.stat.gov.lt/rest_xml
  • resource – the following resources are supported by the web service at this time: dataflow or datastructure
  • agencyID – the identifier of the agency maintaining the artefact. Values all by default.
  • resourceID – the identifier of the resource. Values all by default.
  • version – the version of the artefact to be returned. Always the latest at this time.
  • queryStringParameters – the parameters are not supported

Examples:

Known limitations and implementation details

The following are a list of known limitations at this time. Please be advised that as the standard evolves the list of limitations will be updated to reflect new features.

  • Only anonymous queries are supported, there is no authentication.
  • Each response is limited to 1 000 000 observations.
  • Maximum request URL length is 1000 characters.
  • The response provided only in SDMX-ML 2.1 generic schema or SDMX-JSON, which supports the SDMX 2.1 Information Model.
  • Supports only flat data sets. The intermediate groupings of data set observations (series and groups) not supported.
  • Compression should be enabled using the appropriate HTTP Header field (Accept- 469 Encoding).
  • Versioning is not supported: always the latest implemented version is used.
  • The optional data request path parameters key (=all) and providerRef (=all) are not supported.
  • The optional data request parameters updatedAfter, firstNObservations, lastNObservations, dimensionAtObservation (=AllDimensions), detail (=full) and includeHistory (=falsel) are not supported.
  • The optional structural metadata request parameters detail (=full), references (=parentsandsiblings) are not supported.