3.1.   Return the metadata for one datasource.

Get and POST GetDatasource

Description:   Return the metadata for one named datasource.

API Usage:   This endpoint uses zero API calls. Please refer to section 8.2 for more details on API rate limits.

GET Sample Request:

 GET https://[server]/GetDatasource?SessionToken=YOUR_SESSION_TOKEN&Datasource=ECBFX

POST Sample Request:

POST https://[server]/GetDatasource
						{
							"SessionToken":"YOUR_SESSION_TOKEN",
							"Datasource":"IEO-COMM",
							"ReturnCategoryList":false, 
							"DateFormat":"YY-MM-DD",
							"ReturnCategoryTree":false,
							"ReturnAccess": true
						}


Request Parameters

Parameter Type Description
1 SessionToken String A session token from the GetSessionToken endpoint.
2 Datasource String The datasource ID.

Optional Request parameters

Parameter Type Default Description
3 ReturnCategoryList Boolean True If true (and available for the datasource), returns a list of all available data categories in each datasource. See the ‘Details Object’ and ‘DetailsDS Object’ tables below for details.
4 ReturnCategoryTree Boolean True If true (and available for the datasource), returns a hierarchical data tree of available data categories in each datasource. Some non CategoryDS datasources may return a “Category” style tree that can be used to organise the data using symbol lists or wildcard symbols.
See the “Notes on CategoryDS datasources” below and ‘Details Object’ and ‘DetailsDS Object’ tables for details.
5 ReturnUserCategoryList Boolean True Note: For CategoryDS datasources only (see notes below).
Returns in the DetailsDS object a list of data categories and date ranges that the user can access. This parameter also controls if the result parameter UserCategoryCount is returned.
See the “CategoryDS datasources” below and the DetailsDS table below for details.
6 ReturnAccess Boolean False If true, returns subscription information about the datasources (or data categories in a CategoryDS datasource) that the user can access. The access information is returned as a Subscription string and a UserAccess object.

In a CategoryDS datasource, the access information is located in the UserCategoryList object (in the result DetailsDS object). This requires that the request parameter ReturnUserCategoryList be set to true.
In a non CategoryDS datasource, the UserAccess object is located in the Details object.

See the UserAccess parameter in the ‘Details Object’ and ‘DetailsDS Object’ tables below.
7 DateFormat String “YYYY-MM-DD” The date format to use in the request and the result. See the ‘DateFormat Parameter‘ section below for 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": ….

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.

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 to process the request.
4 Result [Object] No* A Result object as described in table below.
5 Errors [Object] No* An 'Errors' object as described in table below.
Note

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

Contains a number of objects, each one describing a datasource.

Parameter Type Mandatory Description
1 Datasource String Yes The datasource ID.
2 Name String Yes A text string that describes the datasource.
3 LastUpdated Datetime Yes The UTC date and time that the datasource was updated on the server.
Returned as an ISO 8601 string.
4 Premium Boolean Yes If true, this is a premium subscription datasource that is not included gratis as part of a service.
5 HasDataTree Boolean Yes If true, the datasource has an additional JSON tree that can be used to structure and filter its datasets.
6 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 “CategoryDS datasources” above.
7 Details [Object] No* Available only if this is not a CategoryDS datasource (see parameter IsCategoryDS above). It returns details about the datasets in the datasource.
See the ‘Details Object’ table below for more details.
8 DetailsDS [Object] No* Available only if this is a CategoryDS datasource (if parameter IsCategoryDS is true). It returns details about the datasets in the datasource.
See the ‘DetailsDS Object’ table below for more details.
9 Logo String Yes Link to a logo image for the datasource.
10 Description String Yes Additional data describing the datasource in more detail.
Note

If the result parameter IsCategoryDS is set to true, the result will contain a DetailsDS object otherwise, it will contain a Details object.

Details Object

Note

The Details object is returned if the datasource is not a CategoryDS datasource (if result parameter IsCategoryDS is false).

Parameter Type Mandatory Description
1 SeriesCount Long Yes The number of symbols in the datasource.
2 StartDate String Yes The first available date for any dataset.
3 EndDate String Yes The last available date for any dataset.
4 CategoryTree [Object] No The CategoryTree object can only returned when the request parameter ReturnCategoryTree is set to true.
If available, it returns a hierarchical JSON tree of both category groups and items.
Data categories are used to organise data series – often by region, market, product type or instrument class.
In a non CategoryDS datasource, categories are virtual and user access to datasets is not restricted by data category.
Please see the CategoryTree parameter in the DetailsDS table below.
5 CategoryList [Object] No The CategoryList object can only returned when the request parameter ReturnCategoryList is set to true.
If available, it returns a list of CategoryItem objects, each one describing a category from the datasource.
See the CategoryTree parameter above and the ‘CategoryItem Object‘ table below for details.
6 Subscription String 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 “Simulated” option means that the values are fictional and are generated for demonstration purposes only.
7 UserAccess [Object] No The details of the access allowed to the datasource with the current subscription.
The UserAccess object is only returned when the request parameter ReturnAccess is set to true and Subscription is not equal to “None”. See the request parameter ReturnAccess above and the “UserAccess Object” table below for more details.
Category Trees in Non CategoryDS datasources

Categories Trees are TSV (tab seperated value) files that add structure to databases by assigning datasets to groups. This helps users to locate datasets by market, product, region or any defined criteria for the group.

The category tree of a non CategoryDS datasource is different to that of a CategoryDS datasource as the categories are not assigned in the data by the vendor. Instead they are assigned by filtering datasets based on their symbol. Wildcard characters such as '?' and '*' can be used as in the symbol filtering masks. CategoryDS datasourcs have no symbol filter masks.


  • The files contain two line types, a 'Group Name' (a plain text name for a tree node) and 'Category Item' which contains a text description followed by a 'Category Information' section contained in '[]' characters.
  • The Category Item section contains a category ID string, a ':' character and a symbol filter mask. In the example "Crude Oil [CRU: PC12??Z*]", we see a category name of 'Crude Oil', a category ID of 'CRU' and a filter mask of ' PC12??Z*'.
  • With filter mask above, the category "Crude Oil" contains all datasets whose symbols begin with 'PC12', has any characters in positions 5 and 6, has a 'Z' character in position 7 and ignores any remaining characters after the 'Z' character. The filter masks and can have multiple comma seperated symbol masks in the filter such as "PC12??Z*, PCAA*, CL12??Z*". Symbol masks are not case sensitive.

DetailsDS Object

Note

The DetailsDS object is returned only if the datasource is a CategoryDS datasource (if result parameter IsCategoryDS is set to true).

Parameter Type Mandatory Description
1 SeriesCount Long Yes The number of symbols in the datasource
2 CategoryCount Integer Yes The number of data categories in the datasource.
3 CategoryTree [Object] No The CategoryTree object can only returned when the request parameter ReturnCategoryTree is set to true.
If available, it returns a hierarchical JSON tree of both category groups and category items. Data categories are used to organise data series, often by region, market, product type or instrument class. With a CategoryDS datasource, user access may be restricted to individual data categories. Each category item in the tree contains a name and the category ID. Each category group has a name and ‘Filter’ property containing a list of all the categories that are in the category group.JSON Example:

{

“Group”: “Energy”,

“Items”: [
{
“Name”: “Crude Oil”,
“Category”: “C-OIL”
},
{
“Name”: “Natural Gas”,
“Category”: “NGAS”
}
],
“Filter”: “C-OIL, NGAS”
},
4 CategoryList [Object] No The CategoryList object can only returned when the request parameter ReturnCategoryList is set to true.
If available, it returns a list of CategoryItem objects, each one describing a category from the datasource. See the ‘CategoryItem object‘ table below.
5 UserCategoryCount Integer No The UserCategoryCount parameter is returned only if the request parameter ReturnUserCategoryList is set to true. It returns the number of data categories that can be accessed with the current subscription. If it returns zero then the UserCategoryList object will not be present in the result.
6 UserCategoryList [Object] No The UserCategoryList object is only present if the UserCategoryCount parameter above is greater than zero and the ReturnUserCategoryList request parameter is set to true.

It returns a list of UserCategoryItem objects (see the ‘UserCategoryList Object‘ table below) that the user has (or had) access to. Each UserCategoryItem object describes the data category and the available access with the current subscription.
The UserAccess object is located in the UserCategoryList object and is only returned when the request parameter ReturnAccess is set to true.

CategoryItem Object

Parameter Type Description
1 Name String A short text identifier for the data category.
2 Description String A description of the data category.
3 StartDate String The first available data to subscriber for any dataset.
4 EndDate String The latest available data to subscriber for any dataset.
5 SeriesCount Integer The number of series (datasets) in the data category.

UserCategoryList Object

Parameter Type Mandatory Description
1 Name String Yes A short text identifier for the data category.
2 Description String Yes A description of the data category.
3 StartDate String Yes The first available data for any dataset.
4 EndDate String Yes The latest available data for any dataset.
5 SeriesCount Integer Yes The number of series (datasets) in the data category.
6 Subscription String No The Subscription parameter is only returned if the request parameter ReturnAccess is set to true.
It returns the type of subscription access available to the datasource.
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.
7 UserAccess [Object] No The UserAccess object is only returned when the request parameter ReturnAccess is set to true.
It contains details of the access allowed to the datasource with the current subscription.
If Subscription is returned as “None” the UserAccess object will not be present in the result.
See the ‘UserAccess Object’ table below for details.

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.

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 Bad request or missing session parameter.
401 User is inactive.
404 Unknown session token.
405 Method [request] not allowed.
500 Server may be down for maintenance.
Note

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.
If an 'Errors' object is returned, the HTTP result is likely to be the same as the one set in the 'Errors' object.
You can get HTTP client network errors or server errors from any API request. You should check with your network or IT colleagues as the issue may be 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

The sample below requests the metadata for datasource "BOE".

Sample Request:

				GET https://[server]/GetDatasource?SessionToken=YOUR_SESSION_TOKEN&Datasource=BOE

Response body on success:

Response body on fail:

Last updated on October 12, 2021

Datasources Get Metadata for all Datasources