Introduction

IEX Cloud is a platform that makes financial data and services accessible to everyone.

API Reference

The IEX Cloud API is based on REST, has resource-oriented URLs, returns JSON-encoded responses, and returns standard HTTP response codes.

• The base url for the API is: https://cloud.iexapis.com/
• We support JSONP for all endpoints.

API Versioning

IEX Cloud will release new versions of the API when we make backwards-incompatible changes. We plan to support up to three active versions and will give advanced notice before releasing a new version or retiring an old version.

Backwards compatible changes:

• Adding new response attributes
• Adding new endpoints
• Adding new methods to an existing endpoint
• Adding new query string parameters
• Adding new path parameters
• Adding new webhook events
• Adding new streaming endpoints
• Changing the order of existing response attributes

Versions are added to the base url:

• Example: https://cloud.iexapis.com/stable
• Example: https://cloud.iexapis.com/v1
• Example: https://cloud.iexapis.com/beta

Current Version is v1 https://cloud.iexapis.com/v1/

Naming Convention

stable can be used to access the latest stable API version. For example, https://cloud.iexapis.com/stable/ beta can be used to access the latest API version. For example, https://cloud.iexapis.com/beta/

Endpoint Versioning

Endpoints may be in various states of alpha, beta, deprecated, etc. These indicate that an endpoint is either not yet subject to the requirements above (in the case of alpha, beta) or that it will be modified within the same API version (in the case of deprecated).

Deprecation

Both the IEX Cloud platform and the financial data ecosystem are constantly evolving, so it may become necessary to deprecate or disable some endpoints without versioning the entire API. Some situations which might require this action include changes to data contracts, critical useability issues, data universe expansion, etc. In these situations we will make every effort to provide alternative access to the underlying data or another provider’s data, and maintain the deprecated endpoints for a reasonable timeframe.

An endpoint will be removed ~6 Months from the time of deprecation with advance notice given via email and any alternative functionality available in both the API and official client libraries.

Attribution

Attribution is required for all users. It is as simple as putting “Data provided by IEX Cloud” somewhere on your site or app and linking that text to https://iexcloud.io. In case of limited screen space, or design constraints, the attribution link can be included in your terms of service.

<a href="https://iexcloud.io">Data provided by IEX Cloud</a>

When displaying a real-time price, you must display and link to IEX Cloud as the source near the price. The link is commonly placed below the price.

<a href="https://iexcloud.io">IEX Cloud</a>

How Credits Work

Credit Basics

Every dataset has an associated cost in credits based on:

• How much data is there? A dataset like Fundamentals includes hundreds of fields, while a single US Treasury Yield record might only have one field.
• How frequently does the data update? Quote updates millions of times per day, while Unemployment Rate might only update weekly
• How much does it cost to acquire the data? Some datasets we collect on our own, other datasets we purchase from upstream vendors. Ingesting and normalizing data has infrastructural costs on top of the base dataset cost.
• How much does it cost to distribute the data? With billions of API calls and bursty workloads around market hours, our infrastructure needs to scale up and down to ensure constant uptime and consistent delivery.

We call this associated credit cost the dataset’s weight. When you access a dataset, the total weight charged for the access will generally be the weight multiplied by the number of records received (taking into account the other possible credits or debits below). If you don’t receive any records, you won’t be charged for accessing that dataset. Each endpoint has its own weight which you can find in the documentation below. If the sum of these charges exceeds your monthly credit allocation, you will need to upgrade or purchase additional packages to continue accessing data.

Credit allocations reset on the first of each month at 00:00:00 UTC. API calls will return iexcloud-credits-used in the header to indicate the total number of credits consumed for the call, as well as an iexcloud-premium-credits-used to indicate the total number of premium credits consumed for the call. You can also track this information in the console.

Other credits and debits

API Use

All API calls will have an additional 1 credit access charge. This allows us to keep data costs lower across a wide variety of datasets. The following endpoints are omitted:

• Account endpoints
• Status endpoints
• Rules endpoints
• Timeseries Metadata and Inventory endpoints
• Files inventory endpoints
• Data points inventory endpoints
• Calls that result in 4XX or 5XX error codes

SSE connections will have a 1 credit charge on initial connection, not per record. Batch calls will have an additional 1 credit charge for the entire batch, regardless of the number of symbols or channels contained in the batch.

Cloud Cache

If you have an account in the individual or business tiers (rather than a legacy launch, grow, or scale account or a free start account), and you query the same API for data which has not changed, your cost will be reduced to 1 credit per record thanks to Cloud Cache.

As an example, lets say I access Cash Flow data for AAPL. It is the first time I have accessed it this month, and I only access the most recent record, so I am charged 1,000 credits. If I access this same API again this month, and it has not changed, I will only be charged 1 credit as the access has been cached. With Cloud Cache, you only pay for the new data you receive.

Reducing your credit spend

There are several strategies to reduce your costs when accessing datasets.

First, when developing be sure to experiment against the sandbox. Sandbox expenditures do not count against your monthly limit.

Second, decide on an appropriate history and update interval. For example, if I want to access 5 years of financial statements, I do not need to purchase a plan that allows me to access 5 years of financial statements each month. I can simply purchase enough packages to backfill 5 years once, then reduce my packages to maintain ongoing updates. You can also leverage APIs like data points to check when data has been updated.

Authentication

API Tokens

IEX Cloud authenticates your API requests using your account’s API tokens. To use any IEX Cloud API, you must pass an API token with each request. If you do not include your API token when making an API request, or use one that is incorrect or disabled, IEX Cloud returns an error.

IEX Cloud provides two types of API tokens: publishable and secret.

• Publishable API tokens are meant solely to identify your account with IEX Cloud, they aren’t secret. They can be published in places like your website JavaScript code, or in an iPhone or Android app.

• Secret API tokens should be kept confidential and only stored on your own servers. Your account’s secret API token can perform any API request to IEX Cloud.

Protecting Your API Tokens

• Keep your secret token safe. Your secret token can make any API call on behalf of your account, including changes that may impact billing such as enabling pay-as-you-go charges. Do not store your secret token in your version control system. Do not use your secret token outside your web server, such as a browser, mobile app, or distributed file.
• Monitor usage of your API for anomalies. If you observe unauthorized or abnormal usage, rotate your API token. IEX Cloud provides multiple options to address abnormal usage. ..* You may use the IEX Cloud console to rotate an API token. Rotating a token will disable access to IEX Cloud for the rotated token within 10 seconds. ..* You may use the IEX Cloud API or console to disable pay-as-you-go. This may prevent unexpected charges due to unauthorized or abnormal usage.
• Do not embed API keys directly in code. Instead of directly embedding API keys in your application’s code, put them in environment variables or in include files that are stored separately from the bulk of your code—outside the source repository of your application. Then, if you share your code, the API keys will not be included in the shared files.
• Do not store API tokens in inside your application’s source control. If you store API tokens in files, keep the files outside your application’s source control system. This is particularly important if you use a public source code management system such as GitHub.
• Limit access with restricted tokens. IEX Cloud console will allow you to specify the IP addresses or referrer URLs associated with each token, reducing the impact of a compromised API token.
• Use independent API tokens for different apps. This limits the scope of each token. If an API token is compromised, you can rotate the impacted token without impacting other API tokens.

Error Codes

IEX Cloud uses HTTP response codes to indicate the success or failure of an API request.

General HTML status codes

2xx Success.

4xx Errors based on information provided in the request

5xx Errors on IEX Cloud servers

IEX Cloud HTTP Status Codes

Security

We provide a valid, signed certificate for our API methods. Be sure your connection library supports HTTPS with the SNI extension.

Request Limits

IEX Cloud only applies request limits per IP address to ensure system stability. We limit requests to 100 per second per IP measured in milliseconds, so no more than 1 request per 10 milliseconds. We do allow bursts, but this should be sufficient for almost all use cases. Note that Sandbox Testing has a request limit of 10 requests per second measured in milliseconds.

SSE endpoints are limited to 50 symbols per connection. You can make multiple connections if you need to consume more than 50 symbols.

OAuth / OIDC ^BETA

IEX Cloud provides the OpenID Connect identity layer on top of OAuth 2.0, allowing client applications to verify users’ identity and obtain information necessary to interact with the IEX Cloud API on their behalf.

IEX Cloud currently provides the Authorization Code Flow (corresponding to the OAuth 2.0 Authorization Code Grant), which is suitable for most applications. Support for the Proof Key for Code Exchange (PKCE), which is suitable for applications which cannot safely store client secrets (e.g. browser-based single page applications) is planned for Q3/Q4 2021.

Setup and Configuration

Business users can create new applications from the IEX Cloud console. Each application must be configured with a name, description, redirect URL, and a set of authorization scopes. Upon creation, each application will have an associated clientId and clientSecret which are used in the authorization flow. Complete client examples in NodeJS and Python are available on our Github.

Authorization Scopes

Each application must choose what information it requires from its users. Currently, we have a few authorization scopes:

• profile: read access to a user’s email address and account type (either individual or business).
• read:sandbox: read access to a sandbox token for the user
• read:pk: read access to a publishable token for the user (claim is token)

Note: Token lifetime is tethered to the OAuth grant. When the grant expires, or when a user revokes application access, usage of the token will be blocked. The default expiration is 30 days for Access, 180 days for Refresh.

Note: Additions to scope after application authorization will require users to re-authorize the added access.

Getting Started

Complete examples, including information about registering a new application, integrating login/logout, and access user information is available on our Github. These examples are in NodeJS and Python, but the setup, configuration, and usage is generic.

OAuth Benefits

By leveraging IEX Cloud’s OAuth integration, one can very easily authenticate and acquire user information without having to build separate login infrastructure. With seamless access to publishable tokens, a user’s own data budget and data access policies are used, rather than relying on the application’s account and message budget. Though you could achieve similar functionality by having users upload their own publishable tokens, these tokens would not have lifecycle hooks (e.g. if the user revoked the token, this would not be exposed to the application).

Additionally, the combined OAuth + Token solution means that client libraries and access is identical whether you’re in an OAuth context or not. If you are access data directly, use your token; if you’re accessing data on behalf of a user, authenticate and authorize with OAuth then simply use their token. No changes in existing client libraries or accessor code is necessary.

Support

We are looking to migrate to a more centralized, scalable community support site in 2021. In the meantime, please consult the following links for information and support.

• Status Page
• Help Center
• Getting started
• Blog

Have a question or want to report a problem regarding the IEX Cloud API?

Please email us with the below information:

• Email account associated with your IEX Account
• Date/time of the issue
• What you did
• What you expected to happen
• What actually happened
• Additional relevant information

Disclaimers

• Required: If you display any delayed price data, you must display “15 minute delayed price” as a disclaimer.
• Required: If you display latestVolume you must display “Consolidated Volume in Real-time” as a disclaimer.
• Required: If you use cash flow, income statement, balance sheet, financials, or fundamentals endpoints, use must display “Data provided by New Constructs, LLC © All rights reserved.”
• Some data provided by EDI
• Some real-time and delayed market data provided by Exegy
• Note on pricing data: All CTA and UTP pricing data is delayed at least 15 minutes.

Guides

REST How-To

Making your first REST API call is easy and can be done from your browser.

You will need:

• Your publishable token which is found in the Console.
• The URL for the type of data you would like to request.

REST calls are made up of:

• Base url. Example: https://cloud.iexapis.com
• Version. Example: beta
• Token. All REST requests require a valid token and can be added to a url like ?token=YOUR_TOKEN_HERE

Free IEX Price for Apple

https://cloud.iexapis.com/stable/tops?token=YOUR_TOKEN_HERE&symbols=aapl

Stock Quote for Apple

https://cloud.iexapis.com/stable/stock/aapl/quote?token=YOUR_TOKEN_HERE

Curl Quote for Apple From the Command Line

curl -k 'https://cloud.iexapis.com/stable/stock/aapl/quote?token=YOUR_TOKEN_HERE'

Excel How-To

IEX Cloud supports Excel and Google Sheets data import methods.

Excel

Excel provides the Webservice function to import data into a cell. We support this in endpoints like quote, stats, financials, cash-flow, balance-sheet, income, and dividends.

Example: Pull latest price for Apple

=WEBSERVICE("https://cloud.iexapis.com/stable/stock/aapl/quote/latestPrice?token=YOUR_TOKEN_HERE")

IEX Cloud provides an example Excel file that can be used to see how the Webservice function works.

Download it here - the Excel webservice function only works on Excel for Windows.

Please note, the highlighted column for latestUpdate is a formula that converts the Unix timestamp into an excel date/time. To get this to work you’ll have to put your token in column B1. And don’t forget that you need to refresh the workbook to update (CTRL + ALT + F9)

Google Sheets

Google Sheets provides IMPORT functions to populate cells with data.

Example: Pull latest price for Apple

=IMPORTDATA("https://cloud.iexapis.com/stable/stock/aapl/quote/latestPrice?token=YOUR_TOKEN_HERE")

Example: Next earnings report date for Apple

=IMPORTDATA("https://cloud.iexapis.com/stable/stock/aapl/estimates/1/reportDate?token=YOUR_TOKEN_HERE")

CSV Files

You can also return most endpoints as CSV by passing a query parameter of format=csv.

https://cloud.iexapis.com/stable/stock/aapl/quote?token=YOUR_TOKEN_HERE&format=csv

Developer Tools and Open Source

Client Libraries

IEX Cloud has a growing set of official and unofficial client libraries, open source apps, and integrations. More information is available on our Developer Community Page.

Official Libraries

Our official libraries are actively maintained by both IEX Cloud and the open source community. If you’re interested in a language not covered here, reach via our community page and/or vote on the corresponding tickets on our unofficial roadmap.

Name	Language	GitHub	Install
pyEX	Python
iexjs	JavaScript

Testing Sandbox

IEX Cloud provides all accounts a free, unlimited use sandbox for testing. Every account will be assigned two test tokens available via the Console. All sandbox endpoints function the same as production, so you will only need to change the base url and token.

We’ve also updated the Usage Report to allow you to view the number of test credits the same way as production credit usage.

How to Use

• The base url is https://sandbox.iexapis.com
• You can also test SSE with https://sandbox-sse.iexapis.com
• Your test token is available on the console by click the “View Test Data” toggle in the nav.
• All tier features are enforced at this time, but you are not limited by the number of calls you can make. You are not charged for test usage.

Test tokens look like Tpk_ and Tsk_

To make a call for test data, use the same url, but pass your test token.

API Usage

Common functionality across all APIs.

Query Parameters

• Parameter values must be comma-delimited when requesting multiple.
  • (i.e. ?symbols=SNAP,fb is correct.)
• Case does not matter when passing values to a parameter unless specified in the docs.
  • (i.e. Both ?symbols=fb and ?symbols=FB will work.)
• Be sure to url-encode the values you pass.
  • (i.e. ?symbols=AIG+ encoded is ?symbols=AIG%2b.)

Data Formats

Most endpoints support a format parameter to return data in a format other than the default JSON.

Supported formats

Filter Results

Most endpoints support a filter parameter to return a subset of data. Pass a comma-delimited list of response attributes to filter. Response attributes are case-sensitive and are found in the Response Attributes section of each endpoint.

Example: ?filter=symbol,volume,lastSalePrice will return only the three attributes specified.

Result Schema

In many cases, you want to know the type of returned data. As an example, say I want to build a SQL table from the results of an enpoint, and I want to know/verify the types of my columns.

Most endpoints support a schema parameter to return just the types of the result set. Simply pass schema=true and the result set will be an array of a single record containing the column names and data types of the resulting data.

Time Series

Time Series Endpoint

Time series is the most common type of data available, and consists of a collection of data points over a period of time. Time series data is indexed by a single date field, and can be retrieved by any portion of time.

To use this endpoint, you’ll first make a free call to get an inventory of available time series data.

HTTP REQUEST

# List all available time series data
GET /time-series

RESPONSE

{
  "id": "REPORTED_FINANCIALS",
  "description": "Reported financials",
  "key": "a valid symbol",
  "subkey": "10-K,10-Q",  
  "schema": {
    "type": "object",
    "properties": {
      "formFiscalYear": {
        "type": "number"
      },
      "formFiscalQuarter": {
        "type": "number"
      },
      "version": {
        "type": "string"
      },
      "periodStart": {
        "type": "string"
      },
      "periodEnd": {
        "type": "string"
      },
      "dateFiled": {
        "type": "string"
      },
      "reportLink": {
        "type": "string"
      },
      "adsh": {
        "type": "string"
      },
      "stat": {
        "type": "object"
      }
    }
  },
  "weight": 5000,
  "created": "2019-06-04 21:32:20",
  "lastUpdated": "2019-06-04 21:32:20"
}

A full inventory of time series data is returned by calling /time-series without a data id. The data structure returned is an array of available data sets that includes the data set id, a description of the data set, the data weight, a data schema, date created, and last updated date. The schema defines the minimum data properties for the data set, but note that additional properties can be returned. This is possible when data varies between keys of a given data set.

Each inventory entry may include a key and subkey which describes what can be used for the key or subkey parameter.

Once you find the data set you want, use the id to query the time series data.

HTTP REQUEST

# Get time series data
GET /time-series/{id}/{key?}/{subkey?}

Time series data is queried by a required data set id. For example, “REPORTED_FINANCIALS”. Some time series data sets are broken down further by a data set key. This may commonly be a symbol. For example, REPORTED_FINANCIALS accepts a symbol such as AAPL as a key. Data sets can be even further broken down by sub key. For example, REPORTED_FINANCIALS data set with the key AAPL can have a sub key of 10-Q or 10-K.

Keys and sub keys will be defined in the data set inventory.

Data Weighting

The time series inventory call is Free
Time series data weight is specified in the inventory call and applied per array item (row) returned.

Data Timing

Varies

Data Schedule

Varies

Data Source(s)

Varies

Notes

Access to each data point will be based on the source Stocks endpoint

Available Methods

GET /time-series
GET /time-series/{id}/{key?}/{subkey}

Examples

• /time-series/REPORTED_FINANCIALS/AAPL
• /time-series/REPORTED_FINANCIALS/AAPL/10-K
• /time-series/REPORTED_FINANCIALS/AAPL/10-Q?range=1y
• /time-series/REPORTED_FINANCIALS/AAPL/10-Q?range=next-week&calendar=true
• /time-series/REPORTED_FINANCIALS/AAPL/10-Q?last=2
• /time-series/REPORTED_FINANCIALS/AAPL/10-Q?first=3
• /time-series/REPORTED_FINANCIALS/AAPL/10-Q?from=2018-01-01&to=2019-06-01
• /time-series/REPORTED_FINANCIALS/AAPL/10-Q?from=2016-01-01&limit=10
• /time-series/REPORTED_FINANCIALS/AAPL/10-Q?on=2016-01-01
• /time-series/REPORTED_FINANCIALS/AAPL/10-Q?from=2010-01-01&interval=2&format=csv
• /time-series/FUNDAMENTALS/AAPL?limit=1&subattribute=fiscalQuarter|3,fiscalYear|2020

Path Parameters

Query Parameters

Supported Ranges

Response Attributes

Time series call returns an array of objects. The data returned varies by dataset ID, but each will contain common attributes.

Time series inventory call returns:

Time Series Metadata ^BETA

Time-Series presents us a with a powerful query interface on top of our data, while the inventory calls allow us to know the shape of the data contained therein. But sometimes we want to answer questions like “What are all the possible values of key for the time series id FUNDAMENTALS?” or “What time series ids contain data on AAPL?”

For these, we have time series metadata.

HTTP REQUEST

GET /metadata/time-series/{id}/{key?}/{subkey?}

RESPONSE

// metadata/time-series
[
  {
    "id":"ADVANCED_BONUS",
    "value":"ADVANCED_BONUS",
    "numberOfRecords":5149
  },
  {
    "id":"ADVANCED_DISTRIBUTION",
    "value":"ADVANCED_DISTRIBUTION",
    "numberOfRecords":1093
  },
  // ...
]

// metadata/time-series/FUNDAMENTALS
[
  {
    "key":"A",
    "value":"A",
    "numberOfRecords":127
  },
  {
    "key":"AA",
    "value":"AA",
    "numberOfRecords":41
  },
  {
    "key":"AAIC",
    "value":"AAIC",
    "numberOfRecords":108
  },
  // ...

// metadata/time-series/*/AAPL
[
  {
    "id":"ADVANCED_BONUS",
    "value":"ADVANCED_BONUS",
    "numberOfRecords": 3
  },
  {
    "id":"ADVANCED_DIVIDENDS",
    "value":"ADVANCED_DIVIDENDS",
    "numberOfRecords":36
  },
  {
    "id":"ADVANCED_SPLITS",
    "value":"ADVANCED_SPLITS",
    "numberOfRecords": 1
  },
  // ...
]

Data Weighting

The time series metadata call is Free.

Data Timing

Varies

Data Schedule

Varies

Data Source(s)

Varies

Available Methods

GET /metadata/time-series/{id}/{key?}/{subkey}

Examples

• /metadata/time-series/REPORTED_FINANCIALS
• /metadata/time-series/*/AAPL

Path Parameters

Calendar

Using the time series calendar parameter, you can use short-hand codes to pull future event data such as tomorrow, next-week, this-month, next-month, and more.

Subset of time series parameters used for calendar

Supported calendar ranges

Points and Files

Data Points let you access individual data values, while Files lets you conveniently access pregenerated files.

Data Points

Data points are available per symbol and return individual plain text values. Retrieving individual data points is useful for Excel and Google Sheet users, and applications where a single, lightweight value is needed. We also provide update times for some endpoints which allow you to call an endpoint only once it has new data.

To use this endpoint, you’ll first make a free call to list all available data points for your desired symbol, which can be a security or data category.

HTTP REQUEST

# List available data keys
GET /data-points/{symbol}

RESPONSE

[
  {
    "key": "QUOTE-LATESTPRICE",
    "weight": 1,
    "description": "Quote: latestPrice",
    "lastUpdated": "2019-04-15T13:56:39+00:00"
  },
  {
    "key": "LATEST-FINANCIAL-REPORT-DATE",
    "weight": 0,
    "description": "Latest financials report date available",
    "lastUpdated": "2019-04-15T08:08:10+00:00"
  },
  {
    "key": "LATEST-NEWS",
    "weight": 0,
    "description": "Timestamp of the latest available news item",
    "lastUpdated": "2019-04-15T13:50:11+00:00"
  },
  {
    "key": "PRICE-TARGET",
    "weight": 500,
    "description": "Price target average",
    "lastUpdated": "2019-04-15T12:00:08+00:00"
  },
]

Once you find the data point you want, use the key to fetch the individual data point.

HTTP REQUEST

# Get a data point
GET /data-points/{symbol}/{key}

Data Weighting

List available data keys Free
Get a data point: The weight specified in the data list.

Data Timing

Varies

Data Schedule

Varies

Data Source(s)

Varies

Notes

Access to each data point will be based on the source Stocks endpoint

Available Methods

• GET /data-points/{symbol}
• GET /data-points/{symbol}/{key}

Examples

• /data-points/aapl/QUOTE-LATESTPRICE

Response Attributes

Data point call returns a single plain text value Available data keys call returns:

Files

The Files API allows users to download bulk data files, PDFs, etc.

Lookup Available Files

HTTP REQUEST

# List all available file types
GET /files

RESPONSE

[
  {
    "id": "VALUENGINE_REPORT",
    "metadata": {
      "weight": "PREMIUM_VALUENGINE_REPORT",
      "bySymbol": true,
      "byDate": true,
      "numberOfDownloads": 3,
      "source": "ValueEngine",
      "contentType": "text/pdf",
      "extension": "pdf",
      "tags": [ ],
      "categories": [ ]
    },
    "lastUpdated": "2020-03-20T15:15:03+00:00"
  },

]

Lookup Available Symbols and/or Dates for File Types

For files that have bySymbol = true or byDate = true, this call will show what symbols and dates are available.

HTTP REQUEST

# List all available file types
GET /files/info/:id

RESPONSE

{
  "symbols": [],
  "dates": []
}

Download a file

This call returns an HTTP redirect to a one time secure URL. The URL expires after 1 minute.

HTTP REQUEST

# List all available file types
GET /files/download/:id?symbol={symbol}&date={date}

HTTP Redirect response

If the file schema specifies bySymbol = true, then pass a {symbol} query parameter.
If the file schema specifies byDate = true, then pass a {date} query parameter the format "YYYYMMDD".

Batch Requests

HTTP REQUEST

GET /stock/{symbol}/batch

RESPONSE

// .../symbol
{
  "quote": {...},
  "news": [...],
  "chart": [...]
}

// .../market
{
  "AAPL" : {
    "quote": {...},
    "news": [...],
    "chart": [...]
  },
  "FB" : {
    "quote": {...},
    "news": [...],
    "chart": [...]
  },
  // { ... }
}

Data Weighting

Based on each type of call

Examples

• /stock/aapl/batch?types=quote,news,chart&range=1m&last=10
• /stock/market/batch?symbols=aapl,fb,tsla&types=quote,news,chart&range=1m&last=5

Path Parameters

Query Parameters

Response Attributes

Responses will vary based on types requested. Refer to each endpoint for details.

Streaming Data

SSE Streaming

NOTE: Only included with paid subscription plans

We support Server-sent Events (SSE Streaming) for streaming data as an alternative to WebSockets. You will need to decide whether SSE streaming is more efficient for your workflow than REST calls. In many cases streaming is more efficient since you will only receive the latest available data. If you need to control how often you receive updates, then you may use REST to set a timed interval.

Snapshots

When you connect to an SSE endpoint, you should receive a snapshot of the latest message, then updates as they are available. You can disable this feature by passing a url parameter of nosnapshot=true

You can also specify a starting point for a snapshot by passing a url parameter of snapshotAsOf=EPOCH_TIMESTAMP where the value is an epoch timestamp

Curl Example

curl --header 'Accept: text/event-stream' https://cloud-sse.iexapis.com/stable/stocksUS\?symbols\=spy\&token\=YOUR_TOKEN

Curl Firehose Example

curl --header 'Accept: text/event-stream' https://cloud-sse.iexapis.com/stable/stocksUS\?token\=YOUR_TOKEN

Curl Example (Not authorized by UTP)

curl --header 'Accept: text/event-stream' https://cloud-sse.iexapis.com/stable/stocksUSNoUTP\?symbols\=spy\&token\=YOUR_TOKEN

Curl Firehose Example (Not authorized by UTP)

curl --header 'Accept: text/event-stream' https://cloud-sse.iexapis.com/stable/stocksUSNoUTP\?token\=YOUR_TOKEN

How Credits Are Counted

We use a reserve system for streaming endpoints due to high data rates. This is similar to how a credit card puts a hold on an account and reconciles the amount at a later time.

When you connect to an SSE endpoint, we will validate your API token, then attempt to reserve an amount of credits from your account. For example, 1000 credits.

If you have enough credits in your quota (if you have pay-as-you-go enabled on our legacy plans), we will allow data to start streaming.

We keep track of the number of messages streamed to your account during our reserve interval.

Once our reserve interval expires, we will reconcile usage. This means we will compare how many credits worth of messages were sent versus the number of credits we reserved. For example, if we delivered 1200 credits worth of messages, you would have used 200 more than we reserved, so we will apply 200 additional credits to your account. If we only delivered 100 credits worth of messages, we would add the 900 unused credits back to your account.

After we reconcile the credits, we will attempt another reserve.

The reserve and reconcile process is seamless and does not impact your data stream. If we attempt to reserve credits and your account does not have enough quota (and pay-as-you-go disabled on legacy accounts), then we will disconnect your connection. You can avoid service disruptions by ensuring you have sufficient credits, either by purchasing additional packages or, on legacy plans, by enabling pay-as-you-go.

When you disconnect from an endpoint, we will reconcile your credit usage immediately.

Firehose

Scale and Business plan users can firehose stream all symbols (excluding DEEP endpoints) by leaving off the symbols parameter.

Interval Streaming

Some SSE endpoints are offered on set intervals such as 1 second, 5 seconds, or 1 minute. This means we will send out messages no more than the interval subscribed to. This helps make message delivery more predictable.

Supported Endpoints

# Stock Quotes
# Firehose can be about 100 million credits worth of messages per day
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksUS?token=YOUR_TOKEN&symbols=spy'

# Stock Quotes No UTP
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksUSNoUTP?token=YOUR_TOKEN&symbols=spy'

# Stock Quotes OTC
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksOTC?token=YOUR_TOKEN&symbols=otcm'

# Stock Quotes every 1 second
# Can be up to 54,000 credits worth of messages per symbol per day
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksUS1Second?token=YOUR_TOKEN&symbols=spy'

# Stock Quotes every 1 second no UTP
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksUSNoUTP1Second?token=YOUR_TOKEN&symbols=spy'

# Stock Quotes every 1 second OTC
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksOTC1Second?token=YOUR_TOKEN&symbols=otcm'

# Stock Quotes every 5 seconds
# Can be up to 10,800 credits worth of messages per symbol per day
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksUS5Second?token=YOUR_TOKEN&symbols=spy'

# Stock Quotes every 5 seconds no UTP
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksUSNoUTP5Second?token=YOUR_TOKEN&symbols=spy'

# Stock Quotes every 5 seconds OTC
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksOTC5Second?token=YOUR_TOKEN&symbols=otcm'

# Stock Quotes every 1 minute
# Can be up to 900 credits worth of messages per symbol per day
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksUS1Minute?token=YOUR_TOKEN&symbols=spy'

# Stock Quotes every 1 minute no UTP
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksUSNoUTP1Minute?token=YOUR_TOKEN&symbols=spy'

# Stock Quotes every 1 minute OTC
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/stocksOTC1Minute?token=YOUR_TOKEN&symbols=otcm'

# Cryptocurrency Quote
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/cryptoQuotes?token=YOUR_TOKEN&symbols=btcusd'

# Cryptocurrency Book
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/cryptoBook?token=YOUR_TOKEN&symbols=btcusd'

# Cryptocurrency Events
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/cryptoEvents?token=YOUR_TOKEN&symbols=btcusd'

# Social Sentiment
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/sentiment?token=YOUR_TOKEN&symbols=spy'

# Forex / Currencies
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/forex?token=YOUR_TOKEN&symbols=USDCAD'

# News
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/news-stream?token=YOUR_TOKEN&symbols=spy'

# IEX TOPS
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/tops?token=YOUR_TOKEN&symbols=spy'

# IEX TOPS 1 second
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/tops1second?token=YOUR_TOKEN&symbols=spy'

# IEX LAST
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/last?token=YOUR_TOKEN&symbols=spy,aapl,tsla'

# IEX LAST 1 second
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/last1second?token=YOUR_TOKEN&symbols=spy,aapl,tsla'

# IEX DEEP
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=deep'

# IEX DEEP by channel
curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=auction'

curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=book'

curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=op-halt-status'

curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=official-price'

curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=security-event'

curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=trades'

curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=trade-breaks'

curl --header 'Accept: text/event-stream' 'https://cloud-sse.iexapis.com/stable/deep?token=YOUR_TOKEN&symbols=spy&channels=trading-status'

Node.js SSE client example

'use strict';
const request = require('request');
var stream;
var partialMessage;

function connect() {
  stream = request({
    url: 'https://cloud-sse.iexapis.com/stable/stocksUSNoUTP?token=YOUR_TOKEN&symbols=spy,ibm,twtr',
    headers: {
      'Content-Type': 'text/event-stream'
    }
  })
}
connect();

stream.on('socket', () => {
  console.log("Connected");
});

stream.on('end', () => {
  console.log("Reconnecting");
  connect();
});

stream.on('complete', () => {
  console.log("Reconnecting");
  connect();
});

stream.on('error', (err) => {
  console.log("Error", err);
  connect();
});

stream.on('data', (response) => {
  var chunk = response.toString();
  var cleanedChunk = chunk.replace(/data: /g, '');

  if (partialMessage) {
    cleanedChunk = partialMessage + cleanedChunk;
    partialMessage = "";
  }

  var chunkArray = cleanedChunk.split('\r\n\r\n');

  chunkArray.forEach(function (message) {
    if (message) {
      try {  
        var quote = JSON.parse(message)[0];
        console.log(quote);
      } catch (error) {
        partialMessage = message;
      }
    }
  });
});

function wait () {
  setTimeout(wait, 1000);
};

wait();

Rules Engine ^BETA

Rules Engine API

Evaluate thousands of data points per second and build event-driven, automated alerts using Rules Engine. You can access Rules Engine through the IEX Console or through our API using the guidelines below.

Your Secret API Token (sk_) should be used to interact with Rules Engine API endpoints. Make sure to not expose your secret token publicly. All interactions should be from a secure server. Find and manage your API Tokens through the console.

To create a rule:

• Call /rules/schema to understand what values can be used to create the rule
• Call /rules/create to create a rule
• Call /rules/info to check the status of your newly created rule

Rules Schema

Pull the latest schema for data points, notification types, and operators used to construct rules.

HTTP REQUEST

GET /stable/rules/schema

RESPONSE

{
  "schema": [
    {
      "label": "Symbol: Change %",
      "value": "changePercent",
      "type": "number",
      "scope": "state",
      "isLookup": false,
      "weight": 1,
      "weightKey": "STOCK_QUOTE",
    },
    {
      "label": "Symbol: Latest Price",
      "value": "latestPrice",
      "type": "number",
      "scope": "state",
      "isLookup": false,
      "weight": 1,
      "weightKey": "STOCK_QUOTE",
    },
    // { ... }
  ],
  "notificationTypes": [
    {
      "label": "Webhook",
      "value": "webhook",
      "weight": 100,
      "enabled": true,
    },
    {
      "label": "Google Cloud Function",
      "value": "googlefunctions",
      "weight": 1000,
      "enabled": true,
    },
    {
      "label": "Email",
      "value": "email",
      "weight": 20000,
      "enabled": true,
    },
    // { ... }
  ],
  "operators": {
    "number": [
      {
        "label": "is above",
        "value": ">",
      },
      {
        "label": "is above or equal to",
        "value": ">=",
      },
      {
        "label": "is below",
        "value": "<",
      },
      // { ... }
    ],
    "string": [
      {
        "label": "is",
        "value": "==",
      }
    ],
    "boolean": [
      {
        "label": "True",
        "value": "true",
      },
      {
        "label": "False",
        "value": "false",
      },
    ],
    "time": [
      {
        "label": "is within",
        "value": "within",
      }
    ],
  }
}

Available Methods

GET /stable/rules/schema

Examples

• /stable/rules/schema

Notes

If a schema object has “isLookup”: true, pass the value key to /stable/rules/lookup/{value}. This returns all valid values for the rightValue of a condition.

Response Attributes

Lookup Values

HTTP REQUEST

GET /stable/rules/lookup/{value}

RESPONSE

// sector
[
  {
    "value": "Basic Materials",
    "label": "Basic Materials",
    "type": "string",
    "formula": "",
    "scope": "lookup",
  },
  {
    "value": "Communication Services",
    "label": "Communication Services",
    "type": "string",
    "formula": "",
    "scope": "lookup",
  },
  // { ... }
]

Available Methods

GET /stable/rules/lookup/{value}

Examples

• /stable/rules/lookup/sector
• /stable/rules/lookup/IEXHaltStatus

Path Parameters

If a schema object has isLookup:true, then use the value (ex: changePercent, latestPrice, etc) as the {value} path parameter.

Response Attributes

Creating a Rule

This endpoint is used to both create and edit rules. Note that rules run be default after being created.

HTTP REQUEST

POST /stable/rules/create

RESPONSE

{
  "id": "f759e05a-7cda-44cc-9579-41178249be4a",
  "weight": 20001
}

Data Weighting

0

Available Methods

POST /stable/rules/create

Examples

JAVASCRIPT EXAMPLE

'use strict';
const Request = require('request-promise-native');
function connect() {
  Request({
    method: 'POST',
    url: 'https://cloud.iexapis.com/stable/rules/create',
    json: {
      token: '{YOUR_API_TOKEN}',
      ruleSet: 'AAPL',
      type: 'any',
      ruleName: 'My Rule',
      conditions: [
        ['changePercent','>',5],
        ['latestPrice','<',100]
      ],
      outputs: [
        {
          frequency: 60,
          method: 'email',
          to: 'your_email@domain'
        }
      ]
    },
  }).then((body) => {
    console.log(body);
  }).catch((err) => {
    console.log("Error in request", err);
  });
}

connect();

Post Parameters

Response Attributes

Pause and Resume

You can control the output of rules by pausing and resume per rule id.

HTTP REQUEST

POST /stable/rules/pause
POST /stable/rules/resume

RESPONSE

true

Available Methods

POST /stable/rules/pause POST /stable/rules/resume

Post Parameters

Response Attributes

Edit an Existing Rule

To edit an existing rule, use the same process as creating a rule, but include the rule id in the POST object.

Examples

JAVASCRIPT EXAMPLE

'use strict';
const Request = require('request-promise-native');
function connect() {
  Request({
    method: 'POST',
    url: 'https://cloud.iexapis.com/stable/rules/create',
    json: {
      token: {YOUR_API_TOKEN},
      id: "f759e05a-7cda-44cc-9579-41178249be4a",
      ruleSet: "AAPL",
      type: "any",
      ruleName: "My Rule",
      conditions: [
        ['changePercent','>',2],
        ['latestPrice','<',200]
      ],
      outputs: [
        {
          frequency: 60*60,
          method: 'email',
          to: '{Your Email}'
        }
      ]
    },
  }).then((body) => {
    console.log(body);
  });
}

connect();

Delete a Rule

You can delete a rule by using an HTTP DELETE request. This will stop rule executions and delete the rule from your dashboard. If you only want to temporarily stop a rule, use the pause/resume functionality instead.

HTTP REQUEST

DELETE /stable/rules/:id

RESPONSE

true

Available Methods

DELETE /stable/rules/:id

Path Parameters

Response Attributes

Get Rule Info

Rule information such as the current rule status and execution statistics.

HTTP REQUEST

GET /stable/rules/info/{id}

RESPONSE

[
  {
    "id": "f759e05a-7cda-44cc-9579-41178249be4a",
    "name": "My Apple Rule",
    "event": "AAPL",
    "dateCreated": "2020-02-25",
    "dateUpdated": "2020-02-25",
    "isActive": true,
    "ran": 157,
    "passed": 2,
    "sent": 2
  }
]

Available Methods

GET /stable/rules/info/{id}

Path Parameters

Response Attributes

List All Rules

List all rules that are currently on your account. Each rule object returned will include the current rule status and execution statistics.

HTTP REQUEST

GET /stable/rules

RESPONSE

[
  {
    "id": "f759e05a-7cda-44cc-9579-41178249be4a",
    "name": "My Apple Rule",
    "event": "AAPL",
    "dateCreated": "2020-02-25",
    "dateUpdated": "2020-02-25",
    "isActive": true,
    "ran": 157,
    "passed": 2,
    "sent": 2
  },
  {
    "id": "436a3520-5ae5-4497-b116-0152664bd1a8",
    "name": "My Tesla Rule",
    "event": "TSLA",
    "dateCreated": "2020-02-21",
    "dateUpdated": "2020-02-23",
    "isActive": false,
    "ran": 23,
    "passed": 0,
    "sent": 0
  },
  // { ... }
]

Available Methods

GET /stable/rules

Response Attributes

Get Log Output

If you choose logs as your rule output method, IEX Cloud will save the output objects on our server. You can use this method to retrieve those data objects.

HTTP REQUEST

GET /stable/rules/output/{id}

RESPONSE

Available Methods

GET /stable/rules/output/{id}

Path Parameters

Response Attributes

The response will be an array of objects. Each object will contain data defined by the keys in each rule.

Webhooks

If you choose webhooks as your rule output method, IEX Cloud will HTTP POST to a URL with your data object.

The POST is sent with Content-Type header as application/json. Default timeout for a response is 10 seconds

If you use an HTTPS URL for your webhook endpoint, your server must be correctly configured to support HTTPS with a valid server certificate.

HTTP POST JSON Example

{
  "data": {
    "id": "2342-12342ssd-2323xs23-asdfs",
    "event": "AAPL",
    "name": "My Rule",
    "data": {
      "latestPrice": 100.10
    },
    "timestamp": 1505779200000
  }
}

Response Attributes

Account

Credit Budget

Used to set an upper limit, “credit budget”, on pay as you go credits where you want to make sure not to go above a certain amount. Set the total credits you wish to consume for the month, and once that limit is reached, all API calls will stop until the limit is removed or increased.

HTTP REQUEST

POST /account/creditbudget

Data Weighting

Free

Notes

Requires SK token to access

Available Methods

POST /account/creditbudget

Query Parameters

Token Credit Limit

Set monthly credit limits for your publishable API tokens.

HTTP REQUEST

POST /account/tokenlimit

Data Weighting

Free

Notes

Requires SK token to access

Available Methods

POST /account/tokenlimit

Query Parameters

Metadata

Used to retrieve account details such as current tier, payment status, credit quota usage, etc.

HTTP REQUEST

GET /account/metadata

RESPONSE

{
  "payAsYouGoEnabled": true,
  "effectiveDate": 1547590582000,
  "endDateEffective": 1547830921000,
  "subscriptionTermType": "monthly",
  "tierName": "launch",
  "messageLimit": 1000000000, // Legacy field
  "creditLimit": 1000000000,
  "messagesUsed": 215141655, // Legacy field
  "creditsUsed": 215141655,
  "circuitBreaker": 3000000000
}

Data Weighting

Free

Data Timing

Free plans End of day
Paid plans Real-time

Notes

Requires SK token to access

Available Methods

GET /account/metadata

Pay As You Go

Used to toggle Pay-as-you-go on your account.

HTTP REQUEST

POST /account/payasyougo

Data Weighting

Free

Notes

Requires SK token to access

Available Methods

POST /account/payasyougo

Query Parameters

Signed Requests

Making your first Signed REST API requires a little more effort. This approach has been heavily based on Amazon’s V4 signing approach. The basic idea is to take your secret key, and use that to generate a cryptographic fingerprint of all aspects of your request, so they can be verified by the server, so the interception of the data over the network does not compromise your account. However, you must take care that your secret key for your publishable key is not compromised!

You will need:

• Your publishable token which is found in the console
• Your secret key for your publishable token, can be found below using the GET /account/signed API call
• The URL for the type of data you would like to request

Signed REST calls are made up of:

• Base url. Example: https://cloud.iexapis.com
• Version. Example: beta
• Token. All REST requests require a valid token and can be added to a url like ?token=YOUR_TOKEN_HERE
• The authorization header
• The x-iex-date header

Setting Up Signed Token

Signs a token, so it will require signed headers when a request is made using this token.

HTTP REQUEST

POST content-type:application/json { "token" : "SK_TOKEN", "tokenToSign" : "PK/SK_TOKEN_TO_BE_SIGNED", ("unsign" : true) } /account/signed

RESPONSE

{
  "secret" : "e2700e6b-3be0-4f31-a408-61365caa263a",
  "signedToken" : "pk_6b95e1fac3114f0392a5becd4d8f08e1"
}

Data Weighting

Free

Notes

• Requires SK token to access
• Only available to Grow, Scale, and Business plans

Examples

See below

Response Attributes

Getting the Secret for a Signed Token

Returns the secret for a token, thus making it “signed”.

HTTP REQUEST

GET /account/signed?token=SK_TOKEN&signedToken=TOKEN

RESPONSE

{
  "secret" : "e2700e6b-3be0-4f31-a408-61365caa263a",
}

Data Weighting

Free

Notes

• Requires SK token to access
• Only available to Grow, Scale, and Business plans

Examples

See below

Response Attributes

Examples on How to Make a Signed Request:

NODE.JS EXAMPLE

#!/usr/bin/env node

/*
Copyright 2019-2020 iexcloud. or its affiliates. All Rights Reserved.

This file is licensed under the Apache License, Version 2.0 (the "License").
You may not use this file except in compliance with the License. A copy of the
License is located at

https://www.apache.org/licenses/LICENSE-2.0

This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, either express or implied. See the License for the specific
language governing permissions and limitations under the License.
*/

const moment = require('moment');
const crypto = require('crypto');
const https  = require('https');

const method = 'GET'
const host = 'cloud.iexapis.com'

const access_key = process.env.IEX_PUBLIC_KEY // public key
const secret_key = process.env.IEX_SECRET_KEY // secret key for public key

const canonical_querystring = 'token=' + access_key ;
const canonical_uri = '/v1/stock/aapl/company'

var ts = moment.utc();
const iexdate = ts.format("YYYYMMDDTHHmmss") + 'Z';
const datestamp = ts.format("YYYYMMDD");

function sign(secret, data) {
    return crypto.createHmac('sha256', secret).update(data, "utf8").digest('hex');
};

function getSignatureKey(key, datestamp) {
    const signedDate = sign(key, datestamp);
    return sign(signedDate, 'iex_request');
}

if ( ! access_key || ! secret_key ) {
    console.warn('No access key is available.')
    process.exit(1);
}

const canonical_headers = 'host:' + host + '\n' + 'x-iex-date:' + iexdate + '\n';
const signed_headers = 'host;x-iex-date'
const payload = '';
const payload_hash = crypto.createHash('sha256').update(payload).digest('hex');
const canonical_request = method + '\n' + canonical_uri + '\n' + canonical_querystring + '\n' + canonical_headers + '\n' + signed_headers + '\n' + payload_hash;
const algorithm = 'IEX-HMAC-SHA256';
const credential_scope = datestamp + '/' + 'iex_request';
const string_to_sign = algorithm + '\n' +  iexdate + '\n' +  credential_scope + '\n' + crypto.createHash('sha256').update(canonical_request, "utf8").digest('hex');
const signing_key = getSignatureKey(secret_key, datestamp)
const signature = crypto.createHmac('sha256', signing_key).update(string_to_sign, "utf8").digest('hex');
const authorization_header = algorithm + ' ' + 'Credential=' + access_key + '/' + credential_scope + ', ' +  'SignedHeaders=' + signed_headers + ', ' + 'Signature=' + signature
const headers = {'x-iex-date':iexdate, 'Authorization':authorization_header}

const options = {
    host: host,
    port: 443,
    path: canonical_uri + "?" + canonical_querystring,
    method: 'GET',
    headers: headers
};

const req = https.request(options, function(res) {
    res.setEncoding('utf8');
    res.on('data', function(chunk) {
        var parsed = JSON.parse(chunk);
        console.log(parsed);
    });
});
req.end();

PYTHON EXAMPLE

#!/usr/bin/env python

# Copyright 2019-2020 iexcloud. or its affiliates. All Rights Reserved.
#
# This file is licensed under the Apache License, Version 2.0 (the "License").
# You may not use this file except in compliance with the License. A copy of the
# License is located at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
# OF ANY KIND, either express or implied. See the License for the specific
# language governing permissions and limitations under the License.

import sys, os, base64, datetime, hashlib, hmac
import requests # pip install requests

# ************* REQUEST VALUES *************
method = 'GET'
host = 'cloud.iexapis.com'

access_key = os.environ.get('IEX_PUBLIC_KEY')
secret_key = os.environ.get('IEX_SECRET_KEY')

canonical_querystring = 'token=' + access_key
canonical_uri = '/v1/stock/aapl/company'
endpoint = "https://" + host + canonical_uri

def sign(key, msg):
    return hmac.new(key, msg.encode('utf-8'), hashlib.sha256).hexdigest()

def getSignatureKey(key, dateStamp):
    kDate = sign(key, dateStamp)
    return sign(kDate, 'iex_request')

if access_key is None or secret_key is None:
    print('No access key is available.')
    sys.exit()

t = datetime.datetime.utcnow()
iexdate = t.strftime('%Y%m%dT%H%M%SZ')
datestamp = t.strftime('%Y%m%d') # Date w/o time, used in credential scope
canonical_headers = 'host:' + host + '\n' + 'x-iex-date:' + iexdate + '\n'
signed_headers = 'host;x-iex-date'
payload_hash = hashlib.sha256(('').encode('utf-8')).hexdigest()
canonical_request = method + '\n' + canonical_uri + '\n' + canonical_querystring + '\n' + canonical_headers + '\n' + signed_headers + '\n' + payload_hash
algorithm = 'IEX-HMAC-SHA256'
credential_scope = datestamp + '/' + 'iex_request'
string_to_sign = algorithm + '\n' +  iexdate + '\n' +  credential_scope + '\n' +  hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()
signing_key = getSignatureKey(secret_key, datestamp)
signature = hmac.new(signing_key, (string_to_sign).encode('utf-8'), hashlib.sha256).hexdigest()
authorization_header = algorithm + ' ' + 'Credential=' + access_key + '/' + credential_scope + ', ' +  'SignedHeaders=' + signed_headers + ', ' + 'Signature=' + signature

headers = {'x-iex-date':iexdate, 'Authorization':authorization_header}

# ************* SEND THE REQUEST *************
request_url = endpoint + '?' + canonical_querystring

print('\nBEGIN REQUEST++++++++++++++++++++++++++++++++++++')
print('Request URL = ' + request_url)
r = requests.get(request_url, headers=headers)

print('\nRESPONSE++++++++++++++++++++++++++++++++++++')
print('Response code: %d\n' % r.status_code)
print(r.text)

Usage

Used to retrieve current month usage for your account.

HTTP REQUEST

GET /account/usage/{type}

RESPONSE

{
  "monthlyUsage": 215200,
  "monthlyPayAsYouGo": 0,
  "dailyUsage": {
    "20190120": 115200, 
    "20190121": 100000
  },
  "tokenUsage": {
    "pk_123": 215200
  },
  "keyUsage": {
    "IEX_STATS": 0, 
    "EARNINGS": 115200, 
    "STOCK_QUOTES": 100000
  }
}

Data Weighting

Free

Data Timing

Real-time

Notes

• Requires SK token to access
• Billing resets on the first of every month at 00:00:00 UTC

Available Methods

GET /account/usage/{type}

Path Parameters

API System Metadata

Status

Used to retrieve current system status.

HTTP REQUEST

GET /status

RESPONSE

{
  "status": "up",
  "version": "1.32",
  "time": 1607979129127,
  "currentMonthAPICalls": 14225180421
}

Data Weighting

Free

Data Timing

Real-time

Available Methods

GET /status

Notes

No token required

Changelog

The following is a list of running updates to the IEX API.

V1

2022-05-26

• Added iexIndustry, iexSector, and iexTags attributes to the Company endpoint.

2021-08-26

• Fraud Factors Similarity Index endpoint and data was disabled/removed.

2021-08-16

• Fraud Factors Non-timely filings credit cost increased from 1 to 1,000 (premium endpoint)

2021-07-25

• Simplify naming convention for Dividends, Splits, and Stats. Each has 2 endpoints, a “Basic” version (or Key Stats for Stats) and a normal version, with the normal version including more information.

2021-07-15

• Updated prices for several endpoints and added 1 credit cost per API call. See the relevant help center article

2021-07-13

• Add Fundamental Valuations
• EOD Futures and EOD Options V2 reduced weight to 10 per record

2021-06-07

• Added new time series metadata endpoints
• Updated new Options and Futures refdata endpoints
• Deprecated relevant endpoint, use peers instead
• Updated IPO endpoint for new data provider, see IPO Calendar V2
• Added documentation for schema query parameter

2021-06-01

• Added new Options refdata and historical data endpoints
• Added new Futures refdata and historical data endpoints
• Deprecated old options endpoints

2021-05-12

• Premium Data: Added additional data to Estimates
• Added quarter/half/year options to range parameter for various time series endpoints.

2021-05-05

• Core Data: Add Futures Symbols
• Update: Upcoming events now supports querying for an exact date, to facilitate building better calendars and limiting overall credit cost

2021-04-05

• Added additional US treasuries
• Update: US treasury rate reduced from 1,000 per record to 100
• Update: Economic data rate reduced from 1,000 per record to 100
• Update: Mortgate data rate reduced from 1,000 per record to 100

2021-03-05

• Core Data: Added RIC Mapping

2021-02-11

• Core Data: Added pre and post market lists for UTP approved users.
• Core Data: Added two query parameters to Technical Indicators. indicatorOnly and lastIndicator

2021-01-27

• Premium Data: Added New Constructs research reports

2021-01-25

• Core Data: nextEarningsDate has been added back to Basic Stats and Stats

2020-08-10

• Premium Data: Stocktwits data readded as premium data.

2020-06-22

• Update: Giant Machines stock price widget weight reduced to 5

2020-06-01

• Removed: Intraday social sentiment from StockTwits is no longer available. Historical data is still available before June 1.

2020-04-07

• Premium Data: Added Kavout K-Score for China A-Shares

2020-03-20

• Premium Data: Added ValuEngine Stock Research Reports

2020-03-18

• Core Data: Added highTime, highSource, lowTime, lowSource, iexOpen, iexOpenTime, iexClose, iexCloseTime attributes to Stock Quote

2020-03-17

• Premium Data: Added BRAIN language metrics data

2020-03-16

• Premium Data: Added Audit Analytics data

2020-03-13

• Premium Data: Added Kavout data

2020-03-12

• Premium Data: Added Giant Machines stock price widget

2020-03-04

• Rules Engine: Beta API endpoints and documentation

2020-03-03

• Console: Added the ability to enable/disable premium data access per API token

2020-02-28

• Core Data: Added figi and cik to ref data
• Core Data: Added fiscalDate and currency to Balance Sheet
• Core Data: Added fiscalDate and currency to Cash Flow
• Core Data: Added fiscalDate and currency to Financials
• Core Data: Added fiscalDate and currency to Income Statement
• Core Data: Added currency to Price Targets

2020-02-27

• Premium Data: Added Brain Company 21 day ranking

2020-02-07

• Premium Data: Added Brain Company to premium data

2020-02-03

• Core Data: Added odd lot trades to Stock Quote

2020-01-17

• Premium Data: Added Precision Alpha to premium data

2019-12-09

• Rules Engine: Max number of rules per account changed from 10 to 500. Creating a rule remains free during the beta.

2019-12-05

• Premium Data: Added ExtractAlpha to premium data

2019-11-26

• Core Data: Added putCallRatio to the Stats endpoint

2019-11-25

• Core Data: Added Bonus Issue corporate actions endpoint
• Core Data: Added Distribution corporate actions endpoint
• Core Data: Added Return of Capital corporate actions endpoint
• Core Data: Added Rights Issue corporate actions endpoint
• Core Data: Added Right to Purchase corporate actions endpoint
• Core Data: Added Security Reclassification corporate actions endpoint
• Core Data: Added Security Swap corporate actions endpoint
• Core Data: Added Spinoff corporate actions endpoint
• Core Data: Added Splits corporate actions endpoint
  
  
• Core Data: Added historical time series data to the Daily Treasury Rates endpoint
• Core Data: Added historical time series data to the Oil Prices endpoint
• Core Data: Added historical time series data to the Natural Gas Prices endpoint
• Core Data: Added historical time series data to the Jet Fuel Prices endpoint
• Core Data: Added historical time series data to the Diesel Price endpoint
• Core Data: Added historical time series data to the Propane Prices endpoint
• Core Data: Added historical time series data to the Gas Prices endpoint
  
  
• Core Data: Added historical time series data to the Unemployment endpoint
• Core Data: Added historical time series data to the Total Housing Starts endpoint
• Core Data: Added historical time series data to the Mortgage Rates endpoint
• Core Data: Added historical time series data to the Real GDP endpoint

2019-11-20

• Rules Engine beta now available to paid plans. Collecting early user feedback.

2019-11-15

• Added subattribute and dateField parameters to Time Series
• Added 1 second, 5 second, and 1 minute conflation rates for forex real time streaming

2019-11-14

• Added retail money funds endpoint
• Added institutional money funds endpoint
• Added initial claims endpoint

2019-11-12

• Added Dividends endpoint. This greatly expands available dividends data and extends history to 12+ years.

2019-11-08

• Added historical news endpoint
• Added Fraud Factors to Premium Data.
• Fraud Factors Similarity Index endpoint
• Fraud Factors Non-Timely Filings endpoint

2019-11-07

• Added annual earnings and estimates where previously only quarterly was available.

2019-11-01

• Added calendar and range functionality to the time series endpoint. Now you can use short hand to query backwards or forward in time.

2019-10-29

• Introduced Premium Data on IEX Cloud
• Added Wall Street Horizon to Premium Data

2019-10-23

• Expanded dividends by 39k symbols and over 500k records

2019-10-14

• Added historical commodities endpoints

2019-10-11

• Core Data: Added Real-time forex streaming endpoint
• Core Data: Added Currency conversion endpoint
• Core Data: Added Latest fx rate endpoint
• Core Data: Added Historical daily currency rates endpoint
• Core Data: Added total vehicle sales economic data
• Core Data: Added US Recession Probabilities economic data
• Core Data: Added total housing starts economic data

2019-10-10

• Core Data: Technical Indicators endpoints

2019-10-01

• Core Data: Cryptocurrency Quote endpoint and SSE streaming for 500+ coins
• Core Data: Cryptocurrency Events SSE streaming
• Core Data: Cryptocurrency Book endpoint
• Core Data: Cryptocurrency Price endpoint

2019-09-20

• includeToday parameter added to historical prices endpoint
• sort parameter added to historical prices and intraday prices endpoints
• chartIEXWhenNull parameter added to intraday prices and endpoints

2019-09-09

• Added address information to company endpoint

2019-08-15

• Added 1mm and 5dm historical price ranges

2019-08-10

• Added lastTradeTime to Stock Quote
• Added volume to Stock Quote
• Added previousVolume to Stock Quote

2019-07-31

• Docs updated to reflect Nasdaq UTP 15 minute delayed price restrictions

2019-07-18

• Launched Cloud Cache, a fully managed data cache to help efficiently consume messages on IEX Cloud without your own data infrastructure.

2019-07-15

• Changes to 15 minute delayed (intraday) data for Nasdaq listed stocks for Start tier.

2019-07-01

• Added Search endpoint. Search across all symbols. Great for building autocomplete search box.

2019-06-14

• Added Time Series endpoint
• Added 10 years of as reported financials in Time Series

2019-06-03

• Added Tel Aviv Stock Exchange (TAE) EOD prices
• Added Korea Stock Exchange (KRX) EOD prices

2019-05-28

• Added message circuit breaker to Account endpoints to set a cutoff for pay as you go messages. Console will be updated soon with a UI to update message circuit breaker.
• Added ISIN endpoint to convert ISIN to IEX Cloud symbols.
• Added latest-financial-quarterly-report-date to Data Points.
• Added latest-financial-annual-report-date to Data Points.

2019-05-16

• Added Bombay Stock Exchange (BSE Ltd.) EOD prices

2019-05-15

• Updated company descriptions

2019-05-10

• Added symbol search to Console. This feature will expand over time, but initially searches only US stocks.

2019-04-30

• Added Options symbols ref data
• Added new market wide, macro data to Data Points. https://cloud.iexapis.com/stable/data-points/market
• Added 30 year treasury rate /stable/data-points/market/DGS30
• Added 20 year treasury rate /stable/data-points/market/DGS20
• Added 10 year treasury rate /stable/data-points/market/DGS10
• Added 5 year treasury rate /stable/data-points/market/DGS5
• Added 2 year treasury rate /stable/data-points/market/DGS2
• Added 1 year treasury rate /stable/data-points/market/DGS1
• Added 6 month treasury rate /stable/data-points/market/DGS6MO
• Added 3 month treasury rate /stable/data-points/market/DGS3MO
• Added 1 month treasury rate /stable/data-points/market/DGS1MO
• Added mortgage rate 15 year fixed /stable/data-points/market/MORTGAGE15US
• Added mortgage rate 30 year fixed /stable/data-points/market/MORTGAGE30US
• Added mortgage rate 5/1 year adjustable /stable/data-points/market/MORTGAGE5US
• Added federal funds rate /stable/data-points/market/FEDFUNDS
• Added non-farm payrolls /stable/data-points/market/PAYEMS
• Added consumer price index /stable/data-points/market/CPIAUCSL
• Added industrial production index /stable/data-points/market/INDPRO
• Added real gross domestic product /stable/data-points/market/A191RL1Q225SBEA
• Added commercial paper outstanding /stable/data-points/market/COMPOUT
• Added unemployment rate /stable/data-points/market/UNRATE
• Added CD rate non-jumbo /stable/data-points/market/MMNRNJ
• Added CD rate jumbo /stable/data-points/market/MMNRJD
• Added credit card interest rate /stable/data-points/market/TERMCBCCALLNS

2019-04-26

• Added EOD options data
• Added 15 minute delayed OTC data (Only available to Scale users with permission from OTC Markets)

2019-04-18

• Version 1 is available and new version types are available.

Beta

2019-04-15

• Added Data Points endpoint
• Added beta to Basic Stats endpoint

2019-04-10

• Added XETRA EOD prices
• Expanded historical dividend data for ETFs and mutual funds

2019-04-09

• Added Stats endpoint
• Added iexcloud-messages-used header to API responses

2019-03-22

• Added EOD prices for London Stock Exchange
• Added EOD prices for Euronext Brussels
• Added EOD prices for Euronext Paris
• Added EOD prices for Euronext Lisbon
• Added EOD prices for Euronext Dublin
• Added EOD prices for Euronext Amsterdam

2019-03-21

• Added historical sentiment data by minute back to May 2017

2019-03-20

• Added enhanced token security using signed requests

2019-03-18

• Added upcoming events endpoint

2019-03-14

• Added streaming news with SSE

2019-03-13

• Added new Grow tier
• Added historical sentiment data back to May 2017

2019-03-12

• Added international ref data

2019-03-08

• Added social sentiment streaming with SSE
• Added exDividendDate to Basic Stats
• Added listLimit query parameter to list to specify number of items to return

2019-03-07

• Added mutual fund symbols ref data
• Added otc symbols ref data
• Added region and currency to symbols ref data
• Added support for Mexico Exchanges historical prices
• Fixed earnings report date for some after market close symbols that returned the next day

2019-03-06

• Added currency exchange rates
• Added FX Symbols

2019-02-28

• Added Institutional Ownership
• Added Mutual Fund Ownership
• Added Analyst Recommendation Trends
• Added Insider Transactions
• Added Insider Roster
• Added Insider Summary
• Added ability to fetch historical data for a single date. Historical prices with range date can use query parameter chartByDay to return a single day close information.

2019-02-27

• Added international equities. Now supporting EOD Canadian prices.
• Lowered weight of /stock/OHLC endpoint from 2 to 1, and max weight of 500.
• Added peRatio to /stock/quote endpoint

2019-02-26

• Added CEO compensation data ceo-compensation
• Teams You can now invite team members to your account.

2019-02-21

• Introduced a dedicated domain for the sandbox environment.
• /status endpoint updated with version number to track when changes are made.
• Updated /stock/batch endpoint to return data for any valid symbol rather than error out the whole call for one bad symbol.

2019-02-20

• Lowered /stock/stats weight from 20 to 5
• Added peRatio nextDividendDate nextEarningsDate ttmEPS ttmDividendRate dividendYield to the /stock/stats endpoint

2019-02-19

• Added employees to the /stock/company endpoint
• Basic CIDR supported added to publishable token domain constraints in the console
• Fixed /stock/book endpoint

2019-02-14

• Introduced test tokens and sandbox for testing

2019-02-12

• Added StockTwits sentiment data

2019-02-07

• Added mutual fund EOD prices
• Added OTC EOD prices

2019-02-01

• Added /stocksUS to SSE

Core Data

Stocks / Equities

Balance Sheet

Pulls balance sheet data. Available quarterly or annually with the default being the last available quarter. This data is currently only available for U.S. symbols.

HTTP REQUEST

GET /stock/{symbol}/balance-sheet

RESPONSE

{
  "symbol": "AAPL",
  "balancesheet": [
    {
      "reportDate": "2020-10-17",
      "filingType": "10-K",
      "fiscalDate": "2020-09-13",
      "fiscalQuarter": 4,
      "fiscalYear": 2010,
      "currency": "USD",
      "currentCash": 25913000000,
      "shortTermInvestments": null,
      "receivables": 23186000000,
      "inventory": 3956000000,
      "otherCurrentAssets": 12087000000,
      "currentAssets": 131339000000,
      "longTermInvestments": 170799000000,
      "propertyPlantEquipment": 41304000000,
      "goodwill": null,
      "intangibleAssets": null,
      "otherAssets": 22283000000,
      "totalAssets": 365725000000,
      "accountsPayable": 55888000000,
      "currentLongTermDebt": null,
      "otherCurrentLiabilities": null,
      "totalCurrentLiabilities": 116866000000,
      "longTermDebt": 93735000000,
      "otherLiabilities": null,
      "minorityInterest": 0,
      "totalLiabilities": 258578000000,
      "commonStock": 40201000000,
      "retainedEarnings": 70400000000,
      "treasuryStock": null,
      "capitalSurplus": null,
      "shareholderEquity": 107147000000,
      "netTangibleAssets": 107147000000,
      "id": "BALANCE_SHEET",
      "key": "AAPL",
      "subkey": "quarterly",
      "date": 1635273127391,
      "updated": 1635273127391
    },
    // { ... }
  ]
}

Data Weighting

3,000 per symbol per period

Data Timing

End of day

Data Schedule

Updates at 8am, 9am UTC daily

Data Source(s)

Copyright: Data provided by New Constructs, LLC © All rights reserved.

Notes

• Only included with paid subscription plans.
• Financial information is limited for some financial firms.

Examples

• /stock/aapl/balance-sheet
• /stock/aapl/balance-sheet?period=annual

Query Parameters

Response Attributes

This endpoint inherits common keys from Time Series.

Bonus Issue

Obtain up-to-date and detailed information on all new announcements, as well as 12+ years of historical records.

HTTP REQUEST

GET /time-series/advanced_bonus/{symbol?}/{refid?}

RESPONSE

[
  {
    "symbol": "BVHMF",
    "exDate": "2020-01-03",
    "recordDate": "2020-01-02",
    "paymentDate": "2020-01-03",
    "fromFactor": 1,
    "toFactor": 0.03819,
    "ratio": 26.184865147944485,
    "description": "Ordinary Shares",
    "flag": "Stock",
    "securityType": "Equity Shares",
    "resultSecurityType": "Equity Shares",
    "notes": "(As on 10/09/2019) CAB<BR><BR>SITUATION:      BONUS ISSUE <BR>",
    "figi": "BBG000FZ8989",
    "lastUpdated": "2019-11-08",
    "currency": "",
    "countryCode": "US",
    "parValue": 0.5,
    "parValueCurrency": "GBP",
    "lapsedPremium": 0,
    "refid": "5951486",
    "created": "2019-09-11",
    "id": "ADVANCED_BONUS",
    "key": "BVHMF",
    "subkey": "5951486",
    "date": 1578009600000,
    "updated": 1574690010000
  },
  // { ... }
]

Data Weighting

75,000 per item returned

Data Timing

End of day

Data Schedule

Updated at 5am, 10am, 8pm UTC daily

Data Source(s)

IEX Cloud

Notes

Only available to paid plans.

Available Methods

GET /time-series/advanced_bonus/{symbol?}/{refid?}

Examples

• /time-series/advanced_bonus?range=last-week
• /time-series/advanced_bonus?range=next-month&calendar=true
• /time-series/advanced_bonus/AAPL?last=4

Path Parameters

Query Parameters

This endpoint uses all standard time-series query parameters.

Response Attributes

This endpoint inherits common response attributes from time-series.

Book

HTTP REQUEST

GET /stock/{symbol}/book

RESPONSE

{
  "quote": {...},
  "bids": [...],
  "asks": [...],
  "trades": [...],
  "systemEvent": {...},
}

Data Weighting

1 per quote returned

Data Timing

Real-time + 15min delayed

Data Schedule

Real-time during Investors Exchange market hours

Data Source(s)

Investors Exchange IEX Cloud Consolidated Tape

Available Methods

GET /stock/{symbol}/book

Examples

• /stock/aapl/book

Response Attributes

Response includes data from deep and quote. Refer to each endpoint for details.