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.
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 Reference constructor through the key parameter, then this value will be used instead.
Related: Securing your API keys.
Example usage
1 2 3 4 5 6 7
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_codefield 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 | |
us_code | US domestic Committee on Uniform Securities Identification Procedure (CUSIP) code. |
bbg_comp_id | Bloomberg composite global ID. |
bbg_comp_ticker | Bloomberg composite ticker. |
figi | Financial Instrument Global Identifier (FIGI), formerly Bloomberg Global Identifier (BBGID). Listing level identifier. |
figi_ticker | Bloomberg exchange-level ticker. |
listing_id | Databento-specific identifier that tracks an individual exchange's listing of a security. |
issuer_id | Databento-specific identifier shared across all securities issued by the same company. |
security_id | Databento-specific identifier at the security level, tracking a security across all of its exchange listings. |
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:MMZyyyy-mm-ddTHH:MM±hhyyyy-mm-ddTHH:MM±hhmmyyyy-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.
2xxindicates success.4xxindicates an error on the client side. Represented as aBentoClientError.5xxindicates an error with Databento's servers. Represented as aBentoServerError.
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
1 2 3 4
class databento.BentoError(Exception)
class databento.BentoHttpError(databento.BentoError)
class databento.BentoClientError(databento.BentoHttpError)
class databento.BentoServerError(databento.BentoHttpError) Example usage
1 2 3 4 5 6 7 8
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
1 2 3
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
| Parameter | Type | Required | Description |
|---|---|---|---|
key | str | optional | 32-character API key. Found on your API keys page. If None then DATABENTO_API_KEY environment variable is used. |
gateway | databento.HistoricalGateway or str | optional | Site of historical gateway to connect to. Currently only 'bo1' is supported. If None then will connect to the default historical gateway. |
API method
1 2 3 4
class Reference(
key: str | None = None,
gateway: HistoricalGateway | str = 'bo1',
) Example usage
1 2 3 4 5 6 7
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
| Parameter | Type | Required | Description |
|---|---|---|---|
start | pd.Timestamp, datetime, date, str, or int | required | The inclusive start of the request range based on index. Takes pd.Timestamp, Python datetime, Python date, ISO 8601 string, or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. |
end | pd.Timestamp, datetime, date, str, or int | optional | The exclusive end of the request range based on index. Takes pd.Timestamp, Python datetime, Python date, ISO 8601 string, or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. If None, then will return all data available after start. |
index | str, default 'event_date' | optional | 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 | list or str | optional | 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 | SType or str, default 'raw_symbol' | optional | 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', 'listing_id', 'issuer_id', 'security_id'. |
events | list or str | optional | |
countries | list or str | optional | 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 | list or str | optional | 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 | list or str | optional | The security types to filter for. If not specified then will select all security types by default. See SECTYPE enum. |
flatten | bool, default True | optional | 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 | bool, default False | optional | 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. |
allocate_isins | bool, default True | optional | Whether the request should allocate any new ISINs for plans that are ISIN-limited. The request will drop any rows that would create new allocations. |
Returns
pd.Dataframe
The data converted into a DataFrame.
See also
Corporate actions field descriptions for further details.
API method
1 2 3 4 5 6 7 8 9 10 11 12 13 14
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,
exchanges: list[str] | str | None = None,
security_types: list[str] | str | None = None,
flatten: bool = True,
pit: bool = False,
allocate_isins: bool = True,
) -> pd.DataFrame Example usage
1 2 3 4 5 6 7 8 9 10 11 12 13
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
1 2 3 4 5 6
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
Reference.corporate_actions.list_events
Requests documentation for all supported corporate action event types, including their fields, subtypes, and applicable calendar dates.
Returns
dict[str, dict]
The raw JSON response as a dict keyed by event code (e.g. AGM), where each value is:
| Field | Type | Description |
|---|---|---|
calendar_dates | list[dict] or None | The calendar dates relevant to the event. |
category | str or None | The category of the event ( distribution, distribution_debit, legal_action, proposal, reorganisation, static_reference, tax_related, other). |
code | str or None | The code for the event (e.g. AGM). |
description | str or None | Description of the event. |
fields | list[dict] or None | The fields relevant to the event. |
level | str | The level the event applies to ( country, issuer, listing, security). |
name | str | Name of the event. |
participation | str or None | Whether the event is mandatory, voluntary, or a mix of the two ( mandatory, voluntary, mandatory_voluntary). |
subtypes | list[dict] or None | The subtypes relevant to the event. |
See also
Corporate actions events guide for information in text form.
API method
1
Reference.corporate_actions.list_events() -> dict[str, dict] Example usage
1 2 3 4 5 6 7
import databento as db
client = db.Reference("$YOUR_API_KEY")
event_docs = client.corporate_actions.list_events()
print(event_docs["AGM"]) Example response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
{
"code": "AGM",
"name": "Company Meeting",
"level": "issuer",
"category": "proposals",
"participation": "voluntary",
"description": "Annual General meeting of shareholders is held once a year, usually after the end of the financial year. Also includes other meeting types such as Extraordinary General Meeting, Special General Meeting, Court Ordered Meeting, and Postal Ballot.",
"subtypes": [
{
"code": "AGM",
"description": "Annual General Meeting"
},
{
"code": "BHM",
"description": "Bond Holder Meeting"
},
{
"code": "CGM",
"description": "Court Ordered General Meeting"
},
{
"code": "EGM",
"description": "Extraordinary General Meeting"
},
{
"code": "GM",
"description": "General Meeting"
},
{
"code": "SGM",
"description": "Special General Meeting"
}
],
"calendar_dates": [
{
"name": "event_date",
"alias": "meeting_date"
},
{
"name": "effective_date",
"alias": "meeting_date"
}
],
"fields": [
{
"group": "event_info",
"name": "meeting_number",
"description": "Company Meeting Number"
},
{
"group": "event_info",
"name": "meeting_time",
"description": "Local time for Start of Meeting"
},
{
"group": "event_info",
"name": "address_line1",
"description": "Address line 1"
},
{
"group": "event_info",
"name": "address_line2",
"description": "Address line 2"
},
{
"group": "event_info",
"name": "address_line3",
"description": "Address line 3"
},
{
"group": "event_info",
"name": "address_line4",
"description": "Address line 4"
},
{
"group": "event_info",
"name": "address_line5",
"description": "Address line 5"
},
{
"group": "event_info",
"name": "address_line6",
"description": "Address line 6"
},
{
"group": "event_info",
"name": "city",
"description": "City"
},
{
"group": "event_info",
"name": "country",
"description": "Country Code - ISO 3166-1"
}
]
} Reference.corporate_actions.list_enums
Requests documentation for the full set of enumerations used across corporate actions data, like event actions and statuses.
Returns
dict[str, list[dict]]
The raw JSON response as a dict keyed by enum group name (e.g. ACTION). Each value is a list of variants:
| Field | Type | Description |
|---|---|---|
code | str or None | Code for the enum variant. |
description | str | Description of the enum variant. |
See also
Reference data enums for a lookup table of possible enumeration field values.
API method
1
Reference.corporate_actions.list_enums() -> dict[str, list[dict]] Example usage
1 2 3 4 5 6 7
import databento as db
client = db.Reference("$YOUR_API_KEY")
enum_docs = client.corporate_actions.list_enums()
print(enum_docs["ACTION"]) Example response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
[
{
"code": "C",
"description": "Cancelled"
},
{
"code": "D",
"description": "Deleted"
},
{
"code": "I",
"description": "Inserted"
},
{
"code": "P",
"description": "Payment details Cancelled by Issuer"
},
{
"code": "Q",
"description": "Payment details Deleted by Data Supplier"
},
{
"code": "U",
"description": "Updated"
}
] 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
| Parameter | Type | Required | Description |
|---|---|---|---|
start | pd.Timestamp, datetime, date, str, or int | required | The inclusive start of the request range based on ex_date. Takes pd.Timestamp, Python datetime, Python date, ISO 8601 string, or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. |
end | pd.Timestamp, datetime, date, str, or int | optional | The exclusive end of the request range based on ex_date. Takes pd.Timestamp, Python datetime, Python date, ISO 8601 string, or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. If None, then will return all data available after start. |
symbols | list or str | optional | 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 | SType or str, default 'raw_symbol' | optional | The symbology type of input symbols. Use any of 'raw_symbol', 'nasdaq_symbol', 'isin', 'us_code', 'security_id'. |
countries | list or str | optional | 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. |
security_types | list or str | optional | The security types to filter for. If not specified then will select all security types by default. See SECTYPE enum. |
allocate_isins | bool, default True | optional | Whether the request should allocate any new ISINs for plans that are ISIN-limited. The request will drop any rows that would create new allocations. |
Returns
pd.Dataframe
The data converted into a DataFrame.
See also
Adjustment factors field descriptions for further details.
API method
1 2 3 4 5 6 7 8 9
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,
allocate_isins: bool = True,
) -> pd.DataFrame Example usage
1 2 3 4 5 6 7 8 9 10 11 12 13
import databento as db
client = db.Reference("$YOUR_API_KEY")
df_raw = client.adjustment_factors.get_range(
symbols=["MSFT"],
stype_in="raw_symbol",
start="2019",
end="2020",
countries=["US"],
)
print(df_raw.head()) Example response
1 2 3 4 5 6 7 8
security_id event_id event issuer_name security_type ... dividend_currency frequency option detail ts_created ex_date ... 2019-02-20 S-39827 E-1443840-DIV DIV Microsoft Corporation EQS ... USD INT 1 INT Dividend (cash) of USD0.46/EQS 2024-09-23 00:25:46.589794+00:00 2019-05-15 S-39827 E-1550148-DIV DIV Microsoft Corporation EQS ... USD FNL 1 FNL Dividend (cash) of USD0.46/EQS 2024-09-23 00:28:54.651339+00:00 2019-08-14 S-39827 E-1617896-DIV DIV Microsoft Corporation EQS ... USD INT 1 INT Dividend (cash) of USD0.46/EQS 2024-09-23 00:32:47.230682+00:00 2019-11-20 S-39827 E-1669990-DIV DIV Microsoft Corporation EQS ... USD INT 1 INT Dividend (cash) of USD0.51/EQS 2024-09-23 00:36:33.357489+00:00 [4 rows x 27 columns]
Security master
Reference.security_master.get_last
Make a streaming request for the latest security master data from Databento.
Each record represents 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
| Parameter | Type | Required | Description |
|---|---|---|---|
symbols | list or str | optional | 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 | SType or str, default 'raw_symbol' | optional | 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', 'listing_id', 'issuer_id', 'security_id'. |
countries | list or str | optional | 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. |
security_types | list or str | optional | The security types to filter for. If not specified then will select all security types by default. See SECTYPE enum. |
allocate_isins | bool, default True | optional | Whether the request should allocate any new ISINs for plans that are ISIN-limited. The request will drop any rows that would create new allocations. |
Returns
pandas.Dataframe
The data converted into a DataFrame.
See also
Security master field descriptions for further details.
API method
1 2 3 4 5 6 7
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,
allocate_isins: bool = True,
) -> pd.DataFrame Example usage
1 2 3 4 5 6 7 8 9 10
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
1 2 3
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
| Parameter | Type | Required | Description |
|---|---|---|---|
start | pd.Timestamp, datetime, date, str, or int | required | 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 | pd.Timestamp, datetime, date, str, or int | optional | 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. If None, then will return all data available after start. |
index | str, default 'ts_effective' | optional | The index column to use for filtering the start and end time range and record ordering. Use any of 'ts_effective' or 'ts_record'. |
symbols | list or str | optional | 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 | SType or str, default 'raw_symbol' | optional | 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', 'listing_id', 'issuer_id', 'security_id'. |
countries | list or str | optional | 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. |
security_types | list or str | optional | The security types to filter for. If not specified then will select all security types by default. See SECTYPE enum. |
allocate_isins | bool, default True | optional | Whether the request should allocate any new ISINs for plans that are ISIN-limited. The request will drop any rows that would create new allocations. |
Returns
pd.Dataframe
The data converted into a DataFrame.
See also
Security master field descriptions for further details.
API method
1 2 3 4 5 6 7 8 9 10
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,
allocate_isins: bool = True,
) -> pd.DataFrame Example usage
1 2 3 4 5 6 7 8 9 10 11
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
1 2 3 4 5 6 7 8 9 10 11 12
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