View source for Data Query Web Service

[[Category:WebService]]
= Overview =

The Data Query web service offers both a RESTful GET API which conforms the [https://github.com/sdmx-twg/sdmx-rest/blob/master/v2_1/ws/rest/docs/4_4_data_queries.md SDMX Specification], and a RESTful POST API which supports advanced features such as joining mulitple datasets and selecting lists of series.  Both the GET and POST web service support the SDMX standard parameters such as startPeriod and endPeriod, in addition to this, both APIs support advanced parameters to support features such as paging and calculations.

Both REST and POST APIs offer the same [[Category:SdmxDataFormat|data formats]] as valid reponse formats, this can be controlled via the '''format''' data query parameter, or by using the HTTP Accept Header.

This document describes the Syntax of both the GET and POST API.  Both APIs share the same Header Parameters and Query Parameters, as such these sections are applicable to both APIs.

= REST GET =
{| class="wikitable"
|-
|style="background-color:#eaecf0"|<b>Entry Point</b>|| <b> /ws/public/sdmxapi/rest</b>
|-
|style="background-color:#eaecf0"|<b>Access</b>|| <span style='color:green'><b>Public</b></span> 
|-
|style="background-color:#eaecf0"|<b>Http Method</b>|| GET
|-
|style="background-color:#eaecf0"|<b>Compression</b> || gzip supported
|-
|style="background-color:#eaecf0"|<b>Response Format</b>|| Determined by [[Data Formats|Accept Header]] - default SDMX 2.1 Structure Specific Data
|-
|style="background-color:#eaecf0"|<b>Response Statuses</b>|| <p><b>200</b> - Ok</p>
<p><b>400</b> - Bad URL Syntax</p>
<p><b>500</b> - Server Error</p>
|}


= HTTP Headers =
The Accept Header is used to define the output format, to transform the data to. The supported accept header values are

In addition, the following optional header parameters can be used to provide further details on the incoming dataset. If these details are not provided, the Fusion Registry will interrogate the dataset header to get the information. If the dataset is a non-SDMX format, or does not contain the required information in the header, then an error response will be returned.

{| class="wikitable"
|-
!|HTTP Header || Purpose || Allowed Values
|-
|style="background-color:#eaecf0"|<b>Accept</b>|| This can be used to define the response format of the data  || See [[Data_Formats#HTTP_Accept_Headers|Accept Headers]]

|-
|style="background-color:#eaecf0"|<b>Accept-Language</b> ||
 <p>This optional header can be used to set the locale to return any multilingual text in (names and descriptions). If the text does not exist in the specified locale, then the default rules will be applied to find the next best appropriate locale.
<p>
The corresponding locale parameter can be used to override this HTTP Header
 
|| Any valid locale, example: en
|}


= Standard HTTP Query Parameters =
The standard query paramters are supported by both GET and POST queries, and '''are''' part of the official [https://github.com/sdmx-twg/sdmx-rest/blob/master/v2_1/ws/rest/docs/4_4_data_queries.md SDMX API].

{| class="wikitable"
|-
! Request Parameter !! Purpose !! Allowed Values
|- 
| colspan="3" style="background-color:#d2f0ff" |  Parameters to restrict observations per series
|-
|style="background-color:#eaecf0"|<b>startPeriod</b> || Only return observations if the observation time if after the time specified || Any valid [[SDMX_Time_Formats|SDMX Time Format]]
|-
|style="background-color:#eaecf0"|<b>endPeriod</b>|| Only return observations if the observation time if before the time specified || Any valid [[SDMX_Time_Formats|SDMX Time Format]]
|-
|style="background-color:#eaecf0"|<b>lastNObservations</b>|| The last ‘n’ observations to return for each matched series || number
|-
|style="background-color:#eaecf0"|<b>firstNObservations</b>|| The first ‘n’ observations to return for each matched series || number 
|-
|style="background-color:#eaecf0"|<b>updatedAfter</b>|| Only return data if it was updated after the time specified || Any valid [[SDMX_Time_Formats|SDMX Time Format]]
|-
| colspan="3" style="background-color:#d2f0ff" |  Parameters to refine content 
|-
|style="background-color:#eaecf0"|<b>detail</b>|| Specifies the amount of information to be returned || 
'''full''' (default) – return the complete dataset<br/> 
'''dataonly''' – exclude attributes and groups <br/>
'''serieskeysonly''' – only include series, no observations<br/>
'''nodata''' – returns the groups and series, including attributes and annotations, without observations 
|-
|style="background-color:#eaecf0"|<b>includeHistory</b>|| When observation values have been revised over time, this parameter is used to include previous revisions || true/false
|-
| colspan="3" style="background-color:#d2f0ff" |  Parameters to change layout 
|-
|style="background-color:#eaecf0"|<b>dimensionAtObservation</b>|| Groups the data by one of the Dimensions of the DSD || 
'''AllDimensions''' - used to request the observations are not grouped by any dimension <br/>
''''dimension id'''' - used to group the observations by the specified dimenison id must be a valid Dimension Id for the DSD being queried<br/>
Note: This parameter is not supported by all output formats

|}

= Extended HTTP Query Parameters =
The Extended query paramters are supported by both GET and POST queries, and '''are not''' part of the official SDMX API.

{| class="wikitable"
|-
! Request Parameter !! Purpose !! Allowed Values
|- 
| colspan="3" style="background-color:#d2f0ff" |  Parameters to restrict observations per series
|-
|style="background-color:#eaecf0"| <b>obsLimit</b> || Limit with error if exceeded. Max number of obs that can be returned. HTTP response code of 413 (request entity too large) is returned if the query exceeds the limit || number
|-
|style="background-color:#eaecf0"| <b>seriesLimit</b> || Limit with error if exceeded. Max number of series that can be returned. HTTP response code of 413 (request entity too large) is returned if the query exceeds the limit || number
|-
|style="background-color:#eaecf0"| <b>max</b> || Limit for pagination, specifies the limit for the number of series, any additional series over this limit will not be returned || number
|-
|style="background-color:#eaecf0"| <b>offset</b> || Use with max to support pagination, the offset defines which series match to start writing || number
|- 
| colspan="3" style="background-color:#d2f0ff" |  Parameters for saving content
|-
|style="background-color:#eaecf0"| <b>saveAs</b> || If provided the response will be saved to a file with the given name.  The file name does not need to include the format postfix, however if .zip
is the type, the reponse will be in zip format
 || string
|-
|style="background-color:#eaecf0"| <b>prettyPrint</b> || XML formats only, if true the XML will be formatted for easy of readability || true/false
|- 
| colspan="3" style="background-color:#d2f0ff" |  Parameters for language
|-
|style="background-color:#eaecf0"| <b>locale</b> || Alternative to using the HTTP Accept-Langauge header. Locale is used to define which langauge to export labels in.
If the metadata does not include a label in the requested langauge, and alternative language is selected by the server. 
<p/>
For CSV formats the locale is also used to format numerical observation values
|| string
|-
| colspan="3" style="background-color:#d2f0ff" |  Calculating and transforming values
|-
| style="background-color:#eaecf0" | <b>calculatemeasure</b> || 
Creates a new Dimension to support the output of new calculated measures, including percentage change, and moving average
|| 
'''Syntax''': [Measure ID];[calculation 1];[calculation 2];[...]
<br/>
'''Example''': MEASURE;mvavg;pch  
|-
| style="background-color:#eaecf0" | <b>aggregate</b> || 
Removes one or more Dimensions from the output, collapsing multiple series and aggregating the values || 
'''Syntax''':  [DIM_ID ARRAY;AGGREAGATION FUNCTION;KEEP DIMENSIONS] <br/>
'''Example''': FREQ,REF_AREA;SUM;keep<br/>
'''Aggregation Functions:''' sum, mean, median, min, max, stddev, stddevsample, var, varsample, count<br/>
The Aggregation function is SUM if not provided<br/>
If 'keep' is not included the default behaviour is to remove the Dimensions in the given list, with keep only the Dimensions in the list are kept 
|-
| style="background-color:#eaecf0" | <b>completecube</b> || Fills in missing values for each series based on the start and end period of the data query for example if the data query states startPeriod=2008 but the data for one series starts at 2010, this manager will create a writer which completes the cube by either filling in with blank values, or one which is passed in on the parameter || true
|-
|style="background-color:#eaecf0"| <b>interpolate</b> || Derive values for periods with no data (uses linear interpolation) || linear
|-
|style="background-color:#eaecf0"| <b>normalisefreq</b> || Output all series in the given Frequency, even if the data is held in a different frequency, the aggregation function is used to convert frequencies || 
'''Syntax''': [FREQUENCY;AGGREGATION FUNCTION]<br/>
'''Example''': normalisefreq=A;SUM


|-
|style="background-color:#eaecf0"| <b>round</b> || Round observations to x decimal places.  The default behaviour is to ensure all observations meet the given number of decimal places by either rounding the excess, or filling missing with zero values.  For example rounding 1.232 to 2 would retun 1.23, however rounding to 4 would return 1.2320.  The behaviour can be changed so the round funciton is an upper limit, but values are not expanded to meet the limit  || 
Syntax: round=[decimal places;ROUND_FUNCTION;maxdp]<br/>
Example : round=2;halfup;maxdp
|}