Custom Index¶
Endpoints
POST /custom_indexes
GET /custom_indexes
GET /custom_indexes/:id
PUT /custom_indexes/:id
DELETE /custom_indexes/:id
DELETE /custom_indexes?ids=:symbol1,:symbol2
A custom index is a proprietary vector of date-value tuples. It can represent a proprietary benchmark, a risk factor, a proxy or any other measure. Even when persisted to your account, it is only available to the account.
Not bound to a workspace
Custom indexes are scoped to the account, not to a workspace. Every workspace in the account sees the same custom indexes.
The symbol must match the pattern ^CUSTOM:[A-Z0-9_]*$: the CUSTOM: prefix followed by uppercase letters, digits and underscores, for example CUSTOM:AAPLBRL. It has 8 to 107 characters. A symbol that already exists returns 400 with the message Invalid Argument: symbol: entity already exists.
The Custom Index Object¶
What a custom index object looks like?
{
"updated": 1625598288,
"description": "This is my first custom index",
"data_type": "PRICE",
"created": 1625598288,
"symbol": "CUSTOM:AAPLBRL",
"tags": ["first", "custom_index", "20210622"],
"name": "AAPL in BRL",
"currency": "BRL",
"data": [
["20201209", 554.69],
["20190814", 985.45],
["20171012", 885.07]
],
"periodicity": "D",
"base_price": 1.0
}
| Property | Description |
|---|---|
symbol string |
Unique identifier for the custom index. Must match ^CUSTOM:[A-Z0-9_]*$, 8 to 107 characters. |
created float |
Time at which the object was created. Measured in seconds since the Unix epoch. |
updated float |
Time at which the object was updated. Measured in seconds since the Unix epoch. |
name string |
The name of the custom index. Up to 200 characters. |
description string |
An arbitrary string attached to the custom index. Up to 500 characters. |
tags array |
A list of strings. Up to 32 tags. Use them to find the custom index in a list. |
data_type string |
The type of data sent through the data parameter. It can be: PRICE, RETURN(Decimal) or RETURN_100(Percentual). |
currency string |
3-letter ISO 4217 code for currency. To see all supported currencies click here. |
version string |
Indicates the custom index's current version. |
periodicity string |
The periodicity of the data changes. It can be: D (Daily) or M (Monthly). |
base_price float |
The base price when data_type is set to RETURN or RETURN_100 . |
data array |
The content that will be stored inside the Custom Index: a list of [date, value] pairs. See Data rules. |
Data rules¶
The API checks data when you create or update a custom index. A pair that breaks a rule returns 400.
- Each item is a pair
[date, value].dateis a string in the formatYYYYMMDD.valueis a finite number. - Each date occurs only once.
- Dates are between one month before
20080101and one month after today. - When
periodicityisM, each date is the last day of its month. - When
data_typeisPRICE, each value is greater than0. - When
data_typeisRETURNorRETURN_100,base_pricemust not benull. datahas at least one pair.
Create a custom index¶
Creates and then returns the new custom index.
To create a new custom index, run the following:
curl https://api.everysk.com/v2/custom_indexes \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"symbol": "CUSTOM:AAPLBRL",
"name": "AAPL in BRL",
"tags": [
"first",
"custom_index",
"20210622"
],
"description": "This is my first custom index",
"currency": "BRL",
"data": [
["20201209", 554.69],
["20190814", 985.45],
["20171012", 885.07]
]
}' \
-X POST
The above call returns the following JSON object:
{
"custom_index": {
"updated": 1625598288,
"description": "This is my first custom index",
"data_type": "PRICE",
"created": 1625598288,
"symbol": "CUSTOM:AAPLBRL",
"tags": ["first", "custom_index", "20210622"],
"name": "AAPL in BRL",
"currency": "BRL",
"data": [
["20201209", 554.69],
["20190814", 985.45],
["20171012", 885.07]
],
"periodicity": "D",
"base_price": 1.0
}
}
HTTP Request
POST /custom_indexes
HTTP Parameters
| Parameter | Description |
|---|---|
symbol string |
REQUIRED A unique identifier (UID) for a custom index. It must match ^CUSTOM:[A-Z0-9_]*$, 8 to 107 characters. A symbol that already exists returns 400. |
name string |
REQUIRED A string to identify a custom index besides the custom index's id. Up to 200 characters. |
description string |
optional, default is "" Use this field to provide detailed information about your custom index. Up to 500 characters. |
tags array |
optional, default is [] A list of strings. Up to 32 tags. |
data_type string |
optional, default is PRICE The type of data sent through the data parameter. It can be: PRICE, RETURN(Decimal) or RETURN_100(Percentual). |
periodicity string |
optional, default is D The periodicity of the data changes. It can be: D (Daily) or M (Monthly). |
currency string |
optional, default is USD 3-letter ISO 4217 code for currency. Do not send null: it returns 400. Leave the field out to use the default. To see all supported currencies click here. |
base_price float |
optional, default is 1.0 The base price when data_type is set to RETURN or RETURN_100. |
data array |
REQUIRED The content that will be stored inside the Custom Index: a list of [date, value] pairs. See Data rules. |
with_data boolean |
optional, default is True When True, the response includes the data of the custom index. |
List all custom indexes¶
To list all custom indexes, run the following:
The above call returns the following JSON object:
{
"custom_indexes": [
{
"updated": 1625598288,
"description": "This is my first custom index",
"data_type": "PRICE",
"created": 1625598288,
"symbol": "CUSTOM:AAPLBRL",
"tags": [
"first",
"custom_index",
"20210622"
],
"name": "AAPL in BRL",
"currency": "BRL",
"periodicity": "D",
"base_price": 1.0
},
...
],
"next_page_token": null
}
Returns a list of custom indexes you’ve previously created. The list shows the most recently updated custom index first. A name search returns the custom indexes whose name starts with the text, case-insensitive, sorted A to Z. The list leaves out data unless you send with_data=true.
HTTP Request
GET /custom_indexes
HTTP Parameters
| Parameter | Description |
|---|---|
query string |
optional, default is null Request a list of custom indexes filtering it by name or tag. When using a tag to perform a query, each term must include a hashtag prefix. (e.g: query="#april #sample") See Filter with query. |
page_size integer |
optional, default is 10 Set the number of objects that will be listed per page, between 1 and 10000. |
page_token string |
optional, default is null The next_page_token from the previous response. See the pagination guide. |
with_data boolean |
optional, default is False When True, each custom index in the list includes its data. |
start, end, date_time, period_field string |
optional Filter the list by a period. Custom indexes have no date, so the period applies to updated_on. See Filter by period. |
Retrieve a Custom Index¶
To retrieve a custom index, run the following:
The above call returns the following JSON object:
{
"custom_index": {
"updated": 1625598288,
"description": "This is my first custom index",
"data_type": "PRICE",
"created": 1625598288,
"symbol": "CUSTOM:AAPLBRL",
"tags": ["first", "custom_index", "20210622"],
"name": "AAPL in BRL",
"currency": "BRL",
"data": [
["20201209", 554.69],
["20190814", 985.45],
["20171012", 885.07]
],
"periodicity": "D",
"base_price": 1.0
}
}
Retrieves the details of an existing custom index by supplying the custom index's symbol.
HTTP Request
GET /custom_indexes/:id
HTTP Parameters
| Parameter | Description |
|---|---|
symbol string |
REQUIRED A unique identifier (UID) for a custom index. A custom index symbol will always look like this: CUSTOM:AAPLBRL. |
Update a custom index¶
Updates a custom index and then returns the updated custom index. Every field is optional. Only the fields you send change. The other fields keep their current values.
To update a custom index, run the following:
curl https://api.everysk.com/v2/custom_indexes/CUSTOM:AAPLBRL \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"data": [
["20200630", 952.12],
["20200731", 953.06],
["20200831", 953.25]
],
"description": "My new custom index description",
"data_type": "PRICE",
"periodicity": "M"
}' \
-X PUT
The above call returns the following JSON object:
{
"custom_index": {
"updated": 1625668154,
"description": "My new custom index description",
"data_type": "PRICE",
"created": 1625598288,
"symbol": "CUSTOM:AAPLBRL",
"tags": ["first", "custom_index", "20210622"],
"name": "AAPL in BRL",
"currency": "BRL",
"data": [
["20200630", 952.12],
["20200731", 953.06],
["20200831", 953.25]
],
"periodicity": "M",
"base_price": 1.0
}
}
HTTP Request
PUT /custom_indexes/:symbol
HTTP Parameters
| Parameter | Description |
|---|---|
symbol string |
REQUIRED The symbol of the custom index, in the URL path. |
name string |
optional A string to identify a custom index besides the custom index's id. Up to 200 characters. |
description string |
optional Use this field to provide detailed information about your custom index. Up to 500 characters. |
tags array |
optional A list of strings. Up to 32 tags. Replaces the current tags. |
data_type string |
optional The type of data sent through the data parameter. It can be: PRICE, RETURN(Decimal) or RETURN_100(Percentual). |
periodicity string |
optional The periodicity of the data changes. It can be: D (Daily) or M (Monthly). |
currency string |
optional 3-letter ISO 4217 code for currency. Do not send null: it returns 400. To see all supported currencies click here. |
base_price float |
optional The base price when data_type is set to RETURN or RETURN_100. |
data array |
optional The content that will be stored inside the Custom Index. It replaces the current data. See Data rules. |
with_data boolean |
optional, default is True When True, the response includes the data of the custom index. |
Delete a custom index¶
To delete a custom index, run the following:
The above call returns the following JSON object:
Permanently deletes a custom index. It cannot be undone. Returns an object with the custom index's id and an attribute specifying whether the custom index was successfully deleted or not.
HTTP Request
DELETE /custom_indexes/:id
HTTP Parameters
| Parameter | Description |
|---|---|
symbol string |
REQUIRED A unique identifier (UID) for a custom index, in the URL path. |
Delete several custom indexes¶
To delete several custom indexes, run the following:
The above call returns the following JSON object:
{
"custom_indexes": [
{
"symbol": "CUSTOM:AAPLBRL",
"name": "BATCH_DELETE",
"deleted": true
},
{
"symbol": "CUSTOM:SPXBRL",
"name": "BATCH_DELETE",
"deleted": true
}
]
}
Permanently deletes several custom indexes in one request. It cannot be undone. The response has one item for each symbol in ids. deleted is false for a symbol that the API could not delete. A symbol that does not exist also returns deleted: true.
HTTP Request
DELETE /custom_indexes?ids=:symbol1,:symbol2
HTTP Parameters
| Parameter | Description |
|---|---|
ids string |
REQUIRED The symbols to delete, separated by commas. |