6.1. Get historical time series values.

Get and POST GetValues

Description: Retrieve historical time series data for datasets in one or more datasource.

API Usage: This endpoint uses one API call per dataset requested. Please refer to section 8.2 for more details on API rate limits.

GET Sample Request:

                                                GET https://[server]/GetValues?SessionToken=YOUR_SESSION_TOKEN&Frequency=d&Series[]=ECBFX/EURUSD;BateIndex=[0,1];Prefill=true&StartDate=2016-01-01
                                                

                                                Hint: Objects (in green text) can be accessed using the format: Frequency=chm&AllowWeekends=on;FrequencyOptions=StartDay=1;EndDay=12;StartDay2=16;EndDay=31&fill=true

POST Sample Request:

POST https://[server]/GetValues

{
"SessionToken":"YOUR_SESSION_TOKEN",
"Series": [
        {"Datasource":"ECBFX", "Symbol":"EURGBP", "BateIndex":[0]},
        {"Datasource":"ECBFX", "Symbol":"EURUSD", "BateIndex":[0]}
],
"DateFormat":"YYYY-MM-DD", 
"StartDate":"2016-01-01",
"EndDate":"Latest",
"CommonStart":true, 
"Frequency":"hm",
"FrequencyOptions": {  
        "AllowWeekends":"on",
        "StartDay":1,
        "EndDay":15,
        "StartDay2":16,
        "EndDay2":31
},
"Fill":true
}

Request Parameters.

	Parameter	Type	Description
1	SessionToken	String	A session token from the GetSessionToken endpoint.
2	Series	[Object]	A list of Datasource [,Datacategory] and Symbol objects with optional parameters. See the ‘Series Object‘ table below for details.

Option request parameters

	Parameter	Type	Default	Description
3	StartDate	String	“Earliest”	The earliest date to return (use the word “Earliest” to return the first available date). See the DateFormat and Periods parameters below. Use the CommonStart parameter to select a common start date for all the series in the result.
4	EndDate	String	“Latest”	The latest date to return (use the word “Latest” to return the most recent date). See the DateFormat and Periods parameters below. Use the CommonEnd parameter to select a common end date for all the series in the result.
5	Periods	Integer	0	Instead of StartDate, Periods returns a requested number of most recent values (in the selected frequency) prior to the EndDate. Can be used to create ‘rolling’ reports where the the EndDate can change but the row count remains constant.
6	CommonStart	Boolean	False	If true, all returned datasets will have the latest common start date.
7	CommonEnd	Boolean	False	If true, all returned datasets will have the latest common end date.
8	CommonUA	Boolean	True	If true, the CommonStart and ComonEnd parameters above use the user permissioned access dates as the earliest and latest dates available. If false, the dataset start and end dates are used – which may cause no access values to be returned for dates where no access is allowed to the user. See the NAValue parameter below and the ‘“NA” (no access) values‘ section below for more information.
9	DateFormat	String	“YYYY-MM-DD”	The date format to use in the request and result. See the ‘DateFormat Parameter‘ section below for details.
10	DateOrder	String	“asc”	The date order for the result rows. There are 2 options, “asc” for ascending (the default) and “desc” for descending.
11	Prefill	Boolean	False	Fills missing values in the result. Prefill is calculated before the HandleWeekends parameter in FrequencyOptions. See also the Fill and PostFill parameters below. See the PrefillOptions parameter below for information on the available fill options.
12	PreFillOptions	[Object]		Fill options that affects result rows containing only null or only “NA” values. See the ‘Fill Options‘ table below for details on the available settings. Also, refer to the ‘Series object’ table below for individual series fill options.
13	Fill	Boolean	False	Fills missing values in the result. Fill is calculated after the HandleWeekends parameter in FrequencyOptions. See the FillOptions parameter s below for more details.
14	FillOptions	[Object]		Fill options that affects result rows containing only null or only “NA” values. See the ‘Fill Options‘ table below for details on the available settings. Also, refer to the ‘Series object’ table below for fill options for individual series.
15	Frequency	String	“d”	Calculate any average from day to year. See the FrequencyOptions parameter below for details.
16	FrequencyOptions	[Object]		Control how frequency averages are calculated. See the ‘FrequencyOptions‘ table below for more details .
17	PostFill	Boolean	False	Identical to the PreFill and Fill parameters above but calculated after the Frequency parameter. Not used on daily data. See the Fill and Prefill parameters above for more details.
18	PostFillOptions	[Object]		Fill options that affects result rows containing only null or only “NA” values. See the ‘Fill Options‘ table below for details on the available settings. Also, refer to the ‘Series object’ table below for fill options for individual series.
19	Sparse	Boolean		Allows the removal of result rows that contain only null values (removing only “NA” rows is optional). See the "SparseOptions" parameter below for details.
20	SparseOptions	[Object]		Allows the removal of result rows that contain only null values. You can also convert “NA” (no access) rows to nulls or remove “NA” only rows. See the "SparseOptions" table below for more details.
21	Rounding	String	“auto”	Round up or down the decimal values in the result. Rounding also affects spark values and corrections. Use with care as it can affect return value accuracy. See the ‘Rounding Parameter‘ table below for more details.
22	NAValue	Various	null	Set the value to use for “NA” (no access) records. Can be null, a number or a string. See the ‘“NA” (no access) values‘ section below for more details.
23	ReturnMetadata	Boolean	False	Return in the result the full dataset metadata. See the result ‘Metadata Object‘ table below for details.
24	ReturnAccess	Boolean	False	If true, a UserAccess object with the available range for each dataset is returned. For CategoryDS datasources, it is located in the UserCategoryList object (in the DetailsDS object). For non categoryDS datasources, it is located in the Columns object. See the ‘User Access Object’ table below for more details.
25	ReturnParameters	Boolean	True	If true, a Parameters object is returned in the Result object. It contains any request parameters (and default settings used).
26	CustomParameters	Boolean	True	If true, the API ignores user JSON parameters in the request which enables developers to store their own data as part of the request.
27	ReturnBateStatus	Boolean	False	If true, a BateStatus object is returned in the Series result parameter. It contains information about the bate and its status. See the ‘BateStatus Object‘ table in the result for more details.
28	IgnoreCategories	Boolean	False	If true, any CategoryDSdataset does not require its category name in the request. The API will return thefirst datasetthat matches the symbol. See the ‘ CategoryDS datasources‘ note below for more details.

Notes

Order of calculation is: Prefill, HandleWeekends, Fill, Frequency average, PostFill and Sparse.
Add weekends to ‘5 day week’ daily values in the result by setting HandleWeekends to ‘7’ or ‘7F’. See the ‘HandleWeekends Parameter’ table below.

Missing values

For dates with no published values, missing values are returned as null values e.g: “2017-12-25”: [ null, 62.37, 62.57 ]

“NA” (no access) values

Values that are in the dataset but to which the subscriber has no access are referred to as “NA” (no access) values. By default “NA” values are returned as null.
This default “NA” value can be changed using the optional request parameter “NAValue” and defining it to return a null, a number or a string (text in quotes).

E.g: “NAValue”: null or “NAValue”: -9999.99 or “NAValue”: “N/A”.

“NA” values use is controlled by the Fill Options/Type and the SparseOptions parameters.

CategoryDS datasources

A CategoryDS is a datasource whose datasets are grouped into data categories. The subscriber must be authorised to access each individual data category.
A CategoryDS is identified when the result object parameterIsCategoryDSis set to true.
TheDatacategoryparameter must be used in all data requests to a CategoryDS datasource UNLESS the request parameter ' IgnoreCategories' is set to true.
In GET requests Datasource, [Datacategory] and Symbol are combined into one 'Series' string.
e.g. Symbols[]=Datasource/[Datacategory]/Symbol&Symbols[] = ...
In POST requests, the data category is inserted between the datasource and the symbol
e.g. ” {“Datasource”:“AAA”, “Datacategory”:“BBB”, “Symbol”:“CCC”}, { "Datasource": ….

Series Object

The following parameters can be used in the ‘Series’ section of the request for each symbol.
Individual series object settings override any default settings or settings made in the main request body.

	Parameter	Type	Mandatory	Default	Description
1	Datasource	String	Yes		The datasource ID.
2	Datacategory	String	No*		The datasource category name used in ‘CategoryDS’ datasources only. See “Notes on CategoryDS datasources” above.
3	Symbol	String	Yes		The dataset ID (market identifier, symbol or code).
4	BateIndex	Array	No	All	The bate column numbers to be returned in result as an integer array.
5	LeadLag	Integer	No	0	A simple phase shift adjustment of the datasource data +/- a number of days. For example, a LeadLag of -3 would move all prices in the range back 3 days. It is often used to align the values of one dataset with another.
6	Prefill	Boolean	No	False	Fills missing values in the result. Prefill is calculated before the HandleWeekends parameter in FrequencyOptions. See also the Fill and PostFill parameters below. See the PrefillOptions parameter below for information on the available fill options.
7	Fill	Boolean	No	False	Fills missing values in the result. Fill is calculated after the HandleWeekends parameter in FrequencyOptions. See the FillOptions parameter s below for more details.
8	HandleWeekends	String	No	“auto”	Control how weekends are handled in the source data. See the ‘HandleWeekends Parameter’ table below for details.
9	Rounding	String	No	“auto”	How numeric values are formatted in the result. Refer to the Rounding request parameter above for details.

Notes

- - A CategoryDS is a datasource whose datasets are subdivided into data categories. See the ‘CategoryDS datasources‘ section above for details.
  - Order of calculation is: LeadLag, Prefill, HandleWeekends, Fill, and PostFill (there are no Frequency average or Sparse parameters in the series object).
  - The PreFill, Fill and PostFill are configured using the request PreFillOptions, FillOptions and PostFillOptions parameters. See the ‘Fill Options’ section below.

Frequency Parameter

Use a code below in the frequency parameter of the request to set the calculated frequency for ALL series.

	Code	Frequency	Description
1	“d”	Day	One value per day. A 5 day week is normally used unless any dataset in the request has weekend data. See the request FrequencyOptions parameter HandleWeekends for more detailed information.
2	“w”*	Week	By default a week runs from Monday to Sunday (ISO-8601). Many series do not have weekend values and end on Friday. A “Custom” week can be created by changing the request Frequency* parameter to “cw” and setting the day the week begins (1 is Monday and 7 is Sunday) using the week FrequencyOptions parameter StartDay. e.g. …&Frequency=cw;StartDay=1.
3	“hm”*	Half-month	Create two averages per month with the default ranges of days 1-15 and days 16 to 31 (end of month). A “Custom” half month can be created by changing the request Frequency* parameter to “chm” and selecting two custom half month ranges using the FrequencyOptions parameters: StartDay, EndDay, StartDay2 and EndDay2. The custom half month ranges can overlap (e.g. 1-16, 14-30). e.g. …&Frequency=chm; StartDay=1; EndDay=16; StartDay2=14; EndDay2=30.
4	“m”*	Month	A full calendar month. A “Custom” month can be created by changing the request Frequency* parameter to “cm” and selecting the days to use in the average using the FrequencyOptions parameters StartDay and EndDay. The range selected can extend to the following (next) month. For example to select the 16th of one month to the 15th of the following month you can select: …&Frequency=cm; StartDay=16; EndDay=15
5	“q”*	Quarter	Quarterly averages. There are four averages per year using months: 1-3, 4-6, 7-9 and 10-12. A “Custom” quarterly average can be created by changing the request Frequency* parameter to “cq” and setting the FrequencyOptions parameters using the custom “Month” settings above.
6	“hy”*	Half-year	Half year averages. Averages are for months 1-6 and 7-12. A “Custom” half year average can be created by changing the request Frequency* parameter to “chy” and setting the FrequencyOptions parameters using the custom “Month” settings above.
7	“y”*	Year	A full year of months 1-12. A “Custom” year average can be created by changing the request Frequency* parameter to “cy” and setting the FrequencyOptions parameters using the custom “Month” settings above.

FrequencyOptions Parameter

The following parameters can be used to adjust the default frequency settings for ALL series in the request.

	Parameter	Type	Mandatory	Default	Notes
1	HandleWeekends	String	No	“A”	How weekends are handled in the source data. See the ‘HandleWeekends Parameter‘ table below for details on how this can affect the dataset values.
2	AllowWeekends	String	No	“A”	Choose if calculated averages (not daily values) that can fall on weekends can return weekend dates in the result. Options are: 'auto', ‘on’ or ‘off’. See the ‘AllowWeekends Parameter‘ table below for details.
3	UseFirstDate	Boolean	No	False	Averages are normally returned with last date or the average period. Setting UseFirstDate to true will return the first date of the average period.
4	StartDay	Integer	No	1	For a week the value can be 1-7 (1 = Monday). For a month it is the first day of the month to be used. For a half-month it is the first day of the first period. Range is 1-31.
5	EndDay	Integer	No	31*	For month and half-month only. For month it defines the last day of the month. For half-month it defines the last day of the first period to use. Range is 1-31. The default is 31 for month and 15 for half month.
6	StartDay2	Integer	No	16	For custom half-month only. It is the first day of the second period of the calculation. Range is 1-31. The default is 16.
7	EndDay2	Integer	No	31	For custom half-month only. It is the last day of the second period in the calculation. Range is 1-31. The default is 31.

DateFormat Parameter

You can control the format of dates that are used in the request and returned in the result.

If used, the date separator is the character between the day, month and year values and can be one of 4 characters:

“–” – hyphen or dash
“/” – forward slash
“.” – dot or full stop
” ” – space

Format	Result Dates
“YYYY-MM-DD”	Formatted as 2018-01-22. (default).
“YYYY-DD-MM”	Formatted as 2018-22-01.
“YYYYMMDD”	Formatted as 20180122.
“YYYYDDMM”	Formatted as 20182201.
“MM-DD-YYYY”	Formatted as 01-22-2018.
“DD-MM-YYYY”	Formatted as 22-01-2018.
“EXCEL”	Formatted as numbers where 1/1/1976 = 27760.
“JULIAN”	Formatted as the number of days since ’12h Jan 1, 4713 BC’.

Note

In the examples above we use the “-” date separator character. You can replace this character with any of the other three separators characters. If you require 2 character years, replace “YYYY” with “YY” in the formats above.

Fill Options

This option works with all three fill options: Prefill, Fill and PostFill.
Some datasets have leading or trailing rows containing null or “NA” values. Null values mean there are no values in that dataset for the corresponding date. An “NA” value means that value may exist but the subscription does not allow access to it.
Please refer to the Sparse parameter and the " SparseOptions Parameter" table below for more how these values can be changed or removed.

The fill options allow control of how rows containing only null/”NA” values are filled.
The values to replace are defined in the Style parameter.

There are 5 fill options:

Option	Type	Default	Description
Leading	Boolean	False	If true, any leading missing values are filled using the previous valid value (prior to the selected start date) and applied using the selected Fill Type and the Style parameters. If no previous valid value exists then no leading fill is applied.
Trailing	Boolean	True	If true, trailing missing values after the last valid value are filled using the last valid value and applied using the selected Fill Type and the Style parameters. When the fill Type is ‘midpoint‘ or ‘interpolate‘, trailing filled values can only be calculated if there is a value available after the last selected date as this is necessary to calculate the midpoint or interpolate values.
Values	Boolean	True	Missing value rows between the first and last rows are filled to the right. Please refer to the Style and Trailing parameters in this table.
Style	String	“null”	Chose what values are to be filled. See the ‘Fill Style’ table below for details.
Type	String	“previous“	The type of fill calculation to be used. See the ‘Fill Type’ table below for details.

Fill Style

Choose what characters to treat as ‘missing values’ using the fill function. You can choose to fill: null (no values), “NA” (no access allowed) or both null and “NA” values.

Option	Description
“null”	Rows containing only missing (null) values are filled. This is the default setting.
“na'”	Rows containing only “NA” (no access) values are filled.
“both”	Rows containing both null and “NA” values are filled.

Fill Type

Missing values (matching the selected ‘Fill Style‘ above) can be filled in using one of the methods below.
Fill type is always “previous” for any leading and trailing fills.

Option	Description
“previous”	Missing values are filled by using the previous value (from oldest to newest). For example, if we had data values of 10, nul, nul, 13 then after a “previous” fill we would have the values: 10, 10, 10, 13.
“midpoint”	Missing values are replaced with a value mid value between the previous and next valid data points in the dataset. For example, if we had data values of 10, nul, nul, 13 then after a “median” fill we would have the values: 10, 11.5, 11.5, 13.
“interpolate”	Linear interpolation is a method of curve fitting using linear polynomials to create new data points in the dataset for missing values. For example, if we had data values of 10, nul, nul, 13 then after a “median” fill we would have the values: 10, 11, 12, 13.

Rounding Parameter

Used to control how numbers are formatted for values in the result. Rounding can be applied globally or to an individual series.
If the Rounding parameter is missing from the request, the default setting of “A” (or “auto”) is used.

Option	Description
“auto”	A decimal value defined in the datasource metadata is used. If none is present, the ‘off’ option below is used (default). Can be “A”, "a" or “auto”
“off”	Values are returned raw (as stored in the database).
Integer	An integer string value defining the number of decimal places to use in the result. e.g. “Rounding”:”4″.

Note

The Rounding option is used to display a formatted value and should not be used on a value that may later be used in a calculation as it may skew the result.

SparseOptions Parameter

The SparseOptions object allows you to define the missing and/or “NA” (no access) rows to remove from the JSON result.

A “missing value” row is a result row where there are no values available for the date.

An “NA” (no access) row is a row where there are values available for the date but your subscription does not allow you access.

Sparse is automatically applied to “NA” values. You can exclude “NA” values by setting the IncludeNA parameter below to false.

In this GetValues endpoint, sparse is applied to each series and applies to all the bate columns in each result row.

Due to JSON design limitations, both missing and “NA” values are returned as null. Use the request parameter NAValue parameter to change the returned “NA” value to a null, number or string. See the “ "NA" (no access) values” section above for more details.

The Sparse object has 5 options:

Option	Type	Default	Description
Leading	Boolean	True	Missing value rows before the first value are removed.
Trailing	Boolean	True	Null rows after the last value are removed.
Values	Boolean	True	Null rows between the first and last rows are removed.
IncludeNA	Boolean	True	Treat all NA (no access) rows as null value rows.
NAOnly	Boolean	False	Only “NA” (no access) rows are removed. See the notes below.

JSON example:

"SparseOptions":  {
"Leading":true,
"IncludeNA":true,
"Trailing":false
},

Notes

Select which rows to apply the sparse option to by using the Leading, Trailing and Values parameters above.
If parameter IncludeNA is true, the parameter NAOnly is ignored.
You can check the access that is available with your subscription by using a datasource or user favorites endpoint.

HandleWeekends Parameter

How weekends are handled in the datasets when their data is loaded.

There are 5 options:

Option	Description
“A”	Use weekends only if they are present in any of the result datasets. If there are no weekends in the datasets, a 5 day week is returned. However, if any dateset is returned with weekends, ALL datasets are returned with weekends. This is the default setting. Can be “A”, "a" or “auto”.
“5”	Any weekend values are deleted.
“5+”	Attempts a 5 day adjusted week by moving a valid (not null) weekend price forward to the next Monday but (by default) only if the Monday has no value. If present, the Sunday value is moved otherwise the Saturday value is moved. You can force the Monday value to be overwritten by appending the 'overwrite' command "/o" to the parameter ( e.g."5+/o").
“5-”	Attempts a 5 day adjusted week by moving a valid (not null) weekend price backward to the previous Friday but (by default) only if the Friday has no value. If present, the Sunday value is moved otherwise the Saturday value is moved. You can force the Friday value to be overwritten by appending the 'overwrite' command "/o" to the parameter ( e.g. '5-/o").
“7”	Add weekend dates with null values for weekends.
“7f”	Add weekend dates with the previous days valid value – not necessarily the Fridays value as it may be an “NA” also. If no valid previous value is available it remains unchanged.

AllowWeekends Parameter

Controls how weekends are returned in calculated average results. It does not affect the average calculation – only the dates returned.

If set to “on”, average result dates can include weekend dates if any average start date or end date falls on a weekend.
If set to “off" weekend result dates are adjusted to exclude weekends (Monday-Friday only). This normally means that if the period start date is used (See the FrequencyOptions parameter HandleWeekends) and it falls on a weekend it is adjusted forward to the Monday. Conversely, if the period end date falls on a weekend, it is adjusted backwards to the previous Friday. This keeps the values in the requested range.

There are 4 options:

Option	Description
“A”	Return weekend dates if they exist in the dataset average result. This is the default setting. Can be “A”, "a" or “auto”.
“on”	When set to “on”, average result dates can fall on weekends. Week averages are returned on Sunday *ISO-8601) and month averages are returned on the last day of the month (Monday to Sunday).
“off”	When set to “off”‘, average result dates will not include weekend dates (Monday to Friday days only). Result dates are adjusted to the correct Friday or Monday. Normal week averages are returned on Friday and month averages return on the last working day (Monday to Friday) of the month. For periods with a start and end date (custom month or half month for example), weekend start dates are adjusted forward to the Monday and weekend end dates are adjusted backwards to the Friday.

Response from the Server

Description	Type	Mandatory	Description
ServerDateTime	String	Yes	The server UTC date and time in ISO 8601 format.
TimeStamp	Float	Yes	The server date and time as a Julian date.
ExecutionTime	Float	Yes	Milliseconds taken to process the request.
Result	[Object]	No*	Result object as described in the ‘Result Object‘ table below.
Errors	[Object]	No*	Errors object as described in the ‘Errors Object‘ table below.

Notes

A successful API response will return a 'Result' object with the requested payload or an 'Errors' object detailing the issue that caused the error.

Result Object

Parameter	Type	Mandatory	Description
Parameters	Strings	No	Returns the request variable settings for each series in the request. See the ‘Parameters Object‘ section below for details.
Series	[Object]	Yes	A collection of series objects, one for each series in the request.

Parameters Object

The parameters object returns the request parameters including an array of all series in the request and any settings defined for each series in the request. Default settings that are not requested are also listed.

e.g:

"Parameters": {
"Series": [
{
"Datasource": "ECBFX",
"Symbol": "EURRUB",
"BateIndex": [0],
"Fill": false,
"HandleWeekends": "auto"
},
{ 
...
...
} 
],
"StartDate": "2017-01-01",
"EndDate": "Latest",
...
...
...          
"Periods": 0,
"WeekDays": 5
}

Notes

The lines containing “…” signify that there can be more series returned than shown above (one for each series in the request).

Series Object

Parameter	Type	Mandatory	Description
Datasource	String	Yes	The datasource ID.
Datacategory	String	No	The datasource category name. Used in CategoryDS datasources only (see notes below).
Symbol	String	Yes	The unique dataset ID (market identifier, symbol, ID or code).
Bates	Array	Yes	An array of dataset column names (like “High”, “Low”, “Close”…).
UserAccess	[Object]	No	If Subscription is not present or equals “None”, the UserAccess object will not be returned in the result. If requested (and present), the UserAccess object returns details of the access allowed with the current subscription. See the 'UserAccess Object' table below for details.
Metadata	[Object]	No	Information that describes the full dataset and its values and corrections.
BateStatus	[Object]	No	Detailed ‘bate’ information on each value column. Invalid bates or symbols are listed with a status code is not equal to 200 and a detail description. See the ‘BateStatus Object‘ table below for details.
Values	[Object]	Yes	A list of date and value records for the dataset (sorted by date). There is a value for each Bateindex column in the result. This can be empty '[]' if there are no values available for the selected bate/date range.
Corrections	[Object]	Yes	Any published corrected values for the result date range. See the ‘Corrections Object‘ table below.

UserAccess Object

If the user has (or had) a subscription to the datasource (or data category), the UserAccess object reports on the range allowed for the dataset with the current subscription.
The Starts and Ends parameters show the date range that the user can access.

Parameter	Type	Description
Starts	String	Date of the earliest available data for the current subscription.
Ends	String	Date of the latest available data for the current subscription.

Notes

There may be a greater range available in the datasource than the user has permission to access.
The UserAccess object is present only if request parameter ReturnAccess is set to true and Subscription is not equal to “None”.
The request parameter DateFormat controls the format of the result in the Starts and Ends parameters.

Metadata Object

The Metadata section describes each dataset in the Series object. Dates are returned in the default format “YYYY-MM-DD” unless requested in a different format.

	Parameter	Type	Mandatory	Description
1	Datasource	String	Yes	The datasource ID.
2	Datacategory	String	No	Only returned if this is a CategoryDS datasource (result ISCategoryDS is set to true). The Datacategory will contain the data category name.
3	Symbol	String	Yes	The unique dataset ID (market identifier, symbol, ID or code).
4	Name	String	Yes	A short text string describing the dataset.
5	Description	String	No	If available, additional data describing the dataset.
6	Frequency	String	Yes	The frequency ( day, week etc.) in which the data is reported.
7	Currency	String	Yes	The currency a unit the dataset is reported in. ISO three character currency codes are used.
8	Unit	String	Yes	The unit a dataset it reported ( MT, BBL, GALL etc).
9	Decimals	Integer	Yes	The recommended number of decimal places to use when displaying the dataset values.
10	Bates	Array	Yes	An array of price data column ‘bate’ names e.g: “Bid”,”Ask”, “High”,”Low”.
11	Bateindex	Array	Yes	An array of price data column numbers that correspond to the bates array above e.g: “BateIndex”: [ 0, 1, 2 ]
12	StartDate	String	Yes	The first available date in the dataset with a value.
13	EndDate	String	Yes	The last available date date in the dataset with a value.
14	Values	Integer	Yes	Total number of dataset values in the result.
15	Corrections	Integer	Yes	The number of value/price corrections available for the dataset.
15	Premium	Integer	Yes	If true, this is a premium subscription datasource that is not included gratis as part of a service.
16	Favorite	Boolean	Yes	True if this dataset is in the user favorites list.
17	IsCategoryDS	Boolean	Yes	True if the dataset is from a “CategoryDS” datasource. See notes below.
18	Additional	[Object]	No	The Additional object allows more dataset specific information to be provided as additional JSON parameters. Please refer to the datasource documentation and the raw JSON from the Additional object for more information. An example of conversion factors in the Additional object is: “Additional”: { “Conversions”: [ { “ConvertTo”: “BBL”, “ConvertOperator”: “/”, “ConvertValue”: “7.45” } ] }
19	Simulated	Boolean	No	Are the values and corrections are fictional and generated for demonstration purposes only. The Simulated parameter is only returned if it is set to true.
20	Subscription	Boolean	No	The Subscription parameter is only returned when the request parameter ReturnAccess is set to true. It returns the type of datasource access available with the current subscription. There are 4 options: “None”, “Active”, “Inactive” and “Simulated”. Please note that the option “Simulated” means that the values are fictional and are generated for demonstration purposes only.
22	Status	Integer	Yes	HTTP result code from server. A result of 200 equals success.
23	Detail	String	Yes	A string describing any Status parameter value.

Notes

The date format in the result can be changed using the request DateFormat parameter.A CategoryDS is a datasource whose datasets are subdivided into data categories. See the "CategoryDS Datasources‘ section at the top of this page for details.

BateStatus Object

Contains information for each value column.
Invalid bates or symbols that are listed with a status code is not equal to 200 have a detail description parameter containing information about the status code.

Parameter	Type	Mandatory	Description
Bate	String	Yes	The bate name or “Unknown” if the bate is not found.
BateNumber	Integer	Yes	Bate number in the bate index array. Bate 0 is first bate. A value of -1 is returned for an invalid bate.
FirstDate	String	Yes	The first date returned in the Series Values object from the request.
LastDate	String	Yes	The last date returned in the Series Values object from the request.
Values	Integer	Yes	The number of values records returned. See the ‘ Series Values Object‘ table below.
Corrections	Integer	Yes	The number of correction records returned. See the ‘Corrections Object’ table below.
LeadLag	Integer	Yes	A simple phase shift adjustment of the datasource values +/- a number of days. For example, a LeadLag of -3 would move all values in the range back 3 days. It is normally used to align the values of one dataset with another.
PreFill	Boolean	Yes	Missing values can be prefilled with values. See the Prefill parameter in request for details.
Fill	Boolean	Yes	Missing values can be filled with values. See the Fill parameter in request for details.
HandleWeekends	String	No	Control how weekends are handled in the source data. See the ‘HandleWeekends Parameter’ table above for details.
Simulated	Boolean	No	Are the values and corrections are fictional and generated for demonstration purposes only. The Simulated parameter is only returned if set to true.
Status	Integer	Yes	The HTTP result code from the server. A status of 200 equals success, 204 or 206 means full or partial access restrictions apply.
Detail	String	Yes	A string describing any error in the Status parameter above.

Note

Order of calculation is: LeadLag, Prefill, HandleWeekends, Fill, Frequency average, PostFill and Sparse.

Series Values Object

Contains the date/value records for the selected bate columns and date range. Can be empty '[]' if no values are available.

Parameter	Type	Mandatory	Description
Date	String	Yes	The date associated with the value.
Value(s)	double	Yes	One value for each column (can also be null).

Corrections Object

Will contain any corrections that apply to the values in the result for the date range returned. The metadata parameter CorrectionCount will also be greater than zero.

Parameter	Description
CorrectionDateTime	The date that the correction applies to.
IssuedDate	The data vendor published date (the date the correction was published).
InsertDateTime	The date and time the correction was inserted into the datasource.
Operation	“C” for correction or “‘X” for deletion.
From	The value before the correction.
To	The (new) corrected price.

Errors Object

	Parameter	Type	Mandatory	Description
1	Status	String	Yes	HTTP status code.
2	Detail	String	Yes	Description of the status code above.

Possible Status codes in the 'Errors' object

Code	Description
400	Datasource, category or symbol field is empty/missing.
401	Invalid session token.
402	Unauthorised.
403	Premium subscription required.
404	Unknown datasource or symbol.
410	Unknown session token.
413	Payload Too Large or over 500 symbols were requested.

Note

This is not an exhaustive list and additional error codes may be returned. The Errors object Detail field will return more result specific error information.

Possible HTTP response codes

You can get HTTP client network errors or server errors from any API request.
You should check with your network or IT colleagues in case the issue is a local one.
All server generated errors will return an 'Errors' object Detail field will give specific information about the error.
A full list of HTTP codes and their meanings is available here,

Success and fail examples

POST Sample Request:

https://[server]/GetValues


{
"Series":[
                {"Datasource":"ECBFX", "Symbol":"EURUSD","BateIndex":[0],"Fill":false,"HandleWeekends":"auto"},
                {"Datasource":"ECBFX","Symbol":"EURRUB","BateIndex":[0],"Fill":true,"HandleWeekends":"auto"}    
],
"StartDate":"2017-01-01",
"EndDate":"2017-01-04",
"CommonStart":false,
"CommonEnd":false,
"DateFormat":"YYYY-MM-DD",
"Frequency":"d",
"ReturnMetadata":true,
"ReturnParameters":false,
"ReturnBateStatus":true,
"ReturnAccess":true
}

Response body on success:

Response body on fail:

Last updated on April 20, 2024

Market Data Get Dataset ValuesRC