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_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_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: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 
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:

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.