5.2.  Return the User Favorites Metadata

GET GetFavorites

Description:  Get the metadata for the datasets contained in the users ‘favorites’ list (the users personally selected list of datasets).

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]/GetFavorites?SessionToken=YOUR_SESSION_TOKEN&ReturnFavoritesTree=true&DateFormat=YY-MM-DD

Request Parameters

Parameter Type Notes
SessionToken String A session token from the GetSessionToken endpoint.
IgnoreEmpty Boolean If true, any dataset that has no values will not be included in the result.

Optional Request Parameters

Parameter Type Default Notes
ReturnFavoritesTree Boolean false Returns the user created favorites tree. This list is managed by the user from the Monitor+ Favorites web portal.
ReturnAccess Boolean false If true, a UserAccess object with information on each dataset is returned in the dataset object. If the result dataset parameter Subscription is “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 embedded in the Details object.
See the ‘User Access Object’ table below for more information.

Page Integer 1 The page number to select (see Rows parameter below and notes).
Rows Integer 50 Number of rows per page. Default is 50. Maximum is 500*.
DateFormat String “YYYY-MM-DD” The date format to use in the request and result. See the ‘DateFormat Parameter‘ section below for details.
Notes
  • If Rows is not defined in the request, automatic pagination is added to the result if the user favorites has more than 500 series. In this case, the result will return page one with the default number of rows.
  • If the ReturnFavoritesTree request parameter is false, the result will not have a FavoritesTree object even if one exists on the server.
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": ….

Tips:

  • Use the “AddUserFavorites” endpoint to add datasets to your favorite series on the server.
  • Use the “RemoveUserFavorites” endpoint to remove selected datasets from your favorite dataset list.

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’.
Notes
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 ISO 8601 string.
2 TimeStamp Float Yes 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

Parameter Type Mandatory Description
Metadata [Object] Yes Metadata about the result showing the dataset count, page, page count etc. See the “Metadata Object” table below for details.
Datasets [Object] Yes Datasets metadata, each identified by its requested datasource/symbol. See the “Datasets Object” table below for details.
FavoritesTree
[Object] Yes A multi level JSON tree structure managed by the user to organize their favourites datasets.
Only returned if the request ReturnFavoritesTree parameter is true.

Metadata Object

Parameter Type Mandatory Notes
1 Datasets Integer Yes The number of datasets in the favourites list.
2 Updated String Yes The date and time the favorites list was last changed as an ISO 8601 string.
3 TimeStamp String Yes The date and time the favorites list was last changed as a Julian date.
4 Page Integer Yes The current page number in the result.
5 PageCount Integer Yes The number of pages available (based on Rows below).
6 Rows Integer Yes The number of datasets returned in the Page.

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. If the dataset status is not 200, this field may contain the missing DATABASE/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 “CategoryDS datasources” note above.
19 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 option “Simulated” means that the values are fictional and are generated for demonstration purposes only.
20 UserAccess [Object] No* If Subscription is not present or 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 “User Access 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 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”
}
]
}
22 Logo String No* A link to a small datasource logo image.
23 Status Integer No* A HTTP standard result code for the dataset. It returns 200 (success) if the dataset is available. See the Details parameter below.
24 Details String No* A description of the Status parameter value above.
Note

An asterisk '*' character in the Mandatory column above denotes that this parameter will mot be present if the Status returned is 400 or 404 (no error).


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 Mandatory Notes
1 Status Integer Yes The HTTP status code.
2 Detail String Yes Description of the status code above.

Possible Status codes in the 'Errors' object

Code Description
400 The datasource field is invalid.
401 Invalid session token.
404 Datasource was not found.
406 Unacceptable row count.
Note

This is not an exhaustive list and additional error codes may be returned. The Errors object 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 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

Sample Request:

GET https://[server]/GetFavorites?SessionToken=YOUR_SESSION_TOKEN&ReturnTree=true

Response body on success:


Note

In an actual request there may be multiple datasources in the result object. For clarity, we show only two.

Response body on fail:

Last updated on October 12, 2024

Get Favorites Status Add Datasets(s) to Favorites