Skip to content

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]. date is a string in the format YYYYMMDD. value is a finite number.
  • Each date occurs only once.
  • Dates are between one month before 20080101 and one month after today.
  • When periodicity is M, each date is the last day of its month.
  • When data_type is PRICE, each value is greater than 0.
  • When data_type is RETURN or RETURN_100, base_price must not be null.
  • data has 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:

curl -G https://api.everysk.com/v2/custom_indexes \
  --data-urlencode "query=#20210622" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

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:

curl https://api.everysk.com/v2/custom_indexes/CUSTOM:AAPLBRL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

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:

curl https://api.everysk.com/v2/custom_indexes/CUSTOM:AAPLBRL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

The above call returns the following JSON object:

{
  "custom_index": {
    "deleted": true,
    "symbol": "CUSTOM:AAPLBRL",
    "name": "AAPL in BRL"
  }
}

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:

curl "https://api.everysk.com/v2/custom_indexes?ids=CUSTOM:AAPLBRL,CUSTOM:SPXBRL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

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.