Source: https://databento.com/docs/api-reference-data


# 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](https://databento.com/docs/api-reference-data/corporate-actions.md) provides point-in-time (PIT) corporate actions events with global coverage.
- [Adjustment factors](https://databento.com/docs/api-reference-data/adjustment-factors.md) provides end-of-day price adjustment factors for capital events, spanning multiple currencies for the same event.
- [Security master](https://databento.com/docs/api-reference-data/security-master.md) 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]($PLATFORM_HOSTNAME/portal/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](https://databento.com/docs/portal/api-keys.md#securing-your-api-keys).

#### Example usage

```python
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](https://databento.com/docs/conventions/symbology.md) 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](https://www.nasdaqtrader.com/trader.aspx?id=CQSsymbolconvention).

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` | [**I**nternational **S**ecurities **I**dentification **N**umber (ISIN)](https://www.isin.org/) - ISO 6166. |
| `us_code` | US domestic [**C**ommittee on **U**niform **S**ecurities **I**dentification **P**rocedure (CUSIP)](https://en.wikipedia.org/wiki/CUSIP) code. |
| `bbg_comp_id` | Bloomberg composite global ID. |
| `bbg_comp_ticker` | Bloomberg composite ticker. |
| `figi` | **F**inancial **I**nstrument **G**lobal **I**dentifier (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](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), 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](https://en.wikipedia.org/wiki/Unix_time).

The client library also handles several string-based timestamp formats based on [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).

- `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

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

#### Example usage

```python
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

```plaintext
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](https://databento.com/docs/api-reference-data/corporate-actions.md) requests per second.
- 100 [adjustment factors](https://databento.com/docs/api-reference-data/adjustment-factors.md) requests per second.
- 100 [security master](https://databento.com/docs/api-reference-data/security-master.md) 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](https://databento.com/docs/portal/api-keys.md#securing-your-api-keys).
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.

#### API method

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

#### Example usage

```python
import databento as db

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

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

| Parameter | Type | Required | Description |
| `key` | str | optional | 32-character API key. Found on your [API keys]($PLATFORM_HOSTNAME/portal/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. |


## 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](https://databento.com/docs/faqs/instruments-and-products.md#listings) 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](https://databento.com/docs/schemas/corporate-actions.md) dataset guide for further details.

#### API method

```python
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
```

#### 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](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), [Python datetime](https://docs.python.org/3/library/datetime.html#datetime-objects), [Python date](https://docs.python.org/3/library/datetime.html#date-objects), [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string, or [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) 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](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), [Python datetime](https://docs.python.org/3/library/datetime.html#datetime-objects), [Python date](https://docs.python.org/3/library/datetime.html#date-objects), [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string, or [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) 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](https://databento.com/docs/api-reference-data/basics/symbology.md) 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 | The event types to filter for. Takes any number of [event](https://databento.com/docs/conventions/corporate-actions-events.md)s per request. If not specified then will select **all** event types by default. See [EVENT](https://databento.com/docs/conventions/reference-data-enums.md#event) enum. |
| `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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/schemas/corporate-actions.md#fields) for further details.

#### Example usage

```python
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

```plaintext
                 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.

#### API method

```python
Reference.corporate_actions.list_events() -> dict[str, dict]
```

#### 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](https://databento.com/docs/datasets/corporate-actions.md#events) guide for information in text form.

#### Example usage

```python
import databento as db

client = db.Reference("$YOUR_API_KEY")

event_docs = client.corporate_actions.list_events()

print(event_docs["AGM"])
```
#### Example response

```json
{
    "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.

#### API method

```python
Reference.corporate_actions.list_enums() -> dict[str, list[dict]]
```

#### 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](https://databento.com/docs/conventions/reference-data-enums.md) for a lookup table of possible enumeration field values.

#### Example usage

```python
import databento as db

client = db.Reference("$YOUR_API_KEY")

enum_docs = client.corporate_actions.list_enums()

print(enum_docs["ACTION"])
```
#### Example response

```json
[
    {
        "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](https://databento.com/docs/faqs/instruments-and-products.md#listings) 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](https://databento.com/docs/datasets/adjustment-factors.md) dataset guide for further details.

#### API method

```python
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
```

#### 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](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), [Python datetime](https://docs.python.org/3/library/datetime.html#datetime-objects), [Python date](https://docs.python.org/3/library/datetime.html#date-objects), [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string, or [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) 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](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), [Python datetime](https://docs.python.org/3/library/datetime.html#datetime-objects), [Python date](https://docs.python.org/3/library/datetime.html#date-objects), [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string, or [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) 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](https://databento.com/docs/api-reference-data/basics/symbology.md) 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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/schemas/adjustment-factors.md#fields) for further details.

#### Example usage

```python
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

```plaintext
           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](https://databento.com/docs/faqs/instruments-and-products.md#listings) for a security.

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

> **See also**
>
> [Security master](https://databento.com/docs/datasets/security-master.md) dataset guide for further details.

#### API method

```python
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
```

#### 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](https://databento.com/docs/api-reference-data/basics/symbology.md) 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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/schemas/security-master.md#fields) for further details.

#### Example usage

```python
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

```plaintext
                                          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](https://databento.com/docs/faqs/instruments-and-products.md#listings) 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](https://databento.com/docs/datasets/security-master.md) dataset guide for further details.

#### API method

```python
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
```

#### Parameters

| Parameter | Type | Required | Description |
| `start` | pd.Timestamp, datetime, date, str, or int | required | The inclusive start of the request range. Takes [pd.Timestamp](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), [Python datetime](https://docs.python.org/3/library/datetime.html#datetime-objects), [Python date](https://docs.python.org/3/library/datetime.html#date-objects), [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string, or [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) 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](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), [Python datetime](https://docs.python.org/3/library/datetime.html#datetime-objects), [Python date](https://docs.python.org/3/library/datetime.html#date-objects), [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string, or [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) 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](https://databento.com/docs/api-reference-data/basics/symbology.md) 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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/conventions/reference-data-enums.md#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](https://databento.com/docs/schemas/security-master.md#fields) for further details.

#### Example usage

```python
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

```plaintext
                                          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
```