FirstRate Data ETF API Documentation
The API provides customers with a lightweight method for accessing our datasets which can be integrated into custom workflows such as Python scripts.
Datasets are updated daily. The 'update' data (for past day, week or month) are available at 1am US Eastern Time for the prior day's trade data, whereas the full archives (containing the entire historical series) are available at 2am US Eastern Time.
All API functions are authenticated using your userid which is XXX.
Therefore all API requests need to be appended with the parameter userid=XXX as shown in the examples.
API Functions
Historical Data Requests - (requesting the historical datafiles)
Full Updates - (returns the full history for just the adjusted tickers)
Splits / Dividends Requests - (requesting the historical stock/ETF splits and dividends)
Last Update - (provides the last update date for the data. This is helpful for checking if there is fresh data available to request)
Ticker Listing - (provides the full listing of tickers as well as start and end dates)
Historical Data Requests
This function returns historical data archives (.txt files in csv format which are grouped into zip archives)
Url EndPoint : https://firstratedata.com/api/data_file
Requires Authentication : YES. All requests must include the parameter userid with your userid given to you in your signup email. Also available from your Customer Download Page.
Data Details : Full details on the data format, timezone, as well as available tickers and date ranges can be viewed on the bundle ReadMe Page
Parameters : The below parameters are used with the Url Endpoint to use the Historical Data Requests function:
Accepted Values : stock , etf, futures , crypto , index , fx , options
Description : Specifies the type of instrument that is being requested.
Example :
https://firstratedata.com/api/data_file?type=etf&period=week&timeframe=1day&adjustment=adj_split&userid=XXX
Accepted Values : full , month , week , day
Description : Specifies the period to request data for. 'full' requests the entire historical archive, 'month' requests the last 30 days, 'week' requests the current trading week (starting on Monday), 'day' requests the last trading day.
To request the full historical archive you also need to specify a ticker_range parameter (see below).
Example :
https://firstratedata.com/api/data_file?type=etf&period=full&ticker_range=A&adjustment=adj_split&timeframe=1hour&userid=XXX
Accepted Values : A-Z (one letter of the alphabet)
Description : Only to be used when requested the full historical dataset (ie 'period=full'). This parameter specifies the first letter of the ticker, for example 'ticker_range=C' will request all tickers beginning with the letter C
This parameter can only be used when requested the full historical archive (ie 'period=full')
Example :
https://firstratedata.com/api/data_file?type=etf&period=full&ticker_range=C&timeframe=1day&adjustment=adj_split&userid=XXX
Accepted Values : 1min , 5min , 30min , 1hour , 1day
Description : Specifies the period the timeframe of the data. '1min' will request 1-minute intraday bars, '5min' requests 5-minute bars etc.
Note : bars with zero volumes are not included
Example :
https://firstratedata.com/api/data_file?type=etf&period=week&adjustment=adj_split&timeframe=1min&userid=XXX
Accepted Values : adj_split , adj_splitdiv , UNADJUSTED
Description : Specifies the type of adjustment. 'adj_split' is data adjusted for splits only, 'adj_splitdiv' is data adjusted for both splits and dividends, 'UNADJUSTED' is raw data without any splits or dividend adjustments. UNADJUSTED data is only available in the 1min and 1day timeframes.
Example :
https://firstratedata.com/api/data_file?type=etf&period=week&timeframe=1day&adjustment=adj_split&userid=XXX
Full Updates
This function returns the full dataset for stocks or ETFs which have been adjusted.
When a stock/ETF is adjusted for a split or a dividend, the full history is adjusted from the start date up to the present day. Therefore, customers maintaining a local archive of the full dataset will have an issue using day/week/month updates to keep the archive current since the update will not contain the full history of all the adjusted data.
The Full Updates function returns the full history of just the updated tickers. These can then replace the legacy files in the local archive.
Url EndPoint : https://firstratedata.com/api/full_update
Requires Authentication : YES. All requests must include the parameter userid with your userid given to you in your signup email. Also available from your Customer Download Page.
Parameters : The below parameters are used with the Url Endpoint to use the Individual Contract function:
Accepted Values : adj_split , adj_splitdiv
Description : Specifies the type of adjustment. 'adj_split' is data adjusted for splits only, 'adj_splitdiv' is data adjusted for both splits and dividends, 'UNADJUSTED' is raw data without any splits or dividend adjustments.
Example :
https://firstratedata.com/api/full_update?type=etf&period=week&timeframe=1day&adjustment=adj_split&userid=XXX
Accepted Values : 1min , 5min , 30min , 1hour , 1day
Description : Specifies the period the timeframe of the data. '1min' will request 1-minute intraday bars, '5min' requests 5-minute bars etc.
Note : bars with zero volumes are not included
Example :
Example :
https://firstratedata.com/api/full_update?type=etf&period=week&timeframe=1day&adjustment=adj_split&userid=XXX
Accepted Values : week , day
Description : Specifies the period to request data for, 'week' requests the last 5 trading days, 'day' requests the last trading day.
Example :
Example :
https://firstratedata.com/api/full_update?type=etf&period=week&timeframe=1day&adjustment=adj_split&userid=XXX
Splits / Dividends Requests
This function returns historical splits or dividends for an instrument type (either stock or ETF).
Url EndPoint : https://firstratedata.com/api/meta_file
Data Format | Splits : {date,split-ratio} date is in format yyyy-MM-dd,the split-ratio is the ratio of new shares to old share
Data Format | Dividends : {ex-dividend date,dividend amount} the ex-dividend date is in the format yyyy-MM-dd and is the date on which the stock holder is no longer entitled to the dividend.
Requires Authentication : YES. All requests must include the parameter userid with your userid given to you in your signup email. Also available from your Customer Download Page.
Parameters : The below parameters are used with the Url Endpoint to use the Splits / Dividends Requests function:
Accepted Values :stock , etf, futures , crypto , index , fx
Description : Specifies the type of instrument that is being requested.
Example :
https://firstratedata.com/api/meta_file?type=etf&metafile_type=splits&userid=XXX
Accepted Values : splits , dividends
Description : Specifies the whether the request is for historical splits or dividends.
Example :
https://firstratedata.com/api/meta_file?type=etf&metafile_type=splits&userid=XXX
Last Update
This function returns the last update for an instrument type. This function can be used to check whether there has been an update prior to executing data requests. Unlike data requests, this function returns raw data in the form of a date and not zip files.
Url EndPoint : https://firstratedata.com/api/last_update
Requires Authentication : YES. All requests must include the parameter userid with your userid given to you in your signup email. Also available from your Customer Download Page.
Parameters : The below parameters are used with the Url Endpoint to use the Last Update function:
Accepted Values : stock , etf, futures , crypto , index , fx
Description : Specifies the type of instrument that is being requested.
Example :
https://firstratedata.com/api/last_update?type=etf&userid=XXX
Accepted Values : false , true (false is the default)
Description : This parameter is used when requesting the last update of the full historical dataset (otherwise the Last Update function will return the date for the update files for the past day, week or month).
Example :
https://firstratedata.com/api/last_update?type=etf&is_full_update=true&userid=XXX
Ticker Listing
This function returns the full listing of tickers as well as start and end dates for a specified instrument type. The data is returned in csv format so it can be copied into a text file and opened from a spreadsheet application if required.
Url EndPoint : https://firstratedata.com/api/ticker_listing
Data Format : {ticker},{name},{startDate},{endDate}
Parameters : The below parameters are used with the Url Endpoint to use the Last Update function:
Accepted Values : stock , etf
Description : Specifies the type of instrument that is being requested.
Example :
https://firstratedata.com/api/ticker_listing?type=etf&userid=XXX
Accepted Values : true, false (false is the default value)
Description : Specifies the is the returned data is in HTML format. Set this value to true to view the data in a web browser.
Example :
https://firstratedata.com/api/ticker_listing?type=etf&userid=XXX&html=true