Symbology

Financial datasets usually contain symbols or product identifiers. The mapping of symbols to their corresponding product names can be extracted from our definition schema as well as the metadata packaged with our data.

Databento supports four symbology types, also referred to as stypes. They are: raw_symbol, instrument_id, parent, and continuous.

We include methods for mapping between symbology types and resolving symbols under the symbology family of methods.

We do not retroactively reassign symbols in our historical data. Symbols found in our historical data are exactly as they appeared in the live data at the original event time. For example, if a stock symbol was changed due to a corporate action, we preserve the original symbol for data before the event and the new symbol for data after the event. This approach guarantees that the historical data looks identical to the live data at the original time, and encourages our users to write their integration in a manner that handles historical and live data in the same way.

A symbol can be reused and point to two different instruments on two different dates.

Supported symbology combinations

When requesting data, such as with the timeseries.get_range or batch.submit_job endpoints, an input and output symbology type can be specified. Not all symbology types are supported for output and some symbology types are not available in certain datasets. The following table contains all currently supported stype_in and stype_out combinations per dataset.

Raw symbol

Raw symbols are the original string symbols used by the publisher in the source data. This can be useful for environments with direct market connectivity. Examples of raw symbols include AAPL, ESH3, etc.

This symbology is used by setting the stype_in=raw_symbol parameter in the API.

Instrument ID

Instrument IDs are the unique numeric ID assigned to each instrument by the publisher. Most venues use such numeric IDs under the hood. Numeric IDs have the benefit of taking less space than most string symbols. However, numeric IDs can be difficult to work with, especially as some publishers remap them daily.

This symbology is used by setting the stype_in=instrument_id parameter in the API.

Parent

Parent symbology is a smart symbology feature that allows you to easily refer to groups of related symbols using a single root symbol. The root symbols are sourced from the asset field of the definition schema. All futures for a root symbol can be referenced using the parent symbol [ROOT].FUT, for options: [ROOT].OPT. For example, ES.FUT refers to all E-mini S&P 500 futures and futures spreads and ES.OPT refers to all quarterly E-mini S&P 500 options and option spreads.

The type of instrument will be specified in the instrument_class field. When requesting data using futures parent symbology, this field will indicate whether the instrument is a future or futures spread. When requesting data using options parent symbology, it will indicate whether the instrument is a call or put. A full list of variants can be found in the instrument class documentation.

This symbology is used by setting the stype_in=parent parameter in the API.

Continuous

Info

Our continuous contract symbology is a notation that maps to an actual, tradable instrument on any given date. The continuous contract prices returned are the original, unadjusted prices. We don't create a synthetic time series by back-adjusting the prices to remove jumps during rollovers.

Continuous contract symbology is a smart symbology feature that allow a single symbol to refer to different instruments over time. For example, continuous contract symbology allows you to query a single symbol that changes or rolls forward before expiration.

For futures outrights, we use the format [ROOT].[ROLL_RULE].[RANK] to refer to continuous contracts that change over time according to a roll rule and rank. Like with parent symbology, the root symbol corresponds with the asset field of the definition schema.

RANK is a zero-indexed integer, and ROLL_RULE is either c, n, or v from the table below.

This symbology is used by setting the stype_in=continuous parameter in the API. It is not currently possible to select continuous contracts through our web portal.

All symbols

It is possible to request all symbols within a dataset without providing them explicitly. This is done by specifying ALL_SYMBOLS with stype_in=raw_symbol or stype_in=parent in the API.

When requesting all symbols using timeseries.get_range symbology data is not provided. This means that for the CSV and JSON encodings the parameter map_symbols=True is not allowed. For the DBN encoding, the metadata header will not contain symbology mappings.

When requesting all symbols using batch.submit_job, the symbology.json support file will not contain symbology mappings.

Symbology.resolve endpoint

Databento offers symbology resolution for free in our symbology.resolve endpoint and in our client libraries. This endpoint can be used to request mappings from one symbology type to another and contains all the data necessary to perform these conversions.

symbology.json

For batch downloads, symbology information for the job is contained in the symbology.json support file. Below is a sample symbology.json file. This is a batch support file that is included in every batch download request. It's contents are directly obtained from the symbology.resolve endpoint:

{
   "result": {
      "ES.c.0": [
         { "d0": "2023-01-01", "d1": "2023-03-19", "s": "206299"},
         { "d0": "2023-03-19", "d1": "2023-06-01", "s": "95414"}
      ]
   },
   "symbols": ["ES.c.0"],
   "stype_in": "continuous",
   "stype_out": "instrument_id",
   "start_date": "2023-01-01",
   "end_date": "2023-06-01",
   "partial": [],
   "not_found": [],
   "message": "OK",
   "status": 0
}

Examining this sample we can see a requested mapping of the stype_in ("continuous") symbol ("ES.c.0") to stype_out ("instrument_id") over the date range start_date ("2023-01-01") to the end_date ("2023-06-01").

We can check the message ("OK") and status (0) fields to confirm that our request was successful over the entire date interval. Additionally, the not_found and partial fields are empty.

Most importantly, the result field contains our symbology mappings keyed by each input symbol. Each symbol entry in the result mapping will contain a list of entries. These entries contain a start date in the d0 field, and an end date in the d1 field for the mapping. The s field contains the output symbol.

SymbolMappingMsg

Databento's live data publishes symbology information using the SymbolMappingMsg. This message will always contain the input symbol and the resolved output symbol. The record header of the SymbolMappingMsg will always contain the instrument_id. See our DBN encoding article for more information on our binary format.