6.3.  Get dataset values for one date

Get and POST GetValuesForDate

Description:  Get the values for a single date from datasets in one or more datasources. Can be used to create snapshot market reports showing values, averages, changes and sparkline charts.

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

GET Sample Request:

GET https://[server]/GetValuesForDate?SessionToken=YOUR_SESSION_TOKEN&Frequency=d&Series[]=ECBFX/EURGBP;BateIndex=[0];ReturnLatest=true&Series[]=ECBFX/EURUSD;BateIndex=[0];Rounding=2&Date=2017-10-24

POST Sample Request:

							POST https://[server]/GetValuesForDate
							{
								"AccessToken":"YOUR_ACCESS_TOKEN",
								"Series": [
									{"Datasource":"ECBFX", "Symbol":"EURGBP", "BateIndex":[0],"ReturnLatest":true},
									{"Datasource":"ECBFX", "Symbol":"EURUSD", "BateIndex":[0], "Rounding":"2"}
								],
								"Date":"2017-10-24",
								"ReturnLatest" : false,
								"SparksCount":6,
								"DateFormat","EXCEL"
							}

						

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.
3 Date String The request date for the returned values.

Optional request parameters

Field name Type Default Notes
4 ReturnLatest Boolean false If no is value available for the requested date then return the first prior (earlier) date that has a value.
5 ReturnCorrections Boolean true If any corrections are available for the requested date, they will be returned in the result Values object.
6 DateFormat String “YYYY-MM-DD” The date format to use in the request and the result. See the ‘DateFormat Parameter‘ section below.
7 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.
8 Frequency String “d” Calculate a average from day to year. See the ‘Frequency parameter‘ table below for details.
9 FrequencyOptions [Object] Control how frequency averages are calculated. See the ‘Frequency Options‘ table below for details.
10 SparksCount Integer The number of previous values before the request date. Can be used to create sparkline charts.
11 ReturnAccess Boolean false If true, a UserAccess object is returned in the result Series object.

It contains the dataset access allowed for the subscription. See the result ‘UserAccess Object’ table (in the result ‘Series‘ object) below for details.

12 ReturnBateNames Boolean false If true bate names (not bate index numbers) are returned in the values section of the result.
13 ReturnBateStatus Boolean false Return a BateStatus object in the Series result object which returns information about the bate and its status.
See the ‘BateStatus Object‘ table in the result for more details.
14 ReturnMetadata Boolean false Return the full dataset metadata. See the result ‘Metadata Object‘ table for details.
15 ReturnParameters Boolean false Return a Parameters object in the Result object containing any request parameters (and any default settings used).
16 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.
17 IgnoreCategories Boolean False If true, any CategoryDS dataset 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.
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 Notes
1 Datasource String Yes The datasource ID.
2 Datacategory String No* The data category name for CategoryDS datasources only (see the “CategoryDS datasources” note 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 HandleWeekends String No “auto” Control how weekends are handled in the source data. See the ‘HandleWeekends Parameter’ table below for details.
6 ReturnLatest Boolean No false If no value available on the requested date then use and return the previous date with a value.
7 Rounding String No “auto” How numeric values are formatted in the result. Refer to the Rounding request parameter above for details.

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.

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” 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.

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.

FrequencyOption Parameter

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

Parameter Type Mandatory Default Notes
1 HandleWeekends String No “A” How weekends are handled in the source data. Options are: ‘5’, ‘5w’, ‘7’, ‘7F’ and ‘auto’. Can be “A” or “auto”
See the ‘HandleWeekends Parameter‘ table below for details on how this can affect the dataset values.
2 AllowWeekends String No “A” Choose if averages that fall on weekends return weekend dates in the result. Can be “A” or “auto”
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.

HandleWeekends Parameter

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

There are 5 options:

Option Description
“5” Any weekend values are deleted.
“5a” Attempts a 5 day adjusted week by moving a valid (not null) weekend price forward to the Monday but only if the Monday has no value. If present, a valid Sunday value it is moved otherwise a valid Saturday value is moved.
“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.
“A” Use weekends only if they present in any of the result datasets. If there are no weekends in the datasets, a 5 day week is returned. This is the default setting. Can be “A” or “auto”.

AllowWeekends Parameter

Controls how weekends are returned in the average result. 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 FrequencyOption parameter AllowWeekends) 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 there are weekends in the dataset average result. This is the default setting. Can be “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 Monday and weekend end dates are adjusted backwards to the Friday.
Note

For averages with AllowWeekends parameter set to “on” or have a user defined custom frequency start and end date (e.g. custom month, half month), the start date is adjusted forward (to the Sunday) and the end date is adjusted backwards to the previous Sunday.

Response from the Server

Parameter Type Mandatory Description
1 ServerDateTime String Yes The server UTC date and time as an ISO 8601 string.
2 TimeStamp Float Yes Server date and time as a Julian date.
3 ExecutionTime Float Yes Milliseconds taken to process the request’.
4 Result [Object] No* Result object as described in table below’.
5 Errors [Object] No* Error details 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

The result Series object contains a list of unnamed ‘series’ objects, one for each series in the request.

Parameter Type Mandatory Description
Parameters [Object] No If requested, these show the request parameters (and the default settings used).
Series [Object] Yes The result body with the payload of values, user access, bate status and metadata.

Series Object

Parameter Type Mandatory Description
Datasource String Yes The datasource ID
Datacategory String No Only returned if this is a CategoryDS datasource (If Metadata parameter ISCategoryDS is true).
The Datacategory will contain the data category name.
Symbol String Yes The dataset ID (market identifier, symbol, ID or code).
Name String Yes A short text string describing the dataset.
Bates Array Yes An array of dataset column names (like “High”, “Low”, “Close”…).
BateStatus [Object] No Detailed ‘bate’ information on each data 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.
Metadata [Object] No If requested, a JSON object that describes the dataset including date range and its value count.
See the ‘Metadata Object‘ table below for details.
Values [Object] Yes The dataset values from the request. See the ‘Values‘ object table below for details.
Notes

CategoryDS datasources require a data category as well as a datasource as a symbol may not be unique to a single data category.
For more information on CategoryDS datasources, see “Notes on CategoryDS datasources” at the top of the page.


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 ID.
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 Values object.
LastDate String Yes The last date returned in the Values object.
Values Integer Yes The number of values records returned.
Corrections Integer Yes The number of correction records returned. See the ‘Corrections Object’ table below.
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.
Status Integer Yes The HTTP result code from the server. A status of 200 means success, 204 or 206 means full or partial access restrictions apply.
Detail String Yes A string describing the number in the Status parameter above.

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 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 If true, this dataset is in the user favorites list.
17 IsCategoryDS Boolean Yes If true, the datasource is a CategoryDS datasource. A CategoryDS is a datasource whose datasets are grouped in data categories. The user must be authorised to access individual data categories. See the ‘Notes on CategoryDS datasources‘ section at the top of this page.
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.
21 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.
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 ‘Notes on CategoryDS datasources‘ section at the top of this page.

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.

Values Object

The values object contains one or more ‘bate’ objects containing values returned, one for each bate in the request for the dataset. Each bate object can be named by the bate index number (default) or the bate name. The request parameter ReturnBateNames allows you to choose which is returned. In the example below we use bate names (“High” and “Low”).

Parameter Type Mandatory Description
Actual [Object] Yes Details about the actual returned value. See the ‘ActualObject‘ table below.
Previous [Object] Yes Details about the previous value (the value prior to the actual returned value). See the ‘Previous’ object table below.
Example:

Actual Object

Details about the actual value that was returned.

Parameter Type Mandatory Description
Bate String Yes Information that describes bate column returned. E.g. ‘Open’, ‘High’, ‘Low’.
Date String Yes The returned date as a string in the requested format*.
Value Double Yes The value returned for the result date**.
Status Integer Yes HTTP error number (200 for success). See the Detail field for a description of the Status code.
Detail String Yes Text describing the Status code.
Sparks Array No If the request SparksCount is greater than zero, it returns a CSV string containing a number of values prior to the result date.
If the request SparksCount is zero, the Sparks parameter is not returned
The Sparks array can contain nulls if no values available in the previous values range. e,g. “Sparks”: [109.22, 107.92, null, 108.86 ]
CorrectionCount Integer Yes The number of corrections included in the Actual object result.
Corrections [Object] No A Corrections object containing any corrections available for the requested date.
Only available if request parameter ReturnCorrections is true and CorrectionCount is greater than zero.
See the ‘CorrectionsObject‘ table below.

*If the request parameter ReturnLatest is set to true and no value is available for the request date, the value for the previous date that has a value is returned.
**The value can be null if there is no value in datasource for the requested date, or if no access is allowed with the current credentials.
*** Status/detail will show 206 “Partial access only to this data series” if the user has only partial access to the dataset.

Previous Object

Details about the previous value that was returned. The request parameter ReturnLatest’ does not apply to the Previous value

Parameter Type Mandatory Description
Date [Object] Yes The date returned in the result. It is the date for the value prior to the Date in the ‘Actual’ object.
Value Double Yes The value returned for the previous date**.
Status Integer Yes HTTP error number (200 for success). See the Detail field for a description of the Status code.
Detail String Yes Text describing the Status code.
CorrectionCount Integer Yes The number of corrections included in the Previous object result.
Corrections [Object] No A Corrections object containing any corrections available for the requested date.
Only available if request parameter ReturnCorrections is true and CorrectionCount is greater than zero.
See the ‘CorrectionsObject‘ table below.
*If the request parameter ReturnLatest is set to true and no value is available for the request date, the value for the previous date with a valid value is returned.
**The value can be null if there is no value in datasource for the requested date or if no access is allowed with the current credentials.
*** Status/detail will show 206 “Partial access only to this data series” if the user has only partial access to the dataset.

Corrections Object

Will contain any corrections that apply to the values in the result for the date range returned. The ‘Actual‘ or ‘Previous‘ object will have a CorrectionCount value 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 Description
1 Status Integer HTTP status code.
2 Detail String Description of the status code above.

Possible Status codes in the 'Errors' object

Code Description
400 Datasource, Datacategory or Symbol field is invalid.
401 Invalid access token.
403 Unauthorized.
403 Invalid date requested.
404 Unknown datasource, category or symbol.
413 Payload too large or too many series in the request.

Possible HTTP response codes

This endpoint returns 200 for success.
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 that will give specific details about the error.
A full list of HTTP codes and their meanings is available here,

Success and fail examples

							https://[server]/GetValuesForDate
								
							{ 
								"SessionToken":"YOUR_ACCESS_TOKEN",
								"Series": [
									{"Datasource":"ECBFX", "Symbol":"EURGBP", "BateIndex":[0],"ReturnLatest":true},
									{"Datasource":"ECBFX", "Symbol":"EURUSD", "BateIndex":[0], "Rounding","2"  }
								],
								"Date":"2017-10-24",
								"ReturnLatest" : false,
								"SparksCount":6,
								"Rounding ":"4 
							}

Response body on success (with simulated correction):

							{
								"ServerDateTime": "2019-10-02T10:15:18Z",
								"TimeStamp": 2458758.92729,
								"ExecutionTime": 0.019,
								"Result": [
									{
										"Datasource": "ECBFX",
										"Symbol": "EURGBP",
										"Values": {
											"0": {
												"Actual": {
													"Bate": "Close",
													"Date": "2017-09-25",
													"Value": 0.88,
													"Corrected": 0,
													"Corrections": [
														{
															"CorrectionDateTime": "2015-05-29 02:31:00",
															"IssuedDate": "2017-09-29",
															"InsertDateTime": "2017-09-29 15:45:44",
															"Operation": "C",
															"Value": 0.84,
															"CorrectedTo": 0.88
														}
													"Simulated": false,
													"Status": 200,
													"Detail": "Success",
													"Sparks": [ 0.88,0.88,0.88,0.88,0.88,0.88 ]
												},
												"Previous": {
													"Date": "2017-09-26",
													"Value": 0.88,
													"Corrected": 0,
													"Simulated": false,
													"Status": 200,
													"Detail": "Success"
												}
											}
										}
									},
									{
										"Datasource": "ECBFX",
										"Symbol": "EURUSD",
										"Values": {
											"0": {
												"Actual": {
													"Bate": "Close",
													"Date": "2017-10-24",
													"Value": null,
													"Status": 204,
													"Detail": "No value for the date",
													"Sparks": [ 0.884, 0.882,  0.876, 0.876, 0.878, 0.879 ]
												},
												"Previous": {
													"Date": "2017-09-25",
													"Value": 1.1900,
													"Corrected": 0,
													"Simulated": false,
													"Status": 200,
													"Detail": "Success"
												}
											}
										}
									}
								]
							}

Response body on fail:

Last updated on April 20, 2024