Source: https://databento.com/docs/api-historical/timeseries ## Time series ### Historical.timeseries.get\_range Makes a streaming request for time series data from Databento. This is the primary method for getting historical market data, instrument definitions, and status data directly into your application. This method only returns after all of the data has been downloaded, which can take a long time. For large requests, consider using [batch.submit\_job](https://databento.com/docs/api-historical/batch/batch-submit-job.md) instead. #### API method ```python Historical.timeseries.get_range( dataset: Dataset | str, start: pd.Timestamp | datetime | date | str | int, end: pd.Timestamp | datetime | date | str | int | None = None, symbols: Iterable[str | int] | str | int | None = None, schema: Schema | str = "trades", stype_in: SType | str = "raw_symbol", stype_out: SType | str = "instrument_id", limit: int | None = None, path: PathLike[str] | str | None = None, ) -> DBNStore ``` #### Parameters | Parameter | Type | Required | Description | | `dataset` | Dataset or str | required | The [dataset](https://databento.com/docs/api-historical/basics/datasets.md) code (string identifier). Must be one of the values from [list\_datasets](https://databento.com/docs/api-historical/metadata/metadata-list-datasets.md). | | `start` | pd.Timestamp, datetime, date, str, or int | required | The inclusive start of the request range. Filters on `ts_recv` if it exists in the schema, otherwise `ts_event`. 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. Filters on `ts_recv` if it exists in the schema, otherwise `ts_event`. 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. Defaults to the [forward filled](https://databento.com/docs/conventions/common-fields-enums-types.md#forward-filling-end-parameters) value of `start` based on the resolution provided. | | `symbols` | Iterable[str \ | int] or str or int | optional | The product 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. | | `schema` | Schema or str, default 'trades' | optional | The data record [schema](https://databento.com/docs/schemas/whats-a-schema.md). Must be one of the values from [list\_schemas](https://databento.com/docs/api-historical/metadata/metadata-list-schemas.md). | | `stype_in` | SType or str, default 'raw\_symbol' | optional | The [symbology type](https://databento.com/docs/api-historical/basics/symbology.md) of input `symbols`. Must be one of 'raw\_symbol', 'instrument\_id', 'parent', or 'continuous'. | | `stype_out` | SType or str, default 'instrument\_id' | optional | The [symbology type](https://databento.com/docs/api-historical/basics/symbology.md) of output symbols. Must be one of 'raw\_symbol', 'instrument\_id', 'parent', or 'continuous'. Must be a valid symbology combination with `stype_in`. See [symbology combinations](https://databento.com/docs/conventions/symbology.md#supported-symbology-combinations). | | `limit` | int | optional | The maximum number of records to return. If `None` then no limit. | | `path` | PathLike[str] or str | optional | The file path to stream the data to. It is recommended to use the ".dbn.zst" suffix. | #### Returns A [DBNStore](https://databento.com/docs/api-historical/helpers/dbn-store.md) object. A full list of fields for each schema is available through [Historical.metadata.list\_fields](https://databento.com/docs/api-historical/metadata/metadata-list-fields.md). #### Example usage ```python import databento as db client = db.Historical("$YOUR_API_KEY") data = client.timeseries.get_range( dataset="GLBX.MDP3", symbols=["ESM2"], schema="trades", start="2022-06-06T00:00:00", end="2022-06-10T00:10:00", limit=1, ) df = data.to_df() print(df.iloc[0].to_json(indent=4)) ``` #### Example response ```plaintext { "ts_event":1654473600070, "rtype":0, "publisher_id":1, "instrument_id":3403, "action":"T", "side":"A", "depth":0, "price":4108.5, "size":1, "flags":0, "ts_in_delta":18681, "sequence":157862, "symbol":"ESM2" } ``` ### Historical.timeseries.get\_range\_async Asynchronously request a historical time series data stream from Databento. Primary method for getting historical intraday market data, daily data, instrument definitions and market status data directly into your application. This method only returns after all of the data has been downloaded, which can take a long time. For large requests, consider using [batch.submit\_job](https://databento.com/docs/api-historical/batch/batch-submit-job.md) instead. #### API method ```python Historical.timeseries.get_range_async( dataset: Dataset | str, start: pd.Timestamp | datetime | date | str | int, end: pd.Timestamp | datetime | date | str | int | None = None, symbols: Iterable[str | int] | str | int | None = None, schema: Schema | str = "trades", stype_in: SType | str = "raw_symbol", stype_out: SType | str = "instrument_id", limit: int | None = None, path: PathLike[str] | str | None = None, ) -> Awaitable[DBNStore] ``` > **Info** > > This method is a [coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutines) and must be used with an [await](https://docs.python.org/3/reference/expressions.html#await) expression. #### Parameters | Parameter | Type | Required | Description | | `dataset` | Dataset or str | required | The [dataset](https://databento.com/docs/api-historical/basics/datasets.md) code (string identifier). Must be one of the values from [list\_datasets](https://databento.com/docs/api-historical/metadata/metadata-list-datasets.md). | | `start` | pd.Timestamp, datetime, date, str, or int | required | The inclusive start of the request range. Filters on `ts_recv` if it exists in the schema, otherwise `ts_event`. 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. Filters on `ts_recv` if it exists in the schema, otherwise `ts_event`. 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. Defaults to the [forward filled](https://databento.com/docs/conventions/common-fields-enums-types.md#forward-filling-end-parameters) value of `start` based on the resolution provided. | | `symbols` | Iterable[str \ | int] or str or int | optional | The product 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. | | `schema` | Schema or str, default 'trades' | optional | The data record [schema](https://databento.com/docs/schemas/whats-a-schema.md). Must be one of the values from [list\_schemas](https://databento.com/docs/api-historical/metadata/metadata-list-schemas.md). | | `stype_in` | SType or str, default 'raw\_symbol' | optional | The [symbology type](https://databento.com/docs/api-historical/basics/symbology.md) of input `symbols`. Must be one of 'raw\_symbol', 'instrument\_id', 'parent', or 'continuous'. | | `stype_out` | SType or str, default 'instrument\_id' | optional | The [symbology type](https://databento.com/docs/api-historical/basics/symbology.md) of output symbols. Must be one of 'raw\_symbol', 'instrument\_id', 'parent', or 'continuous'. Must be a valid symbology combination with `stype_in`. See [symbology combinations](https://databento.com/docs/conventions/symbology.md#supported-symbology-combinations). | | `limit` | int | optional | The maximum number of records to return. If `None` then no limit. | | `path` | PathLike[str] or str | optional | The file path to stream the data to. It is recommended to use the ".dbn.zst" suffix. | #### Returns A [DBNStore](https://databento.com/docs/api-historical/helpers/dbn-store.md) object. A full list of fields for each schema is available through [Historical.metadata.list\_fields](https://databento.com/docs/api-historical/metadata/metadata-list-fields.md). #### Example usage ```python import asyncio import databento as db client = db.Historical("$YOUR_API_KEY") coro = client.timeseries.get_range_async( dataset="GLBX.MDP3", symbols=["ESM2"], schema="trades", start="2022-06-06T00:00:00", end="2022-06-10T00:10:00", limit=1, ) data = asyncio.run(coro) df = data.to_df() print(df.iloc[0].to_json(indent=4)) ``` #### Example response ```plaintext { "ts_event":1654473600070, "rtype":0, "publisher_id":1, "instrument_id":3403, "action":"T", "side":"A", "depth":0, "price":4108.5, "size":1, "flags":0, "ts_in_delta":18681, "sequence":157862, "symbol":"ESM2" } ```