4.2. Get the metadata for selected datasets from multiple datasources.
GET and POST GetSelectedDatasets
Description: Get the metadata for specified datasets from one or more datasources.
API Usage: This endpoint uses 1 API call per 100 (or part thereof) datasets returned.
Please refer to section 8.2 for more details on API rate limits.
GET Sample Request:
GET https://[server]/GetSelectedDatasets?SessionToken=YOUR_SESSION_TOKEN&Series[]=ECBFX/EURGBP&Series[]=ECBFX/EURUSD
POST Sample Request:
POST https://[server]/GetSelectedDatasets
{
"SessionToken":"YOUR_SESSION_TOKEN",
"Series":[
{ "Datasource":"ECBFX", "Symbol":"EURGBP" },
{ "Datasource":"ECBFX", "Symbol":"EURUSD" }
],
"ValuesSince": "2001-01-30",
"ReturnAccess": 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
parameters to request. See the example above. The Series Datacategory parameter is required if the datasource is a CategoryDS datasource e.g: { “Datasource”:”AAAA”, “Datacategory”:”BB”, “Symbol”:”CCCCC” } See the Notes above for information about categoryDS datasources. |
Optional Request parameters.
| Parameter | Type | Default | Notes | |
| 3 | ShortRecord | Boolean | false | If true, the result does not contain the Description parameter and Additional object. |
| 4 | ValuesSince | String | “Earliest” | Only
return
datasets that have values after this
date. Use the word “Earliest” or a
date in “YYYY-MM-DD” format
e.g:
“ValuesSince”:”2018-01-01″. |
| 5 | ReturnAccess | Boolean | false | If true,
a UserAccess
object with information on
each dataset is returned. If the result dataset parameter Subscription is set to “None”, the UserAccess object is not returned as no subscription exists. In a CategoryDS datasource, the UserAccess object is located in the UserCategoryList object which is in the DetailsDS object. In a non CategoryDS datasource, the UserAccess object is located in the Details object. See the ‘UserAccess Object’ table below for more information. |
| 6 | DateFormat | String | “YYYY-MM-DD” | The date format to use in the request and result. See the ‘DateFormat Parameter‘ section below for details. |
- 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": ….
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’. |
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.
Response Parameters
| Parameter | Type | Mandatory | Description | |
|---|---|---|---|---|
| 1 | ServerDateTime | String | Yes | The server UTC date and time as an ISO 8601 string. |
| 2 | TimeStamp | Float | Yes | The server date and time as a Julian date. |
| 3 | ExecutionTime | Float | Yes | The number of milliseconds taken to process the request. |
| 4 | Result | [Object] | No* | If the request
is
a success, a Result
object is returned. See the ‘Result‘ table below for details. |
| 5 | Errors | [Object] | No* | If the request
fails, an 'Errors' object is
returned. See the ‘'Errors'‘ table below for details. |
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 | Description | |
|---|---|---|---|
| 1 | Metadata | [Object] | The datasource summary data. |
| 2 | Datasets | [Object] | The datasets returned. See the Datasets object below. |
Metadata Object
| Field name | Type | Description | |
|---|---|---|---|
| 1 | Datasets | Integer | The number of datasets in the result. |
| 2 | ShortRecord | Boolean | If true the result does not contain the Description parameter and Additional object. |
| 3 | ValuesSince | Date | Returns only datasets that have values since
this requested date. Use the word “Earliest” or enter a date in “YYYY-MM-DD” format e.g: “ValuesSince”:”2018-01-01″ |
Datasets Object
| Parameter | Type | Mandatory | Description | |
| 1 | Datasource | String | Yes | The datasource ID. |
| 2 | DataCategory | String | No | If true, this is a CategoryDS datasource (result ISCategoryDS is set to true) and the DataCategory result will contain the data category name. |
| 3 | Symbol | String | Yes | The dataset ID (market identifier, symbol, ID or code). |
| 4 | Name | String | Yes | Text 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 as an ISO three character currency code. |
| 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 date available for values in “YYYY-MM-DD” format. |
| 13 | EndDate | String | Yes | The most recent date available for values in “YYYY-MM-DD” format. |
| 14 | Values | Integer | Yes | Total number of value/price records in the dataset. |
| 15 | Corrections | Integer | Yes | The number of value/price corrections available for the dataset. |
| 16 | Premium | Boolean | Yes | If true, this is a premium subscription datasource that is not included gratis as part of a service. |
| 17 | Favorite | Boolean | Yes | If true, this dataset in the users favorite datasets list. |
| 18 | IsCategoryDS | String | 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 “NCategoryDS datasources” note above. |
| 19 | Subscription | String | Yes | 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. |
| 20 | UserAccess | [Object] | No | If
Subscription equals
“None” the UserAccess
object will not be returned in the
result. The UserAccess object contains details of the access allowed with the current subscription. See the “UserAccess Object” table below for details. |
| 21 | Additional | [Object] | No | The
Additional object allows more
dataset specific information to be
provided
as additional JSON
parameters. Please refer to any individual datasource documentation and the JSON returned 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”
}
]
}
|
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. |
- 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.
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 field is empty or too many rows requested (500 maximum). |
| 401 | Invalid access token. |
| 402 | Unauthorized. |
| 403 | No access allowed. |
| 404 | Unknown datasource or symbol. |
| 410 | Session Token expired. |
| 413 | Payload too large. |
This is not an exhaustive list and additional error codes may be returned. The Errors Detail field will return request specific error information.
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 local.
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
Sample Request:
GET https://[server]/GetSelectedDatasets?SessionToken=YOUR_SESSION_TOKEN&Symbol=ECBFX/EURCAD&Symbol=ECBFX/EURGBPXX Note: The Symbol 'EURGBPXX' is not valid and is requested only to show how an invalid symbol is handled.