You need to enable JavaScript to run this app

Click the "Customize" menu button in the top-right corner of the Chrome window

Select the Settings menu item

At the bottom, click Advanced

Under Privacy and security, click Site settings

Click JavaScript

Turn on Allowed (recommended)

Click the Safari menu

Click the Preference menu item

Click on the Security tab

Click the Enable Javascript checkbox

Close the Preferences window. JavaScript is now enabled

Open the "Easy Setup" menu In the top right corner of the Opera window

At the very bottom, click Go to browser settings

Search for Javascript

Click Site settings

Click JavaScript

Choose your JavaScript settings

Click into the Address Bar, type in about:config and press enter

Accept the warning about changing advanced settings

Type javascript into the search field

Find the javascript:enabled preference

Reset the JavaScript preference to default (enabled)

Select the Tools menu

Select Internet Options

Select the Security tab

Click the Custom level... button

Scroll down to the sub-section Active scripting under Scripting section, click Enable

Confirm the change

docs

Support

API reference - Reference

Databento's reference data service can be accessed programmatically over its HTTP API. To make it easier to integrate the API, we also provide official client libraries that simplify the code you need to write.

Our HTTP API is designed as a collection of RPC-style methods, which can be called using URLs in the form https://hist.databento.com/v0/METHOD_FAMILY.METHOD.

Our client libraries wrap these HTTP RPC-style methods with more idiomatic interfaces in their respective languages.

REFERENCE DATA

Client Libraries

Python

APIs

HTTP

pip install -U databento

209

Basics

Overview

Our reference API has the following structure:

Corporate actions provides point-in-time (PIT) corporate actions events with global coverage.
Adjustment factors provides end-of-day price adjustment factors for capital events, spanning multiple currencies for the same event.
Security master provides up-to-date (latest) or point-in-time (PIT) static information on global market securities.

Authentication

Databento uses API keys to authenticate requests. You can view and manage your keys on the API keys page of your portal.

Each API key is a 32-character string starting with db-. By default, our library uses the environment variable DATABENTO_API_KEY as your API key. However, if you pass an API key to the Historical constructor through the key parameter, then this value will be used instead.

Related: Securing your API keys.

Example usage
PythonHTTP

import databento as db

# Establish connection and authenticate
client = db.Reference("$YOUR_API_KEY")

# Authenticated request
print(client.security_master.get_last(symbols="AAPL"))

Symbology

The reference datasets support querying by raw_symbol and additionally symbology types listed in the below table (depending on the endpoint).

The raw_symbol symbology type uses a standardized convention for the symbols parameter for requests. This convention is referred to as the "Nasdaq Integrated Platform Suffix" and is used consistently across our datasets, regardless of the suffix originally used by the exchange.

Standardization. This approach aligns with our symbology standardization for US equity datasets. For a detailed explanation, see our symbology standards documentation.
Local Codes. The local_code field retains the original symbol from the primary exchange. For example, symbols from NYSE-owned feeds such as NYSE Texas use the "CMS Suffix".

For additional context on symbol conventions, including the four most common suffix patterns used for US equities, refer to Nasdaq's guide on ticker symbol conventions.

The symbology related fields included with every data record are as follows:

Field	Description
`nasdaq_symbol`	Nasdaq Integrated Platform Suffix convention symbol (standardized `raw_symbol`).
`local_code`	Local code, typically the original symbol and unique at the listing level (but there are exceptions to this rule). Either an alpha string, or a number.
`isin`	International Securities Identification Number (ISIN) - ISO 6166.
`us_code`	US domestic Committee on Uniform Securities Identification Procedure (CUSIP) code.
`bbg_comp_id`	Bloomberg composite global ID.
`bbg_ticker`	Bloomberg composite ticker.
`figi`	Financial Instrument Global Identifier (FIGI), formerly Bloomberg Global Identifier (BBGID). Listing level identifier.
`figi_ticker`	Bloomberg exchange level ticker.

Info
Note a symbol may match multiple securities across a time range if the symbol has been recycled.

Tip
When identifying a listing on a specific venue, we suggest using the nasdaq_symbol field, as it aligns with the normalized raw_symbol for instruments. Once you have the ISIN for the security, using the isin symbology type will provide the most accurate results when querying for related records.

Dates and times

Our Python client library has several functions with timestamp arguments. These arguments will have type pandas.Timestamp | datetime.date | str | int and support a variety of formats.

It's recommended to use pandas.Timestamp, which fully supports timezones and nanosecond-precision. If a datetime.date is used, the time is set to midnight UTC. If an int is provided, the value is interpreted as UNIX nanoseconds.

The client library also handles several string-based timestamp formats based on ISO 8601.

yyyy-mm-dd, e.g. "2022-02-28" (midnight UTC)
yyyy-mm-ddTHH:MM, e.g. "2022-02-28T23:50"
yyyy-mm-ddTHH:MM:SS, e.g. "2022-02-28T23:50:59"
yyyy-mm-ddTHH:MM:SS.NNNNNNNNN, e.g. "2022-02-28T23:50:59.123456789"

Timezone specification is also supported.

yyyy-mm-ddTHH:MMZ
yyyy-mm-ddTHH:MM±hh
yyyy-mm-ddTHH:MM±hhmm
yyyy-mm-ddTHH:MM±hh:mm

Bare dates

Some parameters require a bare date, without a time. These arguments have type datetime.date | str and must either be a datetime.date object, or a string in yyyy-mm-dd format, e.g. "2022-02-28".

Errors

Our reference API uses HTTP response codes to indicate the success or failure of an API request. The client library provides exceptions that wrap these response codes.

2xx indicates success.
4xx indicates an error on the client side. Represented as a BentoClientError.
5xx indicates an error with Databento's servers. Represented as a BentoServerError.

The full list of the response codes and associated causes is as follows:

Code	Message	Cause
200	OK	Successful request.
400	Bad Request	Invalid request. Usually due to a missing, malformed or unsupported parameter.
401	Unauthorized	Invalid username or API key.
403	Forbidden	The API key has insufficient permissions to perform the request.
404	Not Found	A resource is not found, or a requested symbol does not exist.
422	Unprocessable Entity	The request is well formed, but we cannot or will not process the contained instructions.
429	Too Many Requests	API rate limit exceeded.
500	Internal Server Error	Unexpected condition encountered in our system.
503	Service Unavailable	Data gateway is offline or overloaded.
504	Gateway Timeout	Data gateway is available but other parts of our system are offline or overloaded.

API method
PythonHTTP

      
    
class databento.BentoError(Exception)
class databento.BentoHttpError(databento.BentoError)
class databento.BentoClientError(databento.BentoHttpError)
class databento.BentoServerError(databento.BentoHttpError)

Example usage
PythonHTTP

      
    
import databento as db

client = db.Reference("INVALID_API_KEY")

try:
    print(client.security_master.get_last("TEST"))
except db.BentoClientError as e:
    print(e)

Example response
PythonHTTP

      
    
400 auth_invalid_username_in_basic_auth
Invalid username in Basic auth ('INVALID_API_KEY').
documentation: https://databento.com/docs

Rate limits

Our reference API allows each IP address up to:

100 concurrent connections.
100 corporate actions requests per second.
100 adjustment factors requests per second.
100 security master requests per second.

When a request exceeds a rate limit, a BentoClientError exception is raised with a 429 error code.

Retry-After

The Retry-After response header indicates how long the user should wait before retrying.

If you find that your application has been rate-limited, you can retry after waiting for the time specified in the Retry-After header.

If you are using Python, you may use the time.sleep function as seen below to wait for the time specified in the Retry-After header. e.g. time.sleep(int(response.headers("Retry-After", 1)))

This code snippet works best for our current APIs with their rate limits. Future APIs may have different rate limits, and might require a different default time delay.

Client

Reference

To access Databento's reference API, first create an instance of the Reference client. The entire API is exposed through instance methods of the client.

Note that the API key can be passed as a parameter, which is not recommended for production applications. Instead, you can leave out this parameter to pass your API key via the DATABENTO_API_KEY environment variable:

Currently, only the 'bo1' gateway is supported for historical data.

Parameters

key

optional | str

32-character API key. Found on your API keys page. If None then DATABENTO_API_KEY environment variable is used.

gateway

optional | databento.HistoricalGateway or str

Site of historical gateway to connect to. Currently only 'bo1' is supported. If None then will connect to the default historical gateway.

API method
PythonHTTP

      
    
class Reference(
    key: str | None = None,
    gateway: HistoricalGateway | str = 'bo1',
)

Example usage
PythonHTTP

import databento as db

# Pass as parameter
client = db.Reference("$YOUR_API_KEY")

# Or, pass as `DATABENTO_API_KEY` environment variable
client = db.Reference()

Corporate actions

Reference.corporate_actions.get_range

Make a streaming request for corporate actions time series data from Databento.

Each record represents a unique corporate actions event at the listing level.

The specified index will be used to filter the time range and order the records. It will also be set as the index of the resulting data frame.

See also
Corporate actions dataset guide for further details.

Parameters

start

required | pd.Timestamp, datetime, date, str, or int

The inclusive start of the request range. Takes pd.Timestamp, Python datetime, Python date, ISO 8601 string, or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.

end

optional | pd.Timestamp, datetime, date, str, or int

The exclusive end of the request range. Takes pd.Timestamp, Python datetime, Python date, ISO 8601 string, or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. Defaults to the forward filled value of start based on the resolution provided.

index

optional | str, default 'event_date'

The index column to use for filtering the start and end time range and for record ordering. Use any of 'event_date', 'ex_date' or 'ts_record'. Records with a NULL value in the specified index column will be excluded.

symbols

optional | list or str

The symbols to filter for. Takes up to 2,000 symbols per request. If more than 1 symbol is specified, the data is merged and sorted by time. If 'ALL_SYMBOLS' or None then will select all symbols by default.

stype_in

optional | SType or str, default 'raw_symbol'

The symbology type of input symbols. Use any of 'raw_symbol', 'nasdaq_symbol', 'isin', 'us_code', 'bbg_comp_id', 'bbg_comp_ticker', 'figi', 'figi_ticker'.

events

optional | list or str

The event types to filter for. Takes any number of events per request. If not specified then will select all event types by default. See EVENT enum.

countries

optional | list or str

The listing countries to filter for. Takes any number of country codes per request as two letter ISO 3166-1 alpha-2 strings. If not specified then will select all countries by default. See CNTRY enum.

exchanges

optional | list or str

The (listing) exchanges to filter for. Takes any number of exchanges per request. If not specified then will select all exchanges by default. See EXCHANGE enum.

security_types

optional | list or str

The security types to filter for. If not specified then will select all security types by default. See SECTYPE enum.

flatten

optional | bool, default True

If nested JSON objects within the date_info, rate_info, and event_info fields should be flattened into separate columns in the resulting data frame.

pit

optional | bool, default False

Determines whether to retain all historical records or only the latest records. If True, all historical records for each event_unique_id will be retained, preserving the complete point-in-time history. If False (default), the data frame will include only the most recent record for each event_unique_id based on the ts_record timestamp.

Returns

pd.Dataframe

The data converted into a DataFrame.

See also
Corporate actions field descriptions for further details.

API method
PythonHTTP

      
    
Reference.corporate_actions.get_range(
    start: pd.Timestamp | datetime | date | str | int,
    end: pd.Timestamp | datetime | date | str | int | None = None,
    index: str = "event_date",
    symbols: Iterable[str] | str | None = None,
    stype_in: SType | str = "raw_symbol",
    events: Iterable[str] | str | None = None,
    countries: list[str] | str | None = None,
    security_types: list[str] | str | None = None,
    flatten: bool = True,
    pit: bool = False,
) -> pd.DataFrame

Example usage
PythonHTTP

      
    
import databento as db

client = db.Reference("$YOUR_API_KEY")

df_raw = client.corporate_actions.get_range(
    symbols=["AAPL"],
    stype_in="raw_symbol",
    start="2024-01",
    events=["SHOCH"],
    countries=["US"],
)

print(df_raw.head())

Example response
PythonHTTP

      
    
                 event_unique_id                 ts_record         event_id listing_id listing_group_id security_id issuer_id event_action  event  event_subtype event_date_label event_created_date effective_date ex_date record_date  record_date_id related_event  related_event_id global_status listing_status listing_source listing_date delisting_date issuer_name security_type security_description primary_exchange exchange operating_mic symbol nasdaq_symbol local_code          isin   us_code   bbg_comp_id bbg_comp_ticker          figi figi_ticker listing_country register_country trading_currency  multi_currency segment_mic_name segment_mic mand_volu_flag  rd_priority  lot_size  par_value par_value_currency payment_date duebills_redemption_date from_date to_date registration_date start_date end_date open_date close_date start_subscription_date end_subscription_date option_election_date  withdrawal_rights_from_date withdrawal_rights_to_date notification_date financial_year_end_date exp_completion_date  payment_type  option_id  serial_id  default_option_flag  rate_currency  ratio_old  ratio_new  fraction  outturn_style  outturn_security_type  outturn_security_id  outturn_isin  outturn_us_code  outturn_local_code  outturn_bbg_comp_id  outturn_bbg_comp_ticker  outturn_figi  outturn_figi_ticker  min_offer_qty  max_offer_qty  min_qualify_qty  max_qualify_qty  min_accept_qty  max_accept_qty  tender_strike_price  tender_price_step option_expiry_time  option_expiry_tz  withdrawal_rights_flag withdrawal_rights_expiry_time  withdrawal_rights_expiry_tz expiry_time  expiry_tz                       ts_created old_outstanding_date new_outstanding_date old_shares_outstanding new_shares_outstanding
event_date
2024-01-02  U-40685533904-135825 2024-01-12 13:12:12+00:00  E-5533904-SHOCH   L-135825         LG-35825     S-33449   I-30017            I  SHOCH            NaN   effective_date         2024-01-12     2024-01-02    None        None             NaN         SHOCH               NaN             A              L              M   1980-12-12           None   Apple Inc           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW              US               US              USD           False    Global Select        XNGS              M          NaN       100    0.00001                USD         None                     None      None    None              None       None     None      None       None                    None                  None                 None                          NaN                      None              None                    None                None           NaN        NaN        NaN                False            NaN        NaN        NaN       NaN            NaN                    NaN                  NaN           NaN              NaN                 NaN                  NaN                      NaN           NaN                  NaN            NaN            NaN              NaN              NaN             NaN             NaN                  NaN                NaN                NaT               NaN                     NaN                           NaT                          NaN         NaT        NaN 2024-07-24 06:32:10.375440+00:00  2023-10-20T00:00:00  2024-01-02T00:00:00            15552752000            15461896000
2024-01-19  U-40685575281-135825 2024-02-05 03:37:49+00:00  E-5575281-SHOCH   L-135825         LG-35825     S-33449   I-30017            I  SHOCH            NaN   effective_date         2024-02-03     2024-01-19    None        None             NaN         SHOCH               NaN             A              L              M   1980-12-12           None   Apple Inc           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW              US               US              USD           False    Global Select        XNGS              M          NaN       100    0.00001                USD         None                     None      None    None              None       None     None      None       None                    None                  None                 None                          NaN                      None              None                    None                None           NaN        NaN        NaN                False            NaN        NaN        NaN       NaN            NaN                    NaN                  NaN           NaN              NaN                 NaN                  NaN                      NaN           NaN                  NaN            NaN            NaN              NaN              NaN             NaN             NaN                  NaN                NaN                NaT               NaN                     NaN                           NaT                          NaN         NaT        NaN 2024-07-24 22:44:12.284177+00:00  2024-01-02T00:00:00  2024-01-19T00:00:00            15461896000            15441881000
2024-04-19  U-40685752069-135825 2024-05-06 13:21:00+00:00  E-5752069-SHOCH   L-135825         LG-35825     S-33449   I-30017            I  SHOCH            NaN   effective_date         2024-05-06     2024-04-19    None        None             NaN         SHOCH               NaN             A              L              M   1980-12-12           None   Apple Inc           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW              US               US              USD           False    Global Select        XNGS              M          NaN       100    0.00001                USD         None                     None      None    None              None       None     None      None       None                    None                  None                 None                          NaN                      None              None                    None                None           NaN        NaN        NaN                False            NaN        NaN        NaN       NaN            NaN                    NaN                  NaN           NaN              NaN                 NaN                  NaN                      NaN           NaN                  NaN            NaN            NaN              NaN              NaN             NaN             NaN                  NaN                NaN                NaT               NaN                     NaN                           NaT                          NaN         NaT        NaN 2024-07-25 01:52:32.148864+00:00  2024-01-19T00:00:00  2024-04-19T00:00:00            15441881000            15334082000
2024-07-19  U-40685933868-135825 2024-08-05 03:41:52+00:00  E-5933868-SHOCH   L-135825         LG-35825     S-33449   I-30017            I  SHOCH            NaN   effective_date         2024-08-03     2024-07-19    None        None             NaN         SHOCH               NaN             A              L              M   1980-12-12           None   Apple Inc           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW              US               US              USD           False    Global Select        XNGS              M          NaN       100    0.00001                USD         None                     None      None    None              None       None     None      None       None                    None                  None                 None                          NaN                      None              None                    None                None           NaN        NaN        NaN                False            NaN        NaN        NaN       NaN            NaN                    NaN                  NaN           NaN              NaN                 NaN                  NaN                      NaN           NaN                  NaN            NaN            NaN              NaN              NaN             NaN             NaN                  NaN                NaN                NaT               NaN                     NaN                           NaT                          NaN         NaT        NaN 2024-08-05 06:00:56.552900+00:00  2024-04-19T00:00:00  2024-07-19T00:00:00            15334082000            15204137000

Adjustment factors

Reference.adjustment_factors.get_range

Make a streaming request for adjustment factors time series data from Databento.

Each record represents a unique corporate actions event with an adjustment factor at the listing level.

The ex_date column will be used to filter the time range and order the records. It will also be set as the index of the resulting data frame.

See also
Adjustment factors dataset guide for further details.

Parameters

start

required | pd.Timestamp, datetime, date, str, or int

The inclusive start of the request range. Takes pd.Timestamp, Python datetime, Python date, ISO 8601 string, or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.

end

optional | pd.Timestamp, datetime, date, str, or int

symbols

optional | list or str

stype_in

optional | SType or str, default 'raw_symbol'

The symbology type of input symbols. Use any of 'raw_symbol', 'nasdaq_symbol', 'isin', 'us_code'.

countries

optional | list or str

security_types

optional | list or str

The security types to filter for. If not specified then will select all security types by default. See SECTYPE enum.

Returns

pd.Dataframe

The data converted into a DataFrame.

See also
Adjustment factors field descriptions for further details.

API method
PythonHTTP

      
    
Reference.adjustment_factors.get_range(
    start: pd.Timestamp | datetime | date | str | int,
    end: pd.Timestamp | datetime | date | str | int | None = None,
    symbols: Iterable[str] | str | None = None,
    stype_in: SType | str = "raw_symbol",
    countries: list[str] | str | None = None,
    security_types: list[str] | str | None = None,
) -> pd.DataFrame

Example usage
PythonHTTP

      
    
import databento as db

client = db.Reference("$YOUR_API_KEY")

df_raw = client.adjustment_factors.get_range(
    symbols=["MSFT"],
    stype_in="raw_symbol",
    start="2009",
    end="2010",
    countries=["US"],
)

print(df_raw.head())

Example response
PythonHTTP

      
    
           security_id      event_id event            issuer_name security_type primary_exchange  exchange operating_mic symbol nasdaq_symbol local_code  local_code_resulting          isin  isin_resulting    us_code status    factor  close currency  sentiment  reason  gross_dividend dividend_currency frequency  option                                   detail                       ts_created
ex_date
2009-02-17     S-39827  E-336073-DIV   DIV  Microsoft Corporation           EQS           USNASD       NaN          XNAS   MSFT          MSFT       MSFT                   NaN  US5949181045             NaN  594918104      A  0.993190  19.09      USD   0.968570      17            0.13               USD       FNL       1  Dividend (cash) of USD0.130000000/Share 2024-08-23 10:04:48.075003+00:00
2009-05-19     S-39827  E-353927-DIV   DIV  Microsoft Corporation           EQS           USNASD       NaN          XNAS   MSFT          MSFT       MSFT                   NaN  US5949181045             NaN  594918104      A  0.993689  20.60      USD   0.992718      17            0.13               USD       QTR       1  Dividend (cash) of USD0.130000000/Share 2024-08-23 10:07:09.546929+00:00
2009-08-18     S-39827  E-381906-DIV   DIV  Microsoft Corporation           EQS           USNASD       NaN          XNAS   MSFT          MSFT       MSFT                   NaN  US5949181045             NaN  594918104      A  0.994409  23.25      USD   1.003871      17            0.13               USD       QTR       1  Dividend (cash) of USD0.130000000/Share 2024-08-23 10:09:33.205558+00:00
2009-11-17     S-39827  E-400830-DIV   DIV  Microsoft Corporation           EQS           USNASD       NaN          XNAS   MSFT          MSFT       MSFT                   NaN  US5949181045             NaN  594918104      A  0.995599  29.54      USD   0.998646      17            0.13               USD       QTR       1  Dividend (cash) of USD0.130000000/Share 2024-08-23 10:11:40.477633+00:00

Security master

Reference.security_master.get_last

Make a streaming request for the latest security master data from Databento.

Each record represents the a unique listing for a security.

The resulting data frame will be indexed and sorted by ts_effective.

See also
Security master dataset guide for further details.

Parameters

symbols

optional | list or str

stype_in

optional | SType or str, default 'raw_symbol'

The symbology type of input symbols. Use any of 'raw_symbol', 'nasdaq_symbol', 'isin', 'us_code', 'bbg_comp_id', 'bbg_comp_ticker', 'figi', 'figi_ticker'.

countries

optional | list or str

security_types

optional | list or str

The security types to filter for. If not specified then will select all security types by default. See SECTYPE enum.

Returns

pandas.Dataframe

The data converted into a DataFrame.

See also
Security master field descriptions for further details.

API method
PythonHTTP

      
    
Reference.security_master.get_last(
    symbols: Iterable[str] | str | None = None,
    stype_in: SType | str = "raw_symbol",
    countries: list[str] | str | None = None,
    security_types: list[str] | str | None = None,
) -> pd.DataFrame

Example usage
PythonHTTP

      
    
import databento as db

client = db.Reference("$YOUR_API_KEY")

df_raw = client.security_master.get_last(
    symbols=["AAPL"],
    countries=["US"],
)

print(df_raw.head())

Example response
PythonHTTP

      
    
                                          ts_record listing_id listing_group_id security_id issuer_id listing_status listing_source listing_created_date listing_date delisting_date issuer_name security_type security_description primary_exchange exchange operating_mic symbol nasdaq_symbol local_code          isin   us_code   bbg_comp_id bbg_comp_ticker          figi figi_ticker  fisn                   lei   sic     cik  gics   naics   cic     cfi incorporation_country listing_country register_country trading_currency  multi_currency segment_mic_name segment_mic  structure  lot_size  par_value par_value_currency voting  vote_per_sec  shares_outstanding shares_outstanding_date                       ts_created
ts_effective
2024-07-19 00:00:00+00:00 2024-08-05 02:41:52+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None   Apple Inc           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1         15204137000              2024-07-19 2024-11-11 22:41:29.670132+00:00

Reference.security_master.get_range

Make a streaming request for security master point-in-time (PIT) time series data from Databento.

Each record represents the status of a unique listing for a security with an effective date.

The specified index will be used to filter the time range and order the records. It will also be set as the index of the resulting data frame.

See also
Security master dataset guide for further details.

Parameters

start

required | pd.Timestamp, datetime, date, str, or int

The inclusive start of the request range. Takes pd.Timestamp, Python datetime, Python date, ISO 8601 string, or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.

end

optional | pd.Timestamp, datetime, date, str, or int

index

optional | str, default 'ts_effective'

The index column to use for filtering the start and end time range and recording ordering. Use any of 'ts_effective' or 'ts_record'.

symbols

optional | list or str

stype_in

optional | SType or str, default 'raw_symbol'

The symbology type of input symbols. Use any of 'raw_symbol', 'nasdaq_symbol', 'isin', 'us_code', 'bbg_comp_id', 'bbg_comp_ticker', 'figi', 'figi_ticker'.

countries

optional | list or str

security_types

optional | list or str

The security types to filter for. If not specified then will select all security types by default. See SECTYPE enum.

Returns

pd.Dataframe

The data converted into a DataFrame.

See also
Security master field descriptions for further details.

API method
PythonHTTP

      
    
Reference.security_master.get_range(
    start: pd.Timestamp | datetime | date | str | int,
    end: pd.Timestamp | datetime | date | str | int | None = None,
    index: str = "ts_effective",
    symbols: Iterable[str] | str | None = None,
    stype_in: SType | str = "raw_symbol",
    countries: list[str] | str | None = None,
    security_types: list[str] | str | None = None,
) -> pd.DataFrame

Example usage
PythonHTTP

      
    
import databento as db

client = db.Reference("$YOUR_API_KEY")

df_raw = client.security_master.get_range(
    symbols=["AAPL"],
    countries=["US"],
    start="2005-01-01",
)

print(df_raw.head(10))

Example response
PythonHTTP

      
    
                                          ts_record listing_id listing_group_id security_id issuer_id listing_status listing_source listing_created_date listing_date delisting_date          issuer_name security_type security_description primary_exchange exchange operating_mic symbol nasdaq_symbol local_code          isin   us_code   bbg_comp_id bbg_comp_ticker          figi figi_ticker  fisn                   lei   sic     cik  gics   naics   cic     cfi incorporation_country listing_country register_country trading_currency  multi_currency segment_mic_name segment_mic  structure  lot_size  par_value par_value_currency voting  vote_per_sec  shares_outstanding shares_outstanding_date                       ts_created
ts_effective
2004-11-19 00:00:00+00:00 2004-12-06 15:09:30+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           402057856              2004-11-19 2024-11-11 22:41:24.780487+00:00
2005-01-25 00:00:00+00:00 2005-02-03 16:00:32+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           408585970              2005-01-25 2024-11-11 22:41:24.780487+00:00
2005-02-28 00:00:00+00:00 2005-03-01 15:28:04+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           817171940              2005-02-28 2024-11-11 22:41:24.780487+00:00
2005-04-22 00:00:00+00:00 2005-05-06 14:06:41+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           823933916              2005-04-22 2024-11-11 22:41:24.780487+00:00
2005-07-22 00:00:00+00:00 2005-08-04 14:39:03+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           829829296              2005-07-22 2024-11-11 22:41:24.780487+00:00
2005-11-18 00:00:00+00:00 2005-12-02 15:25:18+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           842767948              2005-11-18 2024-11-11 22:41:24.780487+00:00
2006-01-25 00:00:00+00:00 2006-02-07 15:32:26+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           848612359              2006-01-25 2024-11-11 22:41:24.780487+00:00
2006-04-26 00:00:00+00:00 2006-05-09 14:36:54+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           850508144              2006-04-26 2024-11-11 22:41:24.780487+00:00
2006-12-13 00:00:00+00:00 2007-01-02 15:42:39+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None  Apple Computer Inc.           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           859273757              2006-12-13 2024-11-11 22:41:24.780487+00:00
2007-01-11 00:00:00+00:00 2007-01-11 00:00:00+00:00   L-135825         LG-35825     S-33449   I-30017              L              M           2001-05-05   1980-12-12           None            Apple Inc           EQS      Ordinary Shares           USNASD   USNASD          XNAS   AAPL          AAPL       AAPL  US0378331005  37833100  BBG000B9XRY4         AAPL US  BBG000B9Y5X2     AAPL UW   NaN  HWUPKR0MPOU8FGXBT394  3571  320193   NaN  334111  US31  ESVUFR                    US              US               US              USD           False    Global Select        XNGS        NaN       100          0                USD      V             1           859273757              2006-12-13 2024-11-11 22:41:29.670132+00:00