FMP Node API Documentation

Core API Wrapper

Calendar Endpoints

The Calendar Endpoints provide access to various financial calendars including earnings, dividends, economic events, IPOs, and stock splits. These endpoints help you track important financial events and announcements.

Available Methods

Method	Endpoint	Description
GET	/earning_calendar	Get earnings calendar data
GET	/earning-calendar-confirmed	Get earnings confirmed data
GET	/stock_dividend_calendar	Get dividends calendar data
GET	/economic_calendar	Get economic calendar data
GET	/ipo_calendar	Get IPO calendar data
GET	/stock_split_calendar	Get stock splits calendar data

Get Earnings Calendar

Retrieve upcoming earnings announcements with estimated and actual earnings per share (EPS) and revenue data.

1const earningsCalendar = await fmp.calendar.getEarningsCalendar({
2  from: '2024-01-01',
3  to: '2024-01-31'
4});

Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD format)
to	string	No	End date (YYYY-MM-DD format)

Example Response

1{
2  success: true,
3  data: [
4    {
5      date: '2024-01-25',
6      symbol: 'AAPL',
7      eps: 2.18,
8      estimatedEps: 2.10,
9      time: 'AMC',
10      revenue: 119575000000,
11      estimatedRevenue: 117000000000,
12      fiscalDateEnding: '2023-12-31',
13      updatedFromDate: '2024-01-15'
14    },
15    {
16      date: '2024-01-26',
17      symbol: 'MSFT',
18      eps: 2.93,
19      estimatedEps: 2.78,
20      time: 'AMC',
21      revenue: 62020000000,
22      estimatedRevenue: 61100000000,
23      fiscalDateEnding: '2023-12-31',
24      updatedFromDate: '2024-01-16'
25    }
26  ]
27}

Get Earnings Confirmed

Retrieve confirmed earnings announcements with detailed information including publication dates and URLs.

1const earningsConfirmed = await fmp.calendar.getEarningsConfirmed({
2  from: '2024-01-01',
3  to: '2024-01-31'
4});

Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD format)
to	string	No	End date (YYYY-MM-DD format)

Example Response

1{
2  success: true,
3  data: [
4    {
5      symbol: 'AAPL',
6      exchange: 'NASDAQ',
7      time: 'AMC',
8      when: 'After Market Close',
9      date: '2024-01-25',
10      publicationDate: '2024-01-25',
11      title: 'Apple Inc. Q1 2024 Earnings Release',
12      url: 'https://investor.apple.com/news-events/press-releases/2024/01/25/apple-reports-first-quarter-results'
13    },
14    {
15      symbol: 'MSFT',
16      exchange: 'NASDAQ',
17      time: 'AMC',
18      when: 'After Market Close',
19      date: '2024-01-26',
20      publicationDate: '2024-01-26',
21      title: 'Microsoft Corporation Q2 2024 Earnings Release',
22      url: 'https://news.microsoft.com/2024/01/26/microsoft-announces-second-quarter-fiscal-year-2024-results'
23    }
24  ]
25}

Get Dividends Calendar

Retrieve upcoming dividend payments and declarations with payment dates and amounts.

1const dividendsCalendar = await fmp.calendar.getDividendsCalendar({
2  from: '2024-01-01',
3  to: '2024-01-31'
4});

Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD format)
to	string	No	End date (YYYY-MM-DD format)

Example Response

1{
2  success: true,
3  data: [
4    {
5      date: '2024-01-15',
6      label: 'Jan 15, 24',
7      adjDividend: 0.24,
8      symbol: 'AAPL',
9      dividend: 0.24,
10      recordDate: '2024-01-08',
11      paymentDate: '2024-01-15',
12      declarationDate: '2023-11-02'
13    },
14    {
15      date: '2024-01-25',
16      label: 'Jan 25, 24',
17      adjDividend: 0.75,
18      symbol: 'JNJ',
19      dividend: 0.75,
20      recordDate: '2024-01-18',
21      paymentDate: '2024-01-25',
22      declarationDate: '2023-12-15'
23    }
24  ]
25}

Get Economic Calendar

Retrieve economic events and indicators from various countries with estimates and actual values.

1const economicCalendar = await fmp.calendar.getEconomicsCalendar({
2  from: '2024-01-01',
3  to: '2024-01-31'
4});

Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD format)
to	string	No	End date (YYYY-MM-DD format)

Example Response

1{
2  success: true,
3  data: [
4    {
5      date: '2024-01-05',
6      country: 'US',
7      event: 'Non-Farm Payrolls',
8      currency: 'USD',
9      previous: 173000,
10      estimate: 175000,
11      actual: 216000,
12      change: 43000,
13      impact: 'High',
14      changePercent: 24.86,
15      unit: 'K'
16    },
17    {
18      date: '2024-01-12',
19      country: 'US',
20      event: 'CPI m/m',
21      currency: 'USD',
22      previous: 0.1,
23      estimate: 0.2,
24      actual: 0.3,
25      change: 0.2,
26      impact: 'High',
27      changePercent: 200.00,
28      unit: '%'
29    }
30  ]
31}

Get IPO Calendar

Retrieve upcoming initial public offerings (IPOs) with company details and offering information.

1const ipoCalendar = await fmp.calendar.getIPOCalendar({
2  from: '2024-01-01',
3  to: '2024-01-31'
4});

Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD format)
to	string	No	End date (YYYY-MM-DD format)

Example Response

1{
2  success: true,
3  data: [
4    {
5      date: '2024-01-15',
6      company: 'TechStart Inc.',
7      symbol: 'TECH',
8      exchange: 'NASDAQ',
9      actions: 'Pricing',
10      shares: 10000000,
11      priceRange: '$18-$20',
12      marketCap: 190000000
13    },
14    {
15      date: '2024-01-22',
16      company: 'GreenEnergy Corp.',
17      symbol: 'GREEN',
18      exchange: 'NYSE',
19      actions: 'Pricing',
20      shares: 15000000,
21      priceRange: '$25-$28',
22      marketCap: 397500000
23    }
24  ]
25}

Get Stock Splits Calendar

Retrieve upcoming stock splits with ratio information.

1const splitsCalendar = await fmp.calendar.getSplitsCalendar({
2  from: '2024-01-01',
3  to: '2024-01-31'
4});

Parameters

Parameter	Type	Required	Description
from	string	No	Start date (YYYY-MM-DD format)
to	string	No	End date (YYYY-MM-DD format)

Example Response

1{
2  success: true,
3  data: [
4    {
5      date: '2024-01-20',
6      label: 'Jan 20, 24',
7      symbol: 'TSLA',
8      numerator: 3,
9      denominator: 1
10    },
11    {
12      date: '2024-01-25',
13      label: 'Jan 25, 24',
14      symbol: 'NVDA',
15      numerator: 4,
16      denominator: 1
17    }
18  ]
19}

Working with Calendar Data

Filtering by Date Range

All calendar endpoints support optional date filtering. When no dates are provided, the API returns the most recent data:

1// Get all upcoming earnings (no date filter)
2const allEarnings = await fmp.calendar.getEarningsCalendar({});
3
4// Get earnings for specific month
5const janEarnings = await fmp.calendar.getEarningsCalendar({
6from: '2024-01-01',
7to: '2024-01-31'
8});
9
10// Get earnings for next quarter
11const nextQuarter = await fmp.calendar.getEarningsCalendar({
12from: '2024-01-01',
13to: '2024-03-31'
14});

Processing Calendar Events

Calendar data is particularly useful for building financial dashboards and tracking important events:

1// Get all calendar events for a specific date
2const targetDate = '2024-01-25';
3
4const [earnings, earningsConfirmed, dividends, economic, ipos, splits] = await Promise.all([
5fmp.calendar.getEarningsCalendar({ from: targetDate, to: targetDate }),
6fmp.calendar.getEarningsConfirmed({ from: targetDate, to: targetDate }),
7fmp.calendar.getDividendsCalendar({ from: targetDate, to: targetDate }),
8fmp.calendar.getEconomicsCalendar({ from: targetDate, to: targetDate }),
9fmp.calendar.getIPOCalendar({ from: targetDate, to: targetDate }),
10fmp.calendar.getSplitsCalendar({ from: targetDate, to: targetDate })
11]);
12
13console.log('Earnings:', earnings.data.length);
14console.log('Earnings Confirmed:', earningsConfirmed.data.length);
15console.log('Dividends:', dividends.data.length);
16console.log('Economic Events:', economic.data.length);
17console.log('IPOs:', ipos.data.length);
18console.log('Splits:', splits.data.length);

Error Handling

Always check the success property before accessing data:

1const earnings = await fmp.calendar.getEarningsCalendar({
2  from: '2024-01-01',
3  to: '2024-01-31'
4});
5
6if (earnings.success) {
7console.log('Earnings events:', earnings.data.length);
8earnings.data.forEach(event => {
9console.log(`${event.symbol}: ${event.estimatedEps} EPS`);
10});
11} else {
12console.error('Error:', earnings.error);
13console.error('Status:', earnings.status);
14}

Rate Limiting

Calendar endpoints are subject to FMP's rate limits. For production applications, implement appropriate rate limiting and caching strategies, especially when fetching data for extended date ranges.

Next Steps

Explore other endpoint categories:

Stock Endpoints - Real-time stock data and quotes
Financial Endpoints - Financial statements and ratios
Market Endpoints - Market indices and sector data
Examples - Practical code samples

Ready to explore market data? Check out the Market Endpoints for indices, sector performance, and market statistics.