5.3. Add one or more datasets to the user favorites list.
GET and POST AddFavorites
Description: Add one or more datasets to your list of user favorite 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]/AddFavorites?SessionToken=YOUR_SESSION_TOKEN&Series[]=ECBFX/EURGBP&Series[]=ECBFX/EURUSD
POST Sample Request:
POST https://[server]/AddUserFavorites
{
"SessionToken=YOUR_SESSION_TOKEN",
"Series":[
{ "Datasource":"ECBFX", "Symbol":"EURGBP" },
{ "Datasource":"ECBFX", "Symbol":"EURUSD" }
]
}
- 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": ….
Request Parameters
| Parameter | Type | Mandatory | Description |
| SessionToken | String | Yes | The Session token from the GetSessionToken endpoint |
| Series | [Object] | Yes | A list of
Datasource (,
Datacategory) and
Symbol parameters to
request. See the example above. The SeriesDatacategory parameter is only 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. |
Tips:
- You can use the GetUserFavorites endpoint to return the current list of user favorites.
- Use the RemoveUserFavorites endpoint to remove data symbols from the user favorites.
- If you try to add a dataset that is in your favorites (or is not authorised) the result ‘ignored’ parameter will be incremented.
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 | 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 Object‘ 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 | Mandatory | Description | |
|---|---|---|---|---|
| 1 | Added | Integer | Yes | The number of datasets that were added to favorites list. |
| 2 | Ignored | Integer | Yes | The number of datasets that were ignored (already in the favorites list or unauthorised). |
Errors Object
| Parameter | Type | Mandatory | Description | |
|---|---|---|---|---|
| 1 | Status | Integer | Yes | HTTP status code. |
| 2 | Detail | String | Yes | Description of the status code above. |
Possible Status codes in the 'Errors' object
| Code | Description |
|---|---|
| 400 | Symbol not valid for datasource or data category parameter missing/invalid. |
| 401 | Invalid session token. |
| 404 | Unknown Datasource. |
| 429 | Sesion Token has expired. |
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]/AddFavorites?SessionToken=YOUR_SESSION_TOKEN&Series[]=ECBFX/EURCAD
Response body on success:
Response body on fail: