TrendEconomy Open Data API

The TrendEconomy RESTful web service offers programmatic access to the statistical data and metadata disseminated via the TrendEconomy Statistical Data Warehouse.

It offers two modes of operation:

Data retrieval: You know the data you want to retrieve (e.g.: value of total exports from Ontario, Canada to Washington DC, USA in May 2018).
Data discovery: Using a metadata-driven approach, you want to discover the data exposed by the web service.

The web service complies with the SDMX 2.1 RESTful web service specification.

Concepts and codelists

In order to make sense of statistical data, we need to know the concepts associated with them. For example, on its own the figure 4,007,360 is pretty meaningless, but if we know that this is an trade value of total exports from Ontario, Canada to Washington DC, United States in April 2018, it starts making more sense.

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 code lists.

Data Structure Definitions

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

All the concepts that describe a particular domain (such as exchange rates or inflation) are grouped in a data structure definition (DSD).

Data

The measurement of some phenomenon (e.g. the figure 4,007,360 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. For example, all exchange rates for the US dollar against the euro can be measured on a daily basis and these measures can then be grouped together, in a so-called time series. Similarly, you can group a collection of observations made at the same point in time, in a cross-section (for example, the values of the US dollar, the Japanese yen and the Swiss franc against the euro at a particular date). Of course, these intermediate groupings are entirely optional and you may simply decide to have a flat list of observations.

Dataflows represent the data that covers 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.

The SDMX information model is much richer than this limited introduction, however the above should be sufficient to understand the basics of this web service. For additional information, please refer to the SDMX documentation.

Data discovery

All metadata can be retrieved using the query string described below.

protocol://wsEntryPoint/resource/agencyID/resourceID/version?detail=value&references=value&lang=value&format=value

protocol	The web service is available over `http`
wsEntryPoint	The web service entry point is available at the following location: `http://trendeconomy.com/rest/meta/`
resource	The following resources are supported by the web service, but please note that not all of them are used at the moment: dataflow datastructure conceptScheme codelist
agencyID	Organisations defining metadata are known as agencies in SDMX. In order to retrieve an artefact, you should know the identifier of its maintainer. TrendEconomy defines metadata for datastructures that are not defined by the provider (e.g. Canadian Customs Trade Statistics or World Bank WDI). For such metadata objects agencyID is TrendEconomy, for others - the identifier of the data & metadata provider.
resourceID	The identifier of the resource, such as CL_FREQ for the frequency codelist maintained by the ECB.
version	The version of the artefact to be returned. When the version number is not supplied, the latest version of the resource is returned.
detail	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), `referencestubs` (referenced artefacts should be returned as stubs) `full` (all available information for all artefacts should be returned). Если для заданных параметров agencyID, resourceID, version в хранилище находится более одного объекта resource, то заданное значение параметра игнорируется и считается равным `allstubs` . If there is more than one object of resource type in the warehouse (for given agencyID , resourceID , version) then the specified detail value is ignored and is considered equal to allstubs.
references	Using the `references` parameter, you can instruct 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). You can also retrieve 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. This is the default. `parents` : The artefacts that use the artefact matching the query (for example, the dataflows that use the data structure definition matching the query) will be returned. `parentsandsiblings` : The artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts will be returned. `children` : The artefacts referenced by the matching artefact will be returned (for example, the concept schemes and code lists used in a DSD). `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). If there is more than one object of resource type in the warehouse (for given agencyID , resourceID , version ) then the specified references value is ignored and is considered equal to `none` .
lang	Using the `references` parameter, you can instruct the web service to return text values (names and descriptions) in the given language. Possible values are: `en` : English. This is the default. `de` : German. `fr` : French. `ru` : Russian.
format	Using the `references` parameter, you can instruct the web service to return data in the specified format. Possible values are: `generic_2_0` : SDMX 2.0 (xml). this is the default. `xlsx` : Excel- file.

Data retrieval

All the data stored in the TrendEconomy Data Warehouse can be retrieved using the query string described below.

 protocol://wsEntryPoint/resource/flowRef/key?parameters

where parameters are defined as such:

 startPeriod=value&endPeriod=value&format=value

protocol	The web service is available over `http`
wsEntryPoint	The web service entry point is available at the following location: `http://trendeconomy.com/rest`
resource	The resource for data queries is `data`
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 In order to see the dataflows available in the TrendEconomy statistical data warehouse, a metadata query for all dataflows can be performed: `http://trendeconomy.com/rest/meta/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.
startPeriod endPeriod	It is possible to define a date range for which observations should be returned by using the `startPeriod` and/or `endPeriod` parameters. The values should be given according to the syntax defined in ISO 8601 or as SDMX reporting periods. The format will vary depending on the frequency. 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). `YYYY-W[01-53]` for weekly data (e.g.: 2013-W01). `YYYYMMDD` for daily data (e.g.: 20130101).
format	Using the `references` parameter, you can instruct the web service to return data in the specified format. Possible values are: `sdmx_2_0_compact` : SDMX 2.0 (xml). this is the default. `xlsx_time_series` : Excel- file containing time-series representation of data. `xlsx_flat` : Excel- file containing flat data table.