Time Series Data

Many of our viaNexus Data Platform Data endpoints access time series data--data that you can time-window via dates and times. These endpoints use our GET /data method with different key and subkey path parameters.

HTTP requests, like the following Dividends request, follow the GET /data request pattern.

Request Pattern:

BASE_URL/data/core/DATASET/:key/:subkey?token=YOUR_TOKEN&YOUR_QUERY_PARAMS

Example Request:

You can execute the following example request after applying a valid token in place of YOUR_TOKEN in the requests.

https://api.blueskyapi.com/v1/data/core/advanced_dividends/aapl?token=YOUR_TOKEN

Need a token? Start your Free Trial, and then apply a token to your API Reference session.

Request Components:

Component	Description
`BASE_URL`	`https://api.blueskyapi.com/v1/`
`DATASET`	Dataset ID as specified in the endpoint's reference page. For example, the Stock Quote reference page specifies Dataset ID `QUOTE`.
`:key`	The `key` is the primary index value to query on. For example, the symbol `aapl` is used as the key in method call `/data/core/advanced_dividends/aapl`. The reference page's Path Parameters section marks the key attribute. For example, the Stock Quote endpoint's key attribute is `symbol`. The `:key` now supports multiple identifier types, please reference Identifier Resolution section below.
`:subkey`	Optional. A `subkey` is a secondary index value to query on, in addition to the `key`. For example, the reference ID `2733643` is used as the subkey in method call `/data/core/advanced_dividends/aapl/2733643`. If a dataset has a secondary index, the reference page's Path Parameters section marks the subkey attribute with the label `subkey`. For example, the Dividends endpoint's subkey attribute is `refid`.
`TOKEN`	An API Token authorized with read permissions for the dataset.

You can fetch multiple primary index (:key) of time series endpoint by specifiying a Comma separated lits, for example: [https://api.blueskyapi.com/v1/data/core/advanced\_dividends/aapl](https://api.blueskyapi.com/v1/data/core/advanced_dividends/aapl),msft,tsla?token\=YOUR\_TOKEN

Identifier Resolution

The :key now supports multiple identifier types. When a request is made, the system resolves the key in the following order:

FIGI
- Exchange-level FIGI.
- Example: /data/core/advanced_dividends/BBG000B9Y5X2 → resolves to AAPL.
ISIN
- Resolves to the security associated with the ISIN.
- If the security trades on multiple exchanges, resolution defaults to the primary exchange.
- Example: data/core/historical_prices/US0378331005 → resolves to AAPL.
LEI
- Returns all securities issued by the organization with that LEI.
Symbol
- If the key is a symbol, the system resolves it by checking supported conventions in order:
  - INET
  - CMS
  - CQS

More Examples:

You can execute the following example requests after applying a valid token in place of YOUR_TOKEN in the requests.

https://api.blueskyapi.com/v1/data/core/quote/aapl?token=YOUR_TOKEN - Gets the latest stock quote for Apple.
https://api.blueskyapi.com/v1/data/core/quote/aapl,msft?token=YOUR_TOKEN - Gets the latest stock quote for Apple and Microsoft.
https://api.blueskyapi.com/v1/data/core/advanced_dividends/aapl?token=YOUR_TOKEN - Gets the latest dividends record for Apple.
https://api.blueskyapi.com/v1/data/core/advanced_dividends/aapl?token=YOUR_TOKEN&last=4 - Gets the last four dividends records for Apple.
https://api.blueskyapi.com/v1/data/core/advanced_dividends/aapl?token=YOUR_TOKEN&on=2022-06-25 - Gets the dividends record published on a specific date.
https://api.blueskyapi.com/v1/data/core/advanced_dividends/aapl?token=YOUR_TOKEN&from=2022-02-13&to=2022-07-20 - Gets the dividends records published within a specific date range.
https://api.blueskyapi.com/v1/data/core/advanced_dividends/aapl/2733643?token=YOUR_TOKEN - Gets the dividends record for Apple that has a specific refid value.

Need a token? Start your Free Trial

Query Parameters

You can use query parameters with time series endpoints to filter results based on supported criteria. In particular, date filtering is available through the Supported Ranges parameters.

Date Filtering

Some endpoints include a date-based index that allows you to filter data by a specific date or range of dates. The relevant date attribute is identified in the endpoint's Response Attributes section (look for the date label). For example, the Stock Quote endpoint uses fiscaldate as its date index.

You can filter by:

Parameter	Type	Details
range	string	Optional. Returns data for a given range. Supported ranges described below.
calendar	boolean	Optional. Boolean. Used in conjunction with `range` to return data in the future.
limit	number	Optional. Limits the number of results returned. Defaults to 1 when no date or range {subkey} is specified
offset	number	Optional. Provides pagination. Skip n rows (≥ 0).
subattribute	string	Optional. Allows you to query time series by fields in the result set. All time series data is stored by ID, then key, then subkey. If you want to query by any other field in the data, you can use `subattribute`. For example, news may be stored as `/news/{symbol}/{newsId}`, and the result data returns the keys id, symbol, date, sector, hasPaywall, lang By default you can only query by symbol or id. Maybe you want to query all news where the language is English. Your query would be: /time-series/news?subattribute=lang\|en The syntax is subattribute={keyName1}\|{value1},{keyName2}\|{value2} Both the key name and the value are case sensitive. A pipe symbol (`\|`) is used to represent "equal to", and a tilde symbol (`~`) is used to represent "not equal to".
dateField	string	Optional. All time series data is stored by a single date field, and that field is used for any range or date parameters. You may want to query time series data by a different date in the result set. To change the date field used by range queries, pass the case sensitive field name with this parameter. For example, if you want to retrieve data based on when it was last updated, you can use the `updated` field. In that case, your query would look like: `dateField=updated&from=2023-05-01`
from	string	Optional. Returns data on or after the given from date. Format `YYYY-MM-DD`
to	string	Optional. Returns data on or before the given to date. Format `YYYY-MM-DD`
on	string	Optional. Returns data on the given date. Format `YYYY-MM-DD`
last	number	Optional. Returns the latest n number of records in the series
next	number	Optional. Returns the next n number of records in the series
first	number	Optional. Returns the first n number of records in the series
filter	string	Optional. The standard filter parameter. Filters return data to the specified comma delimited list of keys (case-sensitive)
format	string	Optional. The standard format parameter. Returns data as JSON by default. See the data format section for supported types.
sort	string	Optional. Specify the order of results, either `ASC` or `DESC`. Historical queries, including queries that use last, will default to descending date order (e.g. first record returned is most recent record). Forward looking queries, including queries that use first or specify calendar, will default to ascending date order (e.g. first record returned is nearest record in the future or from the start).
interval	number	Optional. Return every `nth` record in the result

Supported Ranges

Parameter	Details
today	Returns data for today
yesterday	Returns data for yesterday
ytd	Returns data for the current year
last-week	Returns data for Sunday-Saturday last week
last-month	Returns data for the last month
last-quarter	Returns data for the last quarter
d	Use the short hand `d` to return a number of days. Example: `2d` returns 2 days. If `calendar=true`, data is returned from today forward.
w	Use the short hand `w` to return a number of weeks. Example: `2w` returns 2 weeks. If `calendar=true`, data is returned from today forward.
m	Use the short hand `m` to return a number of months. Example: `2m` returns 2 months. If `calendar=true`, data is returned from today forward.
q	Use the short hand `q` to return a number of quarters. Example: `2q` returns 2 quarters. If `calendar=true`, data is returned from today forward.
y	Use the short hand `y` to return a number of years. Example: `2y` returns 2 years. If `calendar=true`, data is returned from today forward.
tomorrow	Calendar data for tomorrow. Requires `calendar=true`
this-week	Calendar data for Sunday-Saturday this week. Requires `calendar=true`
this-month	Calendar data for current month. Requires `calendar=true`
this-quarter	Calendar data for current quarter. Requires `calendar=true`
next-week	Calendar data for Sunday-Saturday next week. Requires `calendar=true`
next-month	Calendar data for next month. Requires `calendar=true`
next-quarter	Calendar data for next quarter. Requires `calendar=true`
specific quarter	Use the short hand `Q[1-4]YYYY` to return a specific quarter for a given year. Example: `Q22020` returns from January 1, 2020 to March 31, 2020.
specific half	Use the short hand `H[1-2]YYYY` to return a specific half for a given year. Example: `H12020` returns from January 1, 2020 to June 30, 2020.
specific year	Use the short hand `YYYY` to return a specific half for a given year. Example: `2020` returns from January 1, 2020 to December 31, 2020.

Query parameters may vary depending on the endpoint. For details on the parameters supported by a specific endpoint, refer to its reference page in the API documentation.