Contents

API reference

API reference

Some parts of the API are described on separate pages:

See also the Implementation notes.

Top-level methods and classes

Client([source, log_level])

Client for a SDMX REST web service.

Resource(value)

Enumeration of SDMX-REST API resources.

add_source(info[, id, override])

Add a new data source.

list_sources()

Return a sorted list of valid source IDs.

log

Top-level logger.

read_sdmx(filename_or_obj[, format])

Load a SDMX-ML or SDMX-JSON message from a file or file-like object.

read_url(url, **kwargs)

Request a URL directly.

to_pandas(obj, *args, **kwargs)

Convert an SDMX obj to pandas object(s).

to_xml(obj, **kwargs)

Convert an SDMX obj to SDMX-ML.
class sdmx.Client(source=None, log_level=None, **session_opts)[source]

Client for a SDMX REST web service.

Parameters

  • source (str or source.Source) – Identifier of a data source. If a string, must be one of the known sources in list_sources().

  • log_level (int) –

    Override the package-wide logger with one of the standard logging levels.

    Deprecated since version 2.0: Will be removed in sdmx version 3.0.

  • **session_opts – Additional keyword arguments are passed to Session.

get(resource_type=None, resource_id=None, tofile=None, use_cache=False, dry_run=False, **kwargs)[source]

Retrieve SDMX data or metadata.

(Meta)data is retrieved from the source of the current Client. The item(s) to retrieve can be specified in one of two ways:

  1. resource_type, resource_id: These give the type (see Resource) and, optionally, ID of the item(s). If the resource_id is not given, all items of the given type are retrieved.

  2. a resource object, i.e. a MaintainableArtefact: resource_type and resource_id are determined by the object’s class and id attribute, respectively.

Data is retrieved with resource_type=’data’. In this case, the optional keyword argument key can be used to constrain the data that is retrieved. Examples of the formats for key:

  1. {'GEO': ['EL', 'ES', 'IE']}: dict with dimension name(s) mapped to an iterable of allowable values.

  2. {'GEO': 'EL+ES+IE'}: dict with dimension name(s) mapped to strings joining allowable values with ‘+’, the logical ‘or’ operator for SDMX web services.

  3. '....EL+ES+IE': str in which ordered dimension values (some empty, '') are joined with '.'. Using this form requires knowledge of the dimension order in the target data resource_id; in the example, dimension ‘GEO’ is the fifth of five dimensions: '.'.join(['', '', '', '', 'EL+ES+IE']). CubeRegion.to_query_string() can also be used to create properly formatted strings.

For formats 1 and 2, but not 3, the key argument is validated against the relevant DataStructureDefinition, either given with the dsd keyword argument, or retrieved from the web service before the main query.

For the optional param keyword argument, some useful parameters are:

  • ‘startperiod’, ‘endperiod’: restrict the time range of data to retrieve.

  • ‘references’: control which item(s) related to a metadata resource are retrieved, e.g. references=’parentsandsiblings’.

Parameters

  • resource_type (str or Resource, optional) – Type of resource to retrieve.

  • resource_id (str, optional) – ID of the resource to retrieve.

  • tofile (str or PathLike or file-like object, optional) – File path or file-like to write SDMX data as it is recieved.

  • use_cache (bool, optional) – If True, return a previously retrieved Message from cache, or update the cache with a newly-retrieved Message.

  • dry_run (bool, optional) – If True, prepare and return a requests.Request object, but do not execute the query. The prepared URL and headers can be examined by inspecting the returned object.

  • **kwargs – Other, optional parameters (below).

  • dsd (DataStructureDefinition) – Existing object used to validate the key argument. If not provided, an additional query executed to retrieve a DSD in order to validate the key.

  • force (bool) – If True, execute the query even if the source does not support queries for the given resource_type. Default: False.

  • headers (dict) – HTTP headers. Given headers will overwrite instance-wide headers passed to the constructor. Default: None to use the default headers of the source.

  • key (str or dict) – For queries with resource_type=’data’. str values are not validated; dict values are validated using make_constraint().

  • params (dict) – Query parameters. The SDMX REST web service guidelines describe parameters and allowable values for different queries. params is not validated before the query is executed.

  • provider (str) –

    ID of the agency providing the data or metadata. Default: ID of the source agency.

    An SDMX web service is a ‘data source’ operated by a specific, ‘source’ agency. A web service may host data or metadata originally published by one or more ‘provider’ agencies. Many sources are also providers. Other agencies—e.g. the SDMX Global Registry—simply aggregate (meta)data from other providers, but do not provide any (meta)data themselves.

  • resource (MaintainableArtefact subclass) – Object to retrieve. If given, resource_type and resource_id are ignored.

  • version (str) – version> of a resource to retrieve. Default: the keyword ‘latest’.

Returns

The requested SDMX message or, if dry_run is True, the prepared request object.

Return type

Message or Request

Raises

NotImplementedError – If the source does not support the given resource_type and force is not True.

preview_data(flow_id, key={})[source]

Return a preview of data.

For the Dataflow flow_id, return all series keys matching key. Uses a feature supported by some data providers that returns SeriesKeys without the corresponding Observations.

To count the number of series:

keys = sdmx.Client('PROVIDER').preview_data('flow')
len(keys)

To get a pandas object containing the key values:

keys_df = sdmx.to_pandas(keys)
Parameters

  • flow_id (str) – Dataflow to preview.

  • key (dict, optional) – Mapping of dimension to values, where values may be a ‘+’-delimited list of values. If given, only SeriesKeys that match key are returned. If not given, preview_data is equivalent to list(client.series_keys(flow_id)).

Returns

Return type

list of SeriesKey

series_keys(flow_id, use_cache=True)[source]

Return all SeriesKey for flow_id.

Returns

Return type

list

session = None

Session for queries sent from the instance.

source = None

source.Source for requests sent from the instance.

sdmx.Request(*args, **kwargs)[source]

Compatibility function for Client.

New in version 2.0.

Deprecated since version 2.0: Will be removed in sdmx version 3.0.

class sdmx.Resource(value)[source]

Enumeration of SDMX-REST API resources.

Enum member

sdmx.model class

actualconstraint

ContentConstraint

agencyscheme

AgencyScheme

allowedconstraint

ContentConstraint

attachementconstraint

AttachmentConstraint

categorisation

Categorisation

categoryscheme

CategoryScheme

codelist

Codelist

conceptscheme

ConceptScheme

contentconstraint

ContentConstraint

data

DataSet

dataflow

DataflowDefinition

dataconsumerscheme

DataConsumerScheme

dataproviderscheme

DataProviderScheme

datastructure

DataStructureDefinition

organisationscheme

OrganisationScheme

provisionagreement

ProvisionAgreement

structure

Mixed.

customtypescheme

Not implemented.

hierarchicalcodelist

Not implemented.

metadata

Not implemented.

metadataflow

Not implemented.

metadatastructure

Not implemented.

namepersonalisationscheme

Not implemented.

organisationunitscheme

Not implemented.

process

Not implemented.

reportingtaxonomy

Not implemented.

rulesetscheme

Not implemented.

schema

Not implemented.

structureset

Not implemented.

transformationscheme

Not implemented.

userdefinedoperatorscheme

Not implemented.

vtlmappingscheme

Not implemented.
classmethod class_name(value: sdmx.rest.Resource, default=None) → str[source]

Return the name of a sdmx.model class from an enum value.

Values are returned in lower case.

classmethod from_obj(obj)[source]

Return an enumeration value based on the class of obj.

sdmx.add_source(info: Union[Dict, str], id: Optional[str] = None, override: bool = False, **kwargs) → None[source]

Add a new data source.

The info expected is in JSON format:

{
  "id": "ESTAT",
  "documentation": "http://data.un.org/Host.aspx?Content=API",
  "url": "http://ec.europa.eu/eurostat/SDMX/diss-web/rest",
  "name": "Eurostat",
  "supports": {"codelist": false, "preview": true}
}

…with unspecified values using the defaults; see Source.

Parameters

  • info (dict-like) – String containing JSON information about a data source.

  • id (str) – Identifier for the new datasource. If None (default), then info[‘id’] is used.

  • override (bool) – If True, replace any existing data source with id. Otherwise, raise ValueError.

  • **kwargs – Optional callbacks for handle_response and finish_message hooks.

sdmx.list_sources()[source]

Return a sorted list of valid source IDs.

These can be used to create Client instances.

sdmx.log = <Logger sdmx (WARNING)>[source]

Top-level logger.

New in version 0.4.

sdmx.read_sdmx(filename_or_obj, format=None, **kwargs)[source]

Load a SDMX-ML or SDMX-JSON message from a file or file-like object.

Parameters

  • filename_or_obj (str or PathLike or file) –

  • format ('XML' or 'JSON', optional) –

  • dsd (DataStructureDefinition) – For “structure-specific” format`=``XML` messages only.

sdmx.read_url(url, **kwargs)[source]

Request a URL directly.

sdmx.to_pandas(obj, *args, **kwargs)[source]

Convert an SDMX obj to pandas object(s).

See sdmx.writer.pandas.

sdmx.to_xml(obj, **kwargs)[source]

Convert an SDMX obj to SDMX-ML.

Parameters

kwargs – Passed to lxml.etree.to_string(), e.g. pretty_print = True.

Raises

NotImplementedError – If writing specific objects to SDMX-ML has not been implemented in sdmx.

format: SDMX file formats

This information is used across other modules including sdmx.reader, sdmx.client, and sdmx.writer.

class sdmx.format.Extra(value)

Bases: enum.IntFlag

Values for the extra field of Format.

ss = 1
ts = 2
sdmx.format.FORMATS = [Format(mime='application/vnd.sdmx.genericdata+xml;version=2.1', base='xml', data=True, meta=False, extra=0), Format(mime='application/vnd.sdmx.structurespecificdata+xml;version=2.1', base='xml', data=True, meta=False, extra=<Extra.ss: 1>), Format(mime='application/vnd.sdmx.generictimeseriesdata+xml;version=2.1', base='xml', data=True, meta=False, extra=<Extra.ts: 2>), Format(mime='application/vnd.sdmx.structurespecifictimeseriesdata+xml;version=2.1', base='xml', data=True, meta=False, extra=<Extra.ts|ss: 3>), Format(mime='application/vnd.sdmx.data+json;version=1.0.0', base='json', data=True, meta=False, extra=0), Format(mime='application/vnd.sdmx.data+csv;version=1.0.0', base='csv', data=True, meta=False, extra=0), Format(mime='application/vnd.sdmx.structure+xml;version=2.1', base='xml', data=False, meta=False, extra=0), Format(mime='application/vnd.sdmx.structure+json;version=1.0.0', base='json', data=False, meta=False, extra=0), Format(mime='application/vnd.sdmx.schema+xml;version=2.1', base='xml', data=False, meta=True, extra=0), Format(mime='application/vnd.sdmx.genericmetadata+xml;version=2.1', base='xml', data=True, meta=True, extra=0), Format(mime='application/vnd.sdmx.structurespecificmetadata+xml;version=2.1', base='xml', data=True, meta=True, extra=<Extra.ss: 1>)]

SDMX formats. Each record is an instance of Format, containing the following fields:

  • mime: the complete MIME type for the format.

  • base: the base MIME type or file format: one of “xml”, “json”, or “csv”.

  • data: True if this format contains (meta)data; False if it contains (meta)data structures.

  • meta: True if this format contains metadata (or metadata structures); False otherwise.

  • extra: an instance of Extra. Zero or more of:

    • ss: for structure-specific (meta)data.

    • ts: for time-series data.

class sdmx.format.Format(mime, base, data, meta, extra)

Bases: tuple

Structure of elements in FORMATS.

property base

Alias for field number 1

property data

Alias for field number 2

property extra

Alias for field number 4

property meta

Alias for field number 3

property mime

Alias for field number 0

sdmx.format.list_content_types(**filters)[source]

Return mime for each format in FORMATS matching filters.

SDMX-JSON

Information about the SDMX-JSON file format.

sdmx.format.json.CONTENT_TYPES = ['application/vnd.sdmx.draft-sdmx-json+json', 'draft-sdmx-json', 'text/json', 'application/vnd.sdmx.data+json;version=1.0.0', 'application/vnd.sdmx.structure+json;version=1.0.0']

Known media types for SDMX-JSON.

SDMX-ML

Information about the SDMX-ML file format.

sdmx.format.xml.CONTENT_TYPES = ['application/xml', 'text/xml', '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.structure+xml;version=2.1', 'application/vnd.sdmx.schema+xml;version=2.1', 'application/vnd.sdmx.genericmetadata+xml;version=2.1', 'application/vnd.sdmx.structurespecificmetadata+xml;version=2.1']

Known media types for SDMX-ML.

sdmx.format.xml.class_for_tag(tag)[source]

Return a message or model class for an XML tag.

sdmx.format.xml.qname(ns_or_name, name=None)[source]

Return a fully-qualified tag name in namespace ns.

sdmx.format.xml.tag_for_class(cls)[source]

Return an XML tag for a message or model class.

message: SDMX messages

Classes for SDMX messages.

Message and related classes are not defined in the SDMX information model, but in the SDMX-ML standard.

sdmx also uses DataMessage to encapsulate SDMX-JSON data returned by data sources.

class sdmx.message.DataMessage(*, header: sdmx.message.Header = <Header>   source:    test: False, footer: sdmx.message.Footer = None, response: Any = None, data: List[sdmx.model.DataSet] = [], dataflow: sdmx.model.DataflowDefinition = <DataflowDefinition (missing id)>, observation_dimension: Optional[Union[sdmx.model._AllDimensions, sdmx.model.DimensionComponent, List[sdmx.model.DimensionComponent]]] = None)[source]

Bases: sdmx.message.Message

Data Message.

Note

A DataMessage may contain zero or more DataSet, so data is a list. To retrieve the first (and possibly only) data set in the message, access the first element of the list: msg.data[0].

compare(other, strict=True)[source]

Return True if self is the same as other.

Two DataMessages are the same if:

Parameters

strict (bool, optional) – Passed to compare().

data: List[sdmx.model.DataSet]

list of DataSet.

dataflow: sdmx.model.DataflowDefinition

DataflowDefinition that contains the data.

observation_dimension: Optional[Union[sdmx.model._AllDimensions, sdmx.model.DimensionComponent, List[sdmx.model.DimensionComponent]]]

The “dimension at observation level”.

property structure

DataStructureDefinition used in the dataflow.

class sdmx.message.ErrorMessage(*, header: sdmx.message.Header = <Header>   source:    test: False, footer: sdmx.message.Footer = None, response: Any = None)[source]

Bases: sdmx.message.Message

footer: Optional[sdmx.message.Footer]

(optional) Footer instance.

header: sdmx.message.Header

Header instance.

response: Optional[Any]

requests.Response instance for the response to the HTTP request that returned the Message. This is not part of the SDMX standard.

class sdmx.message.Footer(*, severity: str = None, text: List[sdmx.model.InternationalString] = [], code: int = None)[source]

Bases: sdmx.util.BaseModel

Footer of an SDMX-ML message.

SDMX-JSON messages do not have footers.

code: Optional[int]
compare(other, strict=True)[source]

Return True if self is the same as other.

Two Footers are the same if their code, severity, and text are equal.

Parameters

strict (bool, optional) – Passed to compare().

severity: Optional[str]
text: List[sdmx.model.InternationalString]

The body text of the Footer contains zero or more blocks of text.

class sdmx.message.Header(*, error: str = None, extracted: datetime.datetime = None, id: str = None, prepared: datetime.datetime = None, reporting_begin: datetime.datetime = None, reporting_end: datetime.datetime = None, receiver: sdmx.model.Agency = None, sender: sdmx.model.Agency = None, source: sdmx.model.InternationalString =, test: bool = False)[source]

Bases: sdmx.util.BaseModel

Header of an SDMX-ML message.

SDMX-JSON messages do not have headers.

compare(other, strict=True)[source]

Return True if self is the same as other.

Two Headers are the same if their corresponding attributes are equal.

Parameters

strict (bool, optional) – Passed to compare().

error: Optional[str]

(optional) Error code for the message.

extracted: Optional[datetime.datetime]

Date and time at which the data was extracted.

id: Optional[str]

Identifier for the message.

prepared: Optional[datetime.datetime]

Date and time at which the message was generated.

receiver: Optional[sdmx.model.Agency]

Intended recipient of the message, e.g. the user’s name for an authenticated service.

reporting_begin: Optional[datetime.datetime]

Start of the time period covered by a DataMessage.

reporting_end: Optional[datetime.datetime]

End of the time period covered by a DataMessage.

sender: Optional[sdmx.model.Agency]

The Agency associated with the data Source.

source: sdmx.model.InternationalString
test: bool
class sdmx.message.Message(*, header: sdmx.message.Header = <Header>   source:    test: False, footer: sdmx.message.Footer = None, response: Any = None)[source]

Bases: sdmx.util.BaseModel

class Config[source]

Bases: object

arbitrary_types_allowed = True
compare(other, strict=True)[source]

Return True if self is the same as other.

Two Messages are the same if their header and footer compare equal.

Parameters

strict (bool, optional) – Passed to compare().

footer: Optional[sdmx.message.Footer]

(optional) Footer instance.

header: sdmx.message.Header

Header instance.

response: Optional[Any]

requests.Response instance for the response to the HTTP request that returned the Message. This is not part of the SDMX standard.

class sdmx.message.StructureMessage(*, header: sdmx.message.Header = <Header>   source:    test: False, footer: sdmx.message.Footer = None, response: Any = None, categorisation: sdmx.util.DictLike[str, sdmx.model.Categorisation] = None, category_scheme: sdmx.util.DictLike[str, sdmx.model.CategoryScheme] = None, codelist: sdmx.util.DictLike[str, sdmx.model.Codelist] = None, concept_scheme: sdmx.util.DictLike[str, sdmx.model.ConceptScheme] = None, constraint: sdmx.util.DictLike[str, sdmx.model.ContentConstraint] = None, dataflow: sdmx.util.DictLike[str, sdmx.model.DataflowDefinition] = None, structure: sdmx.util.DictLike[str, sdmx.model.DataStructureDefinition] = None, organisation_scheme: sdmx.util.DictLike[str, sdmx.model.AgencyScheme] = None, provisionagreement: sdmx.util.DictLike[str, sdmx.model.ProvisionAgreement] = None)[source]

Bases: sdmx.message.Message

add(obj: sdmx.model.IdentifiableArtefact)[source]

Add obj to the StructureMessage.

categorisation: sdmx.util.DictLike[str, sdmx.model.Categorisation]

Collection of Categorisation.

category_scheme: sdmx.util.DictLike[str, sdmx.model.CategoryScheme]

Collection of CategoryScheme.

codelist: sdmx.util.DictLike[str, sdmx.model.Codelist]

Collection of Codelist.

compare(other, strict=True)[source]

Return True if self is the same as other.

Two StructureMessages compare equal if DictLike.compare() is True for each of the object collection attributes.

Parameters

strict (bool, optional) – Passed to DictLike.compare().

concept_scheme: sdmx.util.DictLike[str, sdmx.model.ConceptScheme]

Collection of ConceptScheme.

constraint: sdmx.util.DictLike[str, sdmx.model.ContentConstraint]

Collection of ContentConstraint.

dataflow: sdmx.util.DictLike[str, sdmx.model.DataflowDefinition]

Collection of DataflowDefinition.

get(obj_or_id: Union[str, sdmx.model.IdentifiableArtefact]) → Optional[sdmx.model.IdentifiableArtefact][source]

Retrieve obj_or_id from the StructureMessage.

Parameters

obj_or_id (str or IdentifiableArtefact) – If an IdentifiableArtefact, return an object of the same class and id; if str, an object with this ID.

Returns

  • .IdentifiableArtefact – with the given ID and possibly class.

  • None – if there is no match.

Raises

ValueError – if obj_or_id is a string and there are ≥2 objects (of different classes) with the same ID.

objects(cls)[source]

Get a reference to the attribute for objects of type cls.

For example, if cls is the class DataStructureDefinition (not an instance), return a reference to structure.

organisation_scheme: sdmx.util.DictLike[str, sdmx.model.AgencyScheme]

Collection of AgencyScheme.

provisionagreement: sdmx.util.DictLike[str, sdmx.model.ProvisionAgreement]

Collection of ProvisionAgreement.

structure: sdmx.util.DictLike[str, sdmx.model.DataStructureDefinition]

Collection of DataStructureDefinition.

rest: SDMX-REST standard

Information related to the SDMX-REST web service standard.

sdmx.rest.RESPONSE_CODE = {200: 'OK', 304: 'No changes', 400: 'Bad syntax', 401: 'Unauthorized', 403: 'Semantic error', 404: 'Not found', 406: 'Not acceptable', 413: 'Request entity too large', 414: 'URI too long', 500: 'Internal server error', 501: 'Not implemented', 503: 'Unavailable'}

Response codes defined by the SDMX-REST standard.

session: Access SDMX REST web services

class sdmx.session.Session(timeout=30.1, **kwargs)[source]

requests.Session subclass with optional caching.

If requests_cache is installed, this class inherits from CachedSession and caches responses.

Parameters
Raises

TypeError – if requests_cache is not installed and any parameters are passed.

class sdmx.session.ResponseIO(response, tee=None)[source]

Buffered wrapper for requests.Response with optional file output.

ResponseIO wraps a requests.Response object’s ‘content’ attribute, providing a file-like object from which bytes can be read() incrementally.

Parameters

  • response (requests.Response) – HTTP response to wrap.

  • tee (binary, writable io.BufferedIOBase, defaults to io.BytesIO()) – tee is exposed as self.tee and not closed explicitly.

util: Utilities

class sdmx.util.DictLike(*args, **kwargs)[source]

Bases: dict, MutableMapping[sdmx.util.KT, sdmx.util.VT]

Container with features of a dict & list, plus attribute access.

compare(other, strict=True)[source]

Return True if self is the same as other.

Two DictLike instances are identical if they contain the same set of keys, and corresponding values compare equal.

Parameters

strict (bool, optional) – Passed to compare() for the values.

copy()[source]

Return a copy of the DictLike.

sdmx.util.compare(attr, a, b, strict: bool) → bool[source]

Return True if a.attr == b.attr.

If strict is False, None is permissible as a or b; otherwise,

sdmx.util.dictlike_field()[source]

Shorthand for pydantic.Field with DictLike default factory.

sdmx.util.only(iterator: collections.abc.Iterator) → Any[source]

Return the only element of iterator, or None.

sdmx.util.validate_dictlike(cls)[source]

Adjust cls so that its DictLike members are validated.

This is necessary because DictLike is a subclass of dict, and so pydantic fails to call __get_validators__() and register those on BaseModels which include DictLike members.

previous

Data sources

next

SDMX Information Model