ehd-js v0.0.12

EOD Historical Data JavaScript API wrapper

A JavaScript wrapper around the EOD Historical Data API. This library comes with TypeScript support.

Can be used with NodeJS or with client-side frameworks.

Getting started

Installation

Install with Yarn or NPM

npm install ehd-js

or

yarn add ehd-js

Once installed, you can import the module.

import ehd from 'ehd-js'

or

const ehd = require('ehd-js')

Prerequisites

To use this package you will need an API token for EOD Historical Data. You can check out available API's and pricing on their website.

Once you have an API token, you can set it up for usage two ways:

1. Add an .env file

EHD_API_KEY=YOUR_TOKEN

notes

• Be mindful not to publicise your token. So when adding a project to github for instance, make sure to add .env files to .gitignore or consider using a .env.local file.
• To make the library pick up the variable described in your .env file you might need to use dotenv library.

2. Use the built-in setToken method before calling any of the ehd methods

import ehd from 'ehd-js'

ehd.setToken(YOUR_TOKEN)

ehd.endOfDayPrice({
  // ...
})

Usage

Here we will go over all the methods provided by the ehd module. All functionality models the EOD Historical Data API closely. So for more information or references, be sure to go through the official API documentation.

This library also has full TypeScript support. To inspect the types, take a look at src/types/model.d.ts and src/types/literals.d.ts.

Every ehd method returns a Promise.

Overview

Shared configs

Some fields are used by different API's, like format and from and to date fields. This section will discuss those fields first. When using the library inside a TypeScript project you can rely on Intellisense to see which modules support which fields. For JavaScript only projects the official documentation can be consulted.

format

Most API's allow you to select the format (csv or json) in which the data is returned. Since this is a JavaScript project, all data will be returned in json format by default.

import ehd from 'ehd-js`

ehd.endOfDayPrice({
  code: 'AAPL.US',
  fmt: 'csv'
})

ehd.endOfDayPrice({
  code: 'AAPL.US',
  fmt: 'json' // default, can be omitted
})

Date range (from and to)

All time-series API's allow you to define a date range using the from and to parameters. Those params accept dates in the YYYY-MM-DD format.

ehd-js allows for that standard but builds a helper on top of that. When using to or from you can also use values like d-4, y+1, m, m-2, w-6, q, q-1 etc...

The 5 allowed time periods are d (Day), w (Week), m (Month), y (Year) or q (quarter).

* All below examples will treat 2021-01-05 as the current date
** These helpers are subject to improvement over the near future

D

from: 'D' will transform to today's date.
from: 'D-1' will transform to yesterday's date.
from: 'D-5' will equal 5 days ago
...etc

the same works in the other direction: 'D+1' is tomorrow's date, 'D+5' is a week from now, ...

W

'W' will revert to today's date, 'W-1' will be today's date minus 7 days, etc

M

'M' will revert to start of the current month when used as the from param, to the end of the current month when used as the to param.
'M-1' will be today's date a month ago, etc

Y

When using Y without modifier as the from date, it will transform to the start of the current month. As the to date it will turn into the end of the current month. With modifier, it will behave the in the same way as D, W

Q

This works slightly different than the others:

'Q': takes the end of the current quarter
'Q-1': the end of last quarter. For example, if today is 2020-12-01, 'Q-1' will turn into 2020-09-30

Quarter end dates are as follows: 03-31, 06-30, 09-30, 12-31

import ehd from 'ehd-js'

// Fetch end of day prices for the VWCE ETF from 3 months ago to a week ago.

let prices = await ehd.endOfDayPrice({
  code: 'VWCE.XETRA',
  from: 'm-3',
  to: 'w-1'
})

// Fetch end of day prices for the last three days

prices = await ehd.endOfDayPrice({
  code: 'VWCE.XETRA',
  from: 'd-3'
})

// Fetch end of day prices for the last quarter

prices = await ehd.endOfDayPrice({
  code: 'VWCE.XETRA',
  from: 'q-2',
  to: 'q-1'
})

order

Timeseries data can be requested in d (descending) or a (ascending) order. By default, data is returned in ascending order.

import ehd from 'ehd-js'

let prices = await ehd.endOfDayPrice({
  code: 'MSFT.US',
  order: 'd'
})

bondPrice

official docs

cost: 1 API call / symbol

Bond prices can be fetched using the bond's ISIN ID. When using TypeScript, prices will have the correct EHDBondPrice[] type.

import ehd from 'ehd'

const prices = await ehd.bondPrice({
  isin: 'US910047AG49'
})

It is also possible to fetch historical bond prices using the endOfDayPrice method, but in that case you will need to add the .BOND affix and the result will not have the correct type.

bondFundamentals

official docs
cost: 1 API call / symbol

Bond fundamentals can be fetched with the bond's ISIN or CUSIP. Unlike most methods this one does not accept a config object as param but only a single string.

import ehd from 'ehd'

const fundamentals = await ehd.bondFundamentals('US910047AG49')

bulkEodData

official docs
cost: 1 API call / symbol OR 100 API calls / exchange

Bulk EOD, splits and dividends data can be fetched for a single exchange or multiple symbols.

import ehd from 'ehd-js'

// Fetching EOD data for all symbols part of EuroNext Brussels

let data = await ehd.bulkEodData({
  code: 'BR',
  type: 'eod' // default
})

// When not passing a code, the 'US' exchange will be the default

data = await ehd.bulkEodData()

// Fetch today's splits for the XETRA exchange

data = await ehd.bulkEodData({
  type: 'splits',
  code: 'XETRA'
})

// Fetch today's dividends for the NASDAQ

data = await ehd.bulkEodData({
  type: 'dividends',
  code: 'NASDAQ'
})

// Fetch bulk EOD data for a specific date

data = await ehd.bulkEodData({
  date: '2020-12-05'
})

// Fetch extended EOD data

data = await ehd.bulkEodData({
  extended: true
})

// Fetch bulk data for specific symbols

data = await ehd.bulkEodData({
  symbols: ['EURN.BR', 'VWCE.XETRA', 'MSFT.US', 'AAPL.US']
})

earningsTrends

official docs

cost: 1 API call / symbol
requires: Calendar Data Feed

Fetch earnings trends using one or more symbols

import ehd from 'ehd-js'

let data = await ehd.earningsTrends({
  symbols: 'AAPL.US'
})

data = await ehd.earningsTrends({
  symbols: ['AAPL.US', 'MSFT.US']
})

upcomingEarnings

official docs

cost: 1 API call / symbol
requires: Calendar Data Feed

Use this method to fetch upcoming earnings.

import ehd from 'ehd-js'

// Fetch all upcoming earnings across multiple exchanges

let data = await ehd.upcomingEarnings()

// Fetch upcoming earnings for one or more symbols

data = await ehd.upcomingEarnings({
  symbols: 'AAPL.US',
  to: '2021-12-31'
})

data = await ehd.upcomingEarnings({
  symbols: ['AAPL.US', 'MSFT.US']
})

upcomingIpos

official docs

cost: 1 API call
requires: Calendar Data Feed

Fetch data for upcoming IPOs. This API only allows for a date range.

import ehd from 'ehd-js'

// Fetch all upcoming IPOs for the next 7 days

let data = await ehd.upcomingIpos()

// Fetch all upcoming IPOs for the next 3 weeks

data = await ehd.upcomingIpos({
  to: 'w+3'
})

upcomingSplits

official docs

cost: 1 API call
requires: Calendar Data Feed

Fetch data for upcoming IPO's. This API only allows for a date range.

import ehd from 'ehd-js'

// Fetch all upcoming splits across all exchanges

let data = await ehd.upcomingSplits()

// Fetch upcoming splits for the next three weeks

data = await ehd.upcomingSplits({
  to: 'w+3'
})

dividends

official docs
example json response

cost: 1 API call / symbol

Fetch dividend data for a specific symbol. Adding fmt: 'csv' will only return date and dividend. Use json to receive extended data.

import ehd from 'ehd-js'

// Fetch dividend data for Microsoft for the past two years

const data = await ehd.dividends({
  code: 'MSFT.US',
  from: 'y-2'
})

endOfDayPrice

official docs
example json response

cost: 1 API call / symbol

Historical end of day data can be fetched for any available code. Besides the shared date-range, format and order params, this API also accepts a period param: d (daily), w (weekly), m (monthly).

import ehd from 'ehd-js'

// Fetch historical weekly prices for the past year for the VWCE ETF

const data = await ehd.endOfDayPrice({
  code: 'VWCE.XETRA',
  from: 'y-1',
  period: 'w',
  order: 'd'
})

Economic data

The endOfDayPrice method can also be used to fetch government bond data, exchange and interbank rates. To help with the construction of the codes, additional helper methods have been implemented.

governmentBond

official docs

cost: 1 API call
requires Fundamentals Data Feed

import ehd from 'ehd-js'

let data = await ehd.governmentBondPrice({
  bond: {
    countryCode: 'US',
    period: '10Y'
  },
  from: 'm-1'
})

data = await ehd.governmentBondPrice({
  bond: 'US10Y'
})

euribor

official docs

cost: 1 API call
requires Fundamentals Data Feed

import ehd from 'ehd-js'

const data = await ehd.euribor({
  ratePeriod: '1W'
})

euriborFutures

official docs

cost: 1 API call
requires Fundamentals Data Feed

import ehd from 'ehd-js'

const data = await ehd.euriborFutures({
  from: 'q-1'
})

libor

official docs

cost: 1 API call
requires Fundamentals Data Feed

import ehd from 'ehd-js'

const data = await ehd.libor({
  ratePeriod: '2M',
  nomination: 'EUR',
  fmt: 'csv'
})

stibor

official docs

cost: 1 API call requires Fundamentals Data Feed

import ehd from 'ehd-js'

const data = await ehd.stibor({
  ratePeriod: '1M',
  from: 'y-3',
  period: 'w'
})

ecbExchangeRates

official docs

cost: 1 API call
requires Fundamentals Data Feed

import ehd from 'ehd-js'

const data = await ehd.ecbExchangeRates({
  currency: 'GBP',
  from: 'm-1',
  period: 'w'
})

norgesBankExchangeRates

official docs

cost: 1 API call
requires Fundamentals Data Feed

import ehd from 'ehd-js'

const data = await ehd.norgesBankExchangeRates({
  currency: 'EUR'
})

exchangeDetails

official docs

cost: 1 API call requires: All World Extended Package or higher

Use this API to get detailed info for different exchanges.

import ehd from 'ehd-js'

// Fetch exchange info for Euronext Brussels with market holidays data for the past three months

const data = await ehd.exchangeDetails({
  code: 'BR',
  from: 'm-3'
})

exchangesList

official docs

cost: 1 API call

Use this method to get a full list of supported exchanges.

import ehd from 'ehd-js'

const data = await ehd.exchangesList()

exchangeSymbolList

official docs

cost: 1 API call

To get a full list of symbols for an exchange, use the exchangeSymbolList method.

import ehd from 'ehd-js'

const data = await ehd.exchangeSymbolList({
  code: 'US'
})

fundamentals

official docs
example stock response
example etf response

cost: 1 API call
requires: Fundamentals Data Feed

Get fundamentals data on stocks, ETFs and mutual funds.

You can either use the base fundamentals method. The caveat here is that the return type will be any since the data models differ between stocks, ETFs and mutual funds. To get the correct data type you'll need to cast it yourself.

import ehd from 'ehd-js'
import { EDHETFGeneralInfo, EHDStockFundamentals } from 'ehd-js/src/types/model'

let data = await ehd.fundamentals<EHDETFGeneralInfo>({
  code: 'VWCE.XETRA',
  filter: 'General'
})

data = await ehd.fundamentals<EHDStockFundamentals>({
  code: 'MSFT.US'
})

fundamentals also contains three submethods for each of the three fundamentals symbol types. Here the correct returned data types are built in but you can no longer use the filter option.

import ehd from 'ehd-js'

const stock = await ehd.fundamentals.stock('MSFT.US')
const eft = await ehd.fundamentals.etf('VWCE.XETRA')
const mutualFund = await ehd.fundamentals.mutualFund('SWPPX.US')

indexConstituents

official docs

Get info about an index, including a list of it's components

import ehd from 'ehd-js'

// Fetch a list of supported indices using the virtual 'INDX' exchange

const supportedIndices = await ehd.exchangeSymbolList({
  code: 'INDX'
})

// Use an index code to fetch its related data

const indexInfo = await ehd.indexConsituents('GSCP')

intraday

official docs
example response

cost: 1 API call / symbol

Get historical intraday price data using this API.

This method accepts from and to parameters but instead of dates, the values should be UNIX times with UTC timezones (e.g. 1611340097 for Mon Jan 19 1970 16:35:40 GMT+0100). For ease of use you can still use the date shorthands (e.g. d-5, w-1).

You can choose between intervals of 1m or 5m

import ehd from 'ehd-js'

const data = await ehd.intraday({
  code: 'MSFT.US',
  interval: '5m',
  from: 1611340097,
  to: 'd'
})

livePrices

official docs

cost: 1 API call / symbol

Fetch live (delayed) stock price data using this API. You can fetch data for multiple tickers but it is recommended to limit the total amount to 20.

import ehd from 'ehd-js'

const data = await ehd.livePrices({
  code: 'VWCE.XETRA',
  s: ['AAPL.US', 'MSFT.US']
})

macroEconomics

official docs

Get data for over 30 macroeconomic indicators.

import ehd from 'ehd-js'

const data = await ehd.macroEconomics({
  country: 'DEU',
  indicator: 'gdp_growth_annual'
})

options

official docs
example response

cost: 10 API calls / symbol requires: Options Data Feed

Get options data for a symbol or a specific contract.

import ehd from 'ehd-js'

let data = await ehd.options({
  code: 'AAPL.US',
  from: 'm-1',
  tradeDateFrom: '2020-12-01',
  tradeDateTo: '2021-02-12'
})

data = await ehd.options({
  contract_name: 'AAPL201218C00022500'
})

search

official docs

cost: 1 API call

Use this to perform a query based search. You can choose to limit the amount of results returned as well as confine the search results to bonds only.

import ehd from 'ehd-js'

let data = await ehd.search({
  query: 'apple',
  limit: 5
})

data = await ehd.search({
  query: 'airline',
  limit: 5,
  bondsOnly: true
})

screener

official docs

cost: 5 API calls

Use the screener API to filter out tickers based on certain parameters

type EHDScreenerFilter =
  | 'code'
  | 'name'
  | 'exchange'
  | 'sector'
  | 'industry'
  | 'market_capitalization'
  | 'earnings_share'
  | 'dividend_yield'
  | 'refund_1d_p'
}

type EHDScreenerOperation =
  | '='
  | 'in'
  | 'not in'
  | 'match'
  | '>'
  | '<'
  | '>='
  | '<='
  | '!='

export type EHDScreenerSignal =
  | '50d_new_lo'
  | '50d_new_hi'
  | '200d_new_lo'
  | '200d_new_hi'
  | 'bookvalue_neg'
  | 'bookvalue_pos'
  | 'wallstreet_lo'
  | 'wallstreet_hi'

import ehd from 'ehd-js'

const data = await ehd.screener({
  filters: {
    market_capitalization: ['>', 1000],
    exchange: ['=', 'us']
  },
  signals: ['200d_new_hi'],
  sort: {
    market_capitalization: 'asc'
  },
  limit: 10,
  offset: 5
})

shortInterest

official docs
example response

cost: 1 API call / symbol

Get data on short interest for a specific symbol

import ehd from 'ehd-js'

const data = await ehd.shortInterest({
  code: 'GME.US'
})

splits

official docs
example response

cost: 1 API call / symbol

Get historical splits data for a specific symbol

import ehd from 'ehd-js'

const data = await ehd.splits({
  code: 'AAPL.US'
})

technicals

official docs

cost: 5 API calls

Get historical data for 10+ technical indicators

The following additional options are valid for the macd function

The following additional options are valid for the stochastic function

import ehd from 'ehd-js'

let data = await ehd.technicals({
  code: 'MSFT.US',
  function: 'macd',
  from: 'Y-1',
  period: '75', // amount of data points used to calculate each average
  splitadjustedOnly: true,
  fastPeriod: 20,
  slowPeriod: 50,
  signalPeriod: 10
})

data = await ehd.technicals({
  code: 'MSFT.US',
  function: 'stochastic',
  from: 'Y-1',
  fastKperiod: 20
})

user

official docs

Get data on the user connected with the used token

import ehd from 'ehd-js'

const user = await ehd.user()

Roadmap

I created this library in my free time and will continue to make improvements over time. Feel free to create issues if you have suggestions or encounter problems and I will try to address them whenever I find a moment.

Below you can find a list of improvement that are currently being planned:

• Add an improved date range shorthand option that should be able to handle the following cases:

  results are based on a today date of 2021-01-05

  input	result
  y	{ from: '2021-01-01', to: '2021-12-31' }
  y+1	{ from: '2022-01-01', to: '2022-12-31' }
  y-1:y	{ from: '2020-01-01', to: '2021-12-31' }
  y2014	{ from: '2014-01-01', to: '2014-12-31' }
  m	{ from: '2021-01-01', to: '2021-01-31' }
  m-3	{ from: '2020-10-01', to: '2020-10-31' }
  y-1.m3	{ from: '2020-03-01', to: '2020-03-31' }
  y-1.m+1	{ from: '2020-02-01', to: '2020-02-29' }
  y-2.m2:y-1.m+2	{ from: '2019-01-01', to: '2020-03-31' }
  w-1	{ from: '2020-12-28', to: '2020-01-03' }
  w	{ from: '2021-01-04', to: '2021-01-10' }
  w+3	{ from: '2021-01-24', to: '2021-01-31' }
  d	{ from: '2021-01-05', to: '2021-01-05' }
  d-10	{ from: '2020-12-26', to: '2021-01-05' }

• Improve livePrices method so you don't have to pass both code and s when fetching live prices for multiple symbols

• Add more tests