Query Time Series Core Data#

Many of the IEX Cloud Data endpoints provide financial data in time series–the data can be queried based on time. The endpoints have time-windowing parameters to get data for specific times and time ranges.

For example, the HTTP request below queries for news on Ford on March 1st 2023.

Request:

https://api.iex.cloud/v1/data/CORE/NEWS/f?from=2023-03-01&to=2023-03-02&token=YOUR_API_TOKEN

Response:

[
  {
    "datetime": 1677683309000,
    "hasPaywall": false,
    "headline": "US post office buys 9,250 electric vans, 14,000 charge stations",
    "image": "https://cloud.iexapis.com/v1/news/image/2US9v5KvD2aRkqSqZgI0PGhIt9yRzse1boRqCSzLidFt",
    "imageUrl": "https://supplypro.s3.ca-central-1.amazonaws.com/wp-content/uploads/2022/02/04103603/US-postal-service.jpg",
    "lang": "en",
    "provider": "CityFalcon",
    "qmUrl": "https://www.supplypro.ca/us-post-office-buys-9250-electric-vans-14000-charge-stations/",
    "related": "2FI-GD,F,STLA",
    "source": "Supply Professional magazine",
    "summary": "WASHINGTON (AP) — The US Postal Service is buying 9,250 Ford Motor Co. electric vans and 14,000 charging stations as part of a move to switch its fleet to electric vehicles. The service also is buying another 9,250 internal combustion vans from Fiat Chrysler in North America, now part of Amsterdam-based Stellantis. The Fiat Chrysler […] The post US post office buys 9,250 electric vans, 14,000 charge stations appeared first on Supply Professional .",
    "symbol": "F",
    "url": "https://cloud.iexapis.com/v1/news/article/2US9v5KvD2aRkqSqZgI0PGhIt9yRzse1boRqCSzLidFt",
    "uuid": "2US9v5KvD2aRkqSqZgI0PGhIt9yRzse1boRqCSzLidFt",
    "id": "NEWS",
    "key": "F",
    "subkey": "2US9v5KvD2aRkqSqZgI0PGhIt9yRzse1boRqCSzLidFt",
    "date": 1677683309000,
    "updated": 1677686924000
  },
  {
    "datetime": 1677669006000,
    "hasPaywall": false,
    "headline": "Tesla''s ''2016-2018'' Woes Vs. Rivian''s Current Challenges: Munster Highlights 1 Key Difference",
    "image": "https://cloud.iexapis.com/v1/news/image/11wmNdGowCeuHLxYMaNghjh0oMybiVUFQYxLxhagI5p7",
    "imageUrl": "https://cdn.benzinga.com/files/imagecache/1456x800/images/story/2023/03/01/tesla_photo_by_hadrian_on_shutterstock.jpg",
    "lang": "en",
    "provider": "CityFalcon",
    "qmUrl": "https://www.benzinga.com/analyst-ratings/analyst-color/23/03/31113421/teslas-2016-2018-woes-vs-rivians-current-challenges-munster-highlights-1-key-differ",
    "related": "F,TSLA,TL0-GD,TL0-GS,TL0-GH,TL0-GM,TL0-GF,TL0-GB,TL0-GY,TL0-GI,RIVN,LCID,NVDA,NVD-GD,NVD-GS,NVD-GH,NVD-GM,NVD-GF,NVD-GB,NVD-GY,NVD-GI",
    "source": "Benzinga",
    "summary": "Electric vehicle startup Rivian Automotive Inc. (NASDAQ: NVDA ) reported on Tuesday its fourth-quarter revenue that missed expectations and also issued underwhelming 2023 production guidance. What Happened: Rivian joined Ford Motor Co. (NYSE: F ) with the recent “EV production troubles,” Deepwater Asset Management co-founder Gene Munster tweeted following a review of the earnings report. He noted that the company blamed the supply chain for the soft production guidance. See Also: Best Electric Vehicle Stocks Lucid Group Inc. ''s (NASDAQ: LCID ) issue, however, has to do with demand, Munster said. The fund manager recalled Musk’s acknowledgment of a “production hell” in 2016 and said many were bracing for the other EV startups to experience the same challenges. “The difference is in 2016-2018 … Full story available on Benzinga.com",
    "symbol": "F",
    "url": "https://cloud.iexapis.com/v1/news/article/11wmNdGowCeuHLxYMaNghjh0oMybiVUFQYxLxhagI5p7",
    "uuid": "11wmNdGowCeuHLxYMaNghjh0oMybiVUFQYxLxhagI5p7",
    "id": "NEWS",
    "key": "F",
    "subkey": "11wmNdGowCeuHLxYMaNghjh0oMybiVUFQYxLxhagI5p7",
    "date": 1677669006000,
    "updated": 1677672620000
  }
]

The query parameter settings from=2023-03-01 and to=2023-03-02 filter on results from March 1st 2023 up to but not inluding March 2nd 2023.

You can query other IEX Cloud time series data similarly. Here we’ll demonstrate querying the Cash Flow IEX Cloud Data endpoint.

Prerequisite

IEX Cloud Apperate account - Create one here.

Note

If there are grayed-out endpoints you want to call, you can purchase the Data Bundles they belong to. The Data Bundles are available to purchase in the Console.

Step 1: Go to the Endpoint Reference Doc#

Let’s go to the Cash Flow endpoint reference page.

  1. Open the API Reference in your browser.

  2. Scroll down to the IEX Cloud Data section in the sidebar. If its contents are not expanded, click its name to show its contents.

  3. Since the Cash Flow endpoint is in the Fundamentals data bundle, scroll down further to Fundamentals in the sidebar.

  4. Click on Cash Flow (it’s the data endpoint name) to open its reference docs. The endpoint reference page appears. Below is an image of the Cash Flow reference page.

Tip

Here are some more ways to get to a time series data endpoint’s reference page.

  • In the data bundle article, click on the data endpoint name: Each data bundle article (see Data Bundles) lists the bundle’s endpoint names. Click a name to visit the corresponding endpoint reference doc.

    If you’re not sure which data bundle the data is in, use the Apperate Documentation search box–enter keywords that describe the data and browse the search results.

  • In the Console, click Open Docs in the endpoint’s Overview tab: Click on the endpoint’s name on the IEX Cloud Data console page. In the endpoint’s Overview tab, click Open Docs.

The endpoint reference page offers several resources to get you started using the endpoint.

The HTTP Request/Response shows a live example HTTP request and response.

The Response Attributes table describes the endpoint’s response properties. The image below shows some response attribute descriptions.

Note

Response attributes that are key, subkey, or date indexes are labeled as such. You can use the endpoint’s key path parameter and subkey (if it has one) path parameter to fine tune queries. You can furthermore, time-window your query by the data’s date index.

Tip

An endpoint doc’s Path Parameters section indicates the data’s key index and subkey index (if it has any).

Example HTTP Requests lists example requests you can click on to try out.

The top Cash Flow example request returns the latest Cash Flow record added to IEX Cloud Data. Let’s try it out.

Step 2: Execute an Example HTTP Request#

Click the top example HTTP request to see cash flow results for yourself. A response like the one below appears in your browser.

[
    {
        "capitalExpenditures": -153981933.26019996,
        "cashChange": 52921982765.789,
        "cashFlow": -7635540477.244902,
        "cashFlowFinancing": 804800407.0185003,
        "changesInInventories": 0,
        "changesInReceivables": 0,
        "currency": "USD",
        "depreciation": 300821632.50179994,
        "dividendsPaid": null,
        "exchangeRateEffect": null,
        "filingType": "6-K",
        "fiscalDate": "2022-07-31",
        "fiscalQuarter": 3,
        "fiscalYear": 2022,
        "investingActivityOther": null,
        "investments": null,
        "netBorrowings": -786885758368.2644,
        "netIncome": 1956976221.5984,
        "otherFinancingCashFlows": null,
        "reportDate": "2022-08-23",
        "symbol": "BNS",
        "totalInvestingCashFlows": 5990703186.795099,
        "id": "CASH_FLOW",
        "key": "BNS",
        "subkey": "quarterly",
        "date": 1659225600000,
        "updated": 1661439879000
    }
]

The response includes the attributes listed in the Response Attributes table. It also includes the following attributes: that reflect the index values and its last update timestamp.

  • id: Dataset ID

  • key: Key (primary) index

  • subkey: Subkey (secondary) index

  • updated: Last update timestamp

Let’s modify the request to get cash flow for a particular company.

Step 3: Query on Indexes#

You can use an endpoint’s key and subkey (if available) path parameters to fine-tune your query.

The Cash Flow endpoint, for example, takes a company ticker symbol as its key path parameter (see the Response Attributes table image shown earlier in this article).

Building off of the example Cash Flow request, let’s get Apple’s latest cash flow record. To get it, add Apple’s symbol AAPL as the key path parameter value after CASH_FLOW in the request URL.

Request:

https://api.iex.cloud/v1/data/CORE/CASH_FLOW/AAPL?last=1&token=YOUR_API_TOKEN

Response:

[
    {
        "capitalExpenditures": -2102000000,
        "cashChange": 48231000000,
        "cashFlow": 22892000000,
        "cashFlowFinancing": -27445000000,
        "changesInInventories": 5433000000,
        "changesInReceivables": 42242000000,
        "currency": "USD",
        "depreciation": 2805000000,
        "dividendsPaid": null,
        "exchangeRateEffect": null,
        "filingType": "10-Q",
        "fiscalDate": "2022-06-25",
        "fiscalQuarter": 3,
        "fiscalYear": 2022,
        "investingActivityOther": null,
        "investments": null,
        "netBorrowings": 55074000000,
        "netIncome": 19442000000,
        "otherFinancingCashFlows": null,
        "reportDate": "2022-07-29",
        "symbol": "AAPL",
        "totalInvestingCashFlows": 4234000000,
        "id": "CASH_FLOW",
        "key": "AAPL",
        "subkey": "quarterly",
        "date": 1656115200000,
        "updated": 1661439802000
    }
]

The response shows Apple’s latest cash flow record.

Important

key and subkey path parameters are restricted to primary and secondary indexes, respectively. For more information on the Unique Index components, see Understanding Datasets.

Next, let’s get a time range of cash flow data by using the GET /data endpoint time-windowing query parameters.

Step 4: Time-Window the Query#

You can use on=timestamp, range=some_range, or other time range query parameters to time-window your results.

For example, the following query gets Apple’s last six quarterly Cash Flow records.

Request:

https://api.iex.cloud/v1/data/CORE/CASH_FLOW/AAPL/quarterly?last=6&token=YOUR_API_TOKEN

The URL uses AAPL as its symbol (key index) and quarterly as its period (subkey index). The last=6 query parameter setting limits the request to the last six records (e.g., Apple’s last six quarters).

Response:

[
  {
    "capitalExpenditures": -3787000000,
    "cashChange": 51355000000,
    "cashFlow": 34005000000,
    "cashFlowFinancing": -35563000000,
    "changesInInventories": 6820000000,
    "changesInReceivables": 54180000000,
    "currency": "USD",
    "depreciation": 2916000000,
    "dividendsPaid": null,
    "exchangeRateEffect": null,
    "filingType": "10-Q",
    "fiscalDate": "2022-12-31",
    "fiscalQuarter": 1,
    "fiscalYear": 2023,
    "investingActivityOther": null,
    "investments": null,
    "netBorrowings": 43333000000,
    "netIncome": 29998000000,
    "otherFinancingCashFlows": null,
    "reportDate": "2023-02-03",
    "symbol": "AAPL",
    "totalInvestingCashFlows": -1445000000,
    "id": "CASH_FLOW",
    "key": "AAPL",
    "subkey": "quarterly",
    "date": 1672444800000,
    "updated": 1676300867000
  },
  {
    "capitalExpenditures": -3289000000,
    "cashChange": 48304000000,
    "cashFlow": 24127000000,
    "cashFlowFinancing": -26794000000,
    "changesInInventories": 4946000000,
    "changesInReceivables": 60932000000,
    "currency": "USD",
    "depreciation": 2865000000,
    "dividendsPaid": null,
    "exchangeRateEffect": null,
    "filingType": "10-K",
    "fiscalDate": "2022-09-24",
    "fiscalQuarter": 4,
    "fiscalYear": 2022,
    "investingActivityOther": null,
    "investments": null,
    "netBorrowings": 50542000000,
    "netIncome": 20721000000,
    "otherFinancingCashFlows": null,
    "reportDate": "2022-10-28",
    "symbol": "AAPL",
    "totalInvestingCashFlows": -1217000000,
    "id": "CASH_FLOW",
    "key": "AAPL",
    "subkey": "quarterly",
    "date": 1663977600000,
    "updated": 1676300867000
  },
  // more results ...
  {
    "capitalExpenditures": -2803000000,
    "cashChange": 63913000000,
    "cashFlow": 46966000000,
    "cashFlowFinancing": -28159000000,
    "changesInInventories": 5876000000,
    "changesInReceivables": 65253000000,
    "currency": "USD",
    "depreciation": 2697000000,
    "dividendsPaid": null,
    "exchangeRateEffect": null,
    "filingType": "10-Q",
    "fiscalDate": "2021-12-25",
    "fiscalQuarter": 1,
    "fiscalYear": 2022,
    "investingActivityOther": null,
    "investments": null,
    "netBorrowings": 40773000000,
    "netIncome": 34630000000,
    "otherFinancingCashFlows": null,
    "reportDate": "2022-01-28",
    "symbol": "AAPL",
    "totalInvestingCashFlows": -16106000000,
    "id": "CASH_FLOW",
    "key": "AAPL",
    "subkey": "quarterly",
    "date": 1640390400000,
    "updated": 1676300868000
  }
]

Congratulations on querying Cash Flow time series data. You can similarly query other IEX Cloud time series data endpoints.

What’s Next#

If you want to get stock quotes, see Example: Get Stock Quotes.

To dive into more core financial data queries using the Data API, see Querying Data.

To batch multiple data queries in a single call, check out Batch Data Queries.

Paginate with Chunks of Data using apperate.queryData() in JavaScript or using the GET /data REST endpoint directly. Pagination and handling large amounts of data has never been easier.

To learn more about Apperate’s APIs, visit the API Reference.

If want to combine core financial time series data with data from other datasets, check out Create Views.

If you need to store application data, learn how at Write Data in Real-time.