Stocks Specific

Learn to get information about stock splits and dividends.

We'll cover the following

In this lesson, we’ll discuss endpoints that are only valid for the US stock exchanges.

Stock splits

A stock split is a phenomenon where a company increases its number of shares. This usually happens to lower the price of a single share and make it more affordable. A split ratio defines how the new shares will be distributed among the current shareholders. For example, if a shareholder has one share before the split, they will have two shares after the split if the 2:1 split ratio is followed.

Press + to interact
The stock splits endpoint
The stock splits endpoint

The stock split endpoint available in the Polygon API provides us with a list of stock splits.

Following is the base URL for this endpoint:

https://api.polygon.io/v3/reference/splits

Request parameters

By default, the stock splits endpoint gives us 10 response objects. However, we can filter our search by providing some optional request parameters. The table below gives an overview of these request parameters.

Name

Type

Category

Description

ticker

String

Optional

The ticker associated with the stock whose data we want.

execution_date

String

Optional

This is used to fetch stock splits on a specific date. The YYYY-MM-DD format is used for the date.

reverse_split

Boolean

Optional

This is used to view reverse stock splits, where the split-from is greater than the split-to

order

String

Optional

This is used to order the results in ascending or descending order. Valid input parameters are asc or desc for ascending and descending, respectively.

limit

Integer

Optional

This specifies the required number of responses. By default, 10 responses are returned, and the maximum is 1000.

sort

String

Optional

This sorts the responses on the bases of execution_date or ticker

We can provide additional filter parameters, such as .lt (less than), .gt (greater than), .lte (less than equal to), and .gte (greater than equal to), to ticker and execution_date. For example, if we want results in which execution_date is less than 2022-01-01, we can write the following in our query parameters:

const queryParameters = new URLSearchParams({
   'execution_date.lt' : '2022-01-01'
});

Let’s try to call this endpoint with its default values in the following code:

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define API key here
const apiKey = '{{API_KEY}}';
// Define endpoint URL here
const endpointUrl = new URL('https://api.polygon.io/v3/reference/splits');
// Define Header Parameters here
const headerParameters = {
  authorization: `Bearer ${apiKey}`
};
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function StockSplits() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } 
  catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Calling function to make API call
StockSplits();

Here’s an explanation for the above code:

  • Line 8: We define the endpoint URL.

  • Lines 11–13: We define the API key in the header parameter.

  • Lines 16–19: We define the options parameters and set the request type as GET.

  • Lines 22–32: We define the StockSplits function, which calls the endpoint.

  • Line 35: We call the StockSplits function.

Now, let’s try to call the stock splits endpoint again, but this time we’ll provide some request parameters to filter our search.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define API key here
const apiKey = '{{API_KEY}}';
// Define endpoint URL here
const endpointUrl = new URL('https://api.polygon.io/v3/reference/splits');
// Define Header Parameters here
const headerParameters = {
  authorization: `Bearer ${apiKey}`
};
// Define Query Parameters here
const queryParameters = new URLSearchParams({
   "ticker.gt" : 'B',
   limit: 6,
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function fetchSplitJSON() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Calling function to make API call
fetchSplitJSON();

We have defined the query parameters in lines 16–19. We have set ticker.gt as B to get stock splits information for tickers that are greater than B. Additionally, we've also limited the results to six. Try to play with the code by changing the parameters.

Response fields

The details of the attributes in the response object are given in the following table:

Name

Type

Description

results

Array

This includes the details of each stock.

results.execution_date

String

The date on which the stocks were split.

results.split_from

Integer

The first number in the split ratio.

results.split_to

Integer

The second number in the split ratio.

results.ticker

String

The ticker of a stock.

status

String

The response to our query.

request_id

String

The ID associated with our query.

next_url

String

The URL to the next page in case our response spans multiple pages.

Dividends

When a corporation earns profit, it distributes a portion of its earnings to the shareholders, known as dividends. We can get a list of dividends within the last two years through the dividends endpoint.

Press + to interact
The dividends endpoint
The dividends endpoint

The base URL for this endpoint is as follows:

https://api.polygon.io/v3/reference/dividends

Request parameters

By default, the dividends endpoint returns a list of all dividends within the last two years. However, we can filter our search by providing some additional parameters. An overview of these parameters is given in the table below.

Name

Type

Category

Description

ticker

String

Optional

The ticker associated with the stock we want.

ex_dividend_date

String

Optional

This is set to one date before the record date. People who buy stocks on this date are not eligible to receive the next dividend. This date is given in the YYYY-MM-DD format.

record_date

String

Optional

Only the stockholders recorded in the company's books on the record date are eligible to receive the dividend. It is given in the YYYY-MM-DD format.

declaration_date

String

Optional

The date when the dividend is announced. It is given in the YYYY-MM-DD format.

pay_date

String

Optional

The date when the dividend is paid to the investors. It is given in the YYYY-MM-DD format.

frequency

Integer

Optional

This is the number of times the dividend is paid annually. Accepted values are 0, 1, 2, 4, and 12 for one-time, annually, biannually, quarterly, or monthly, respectively.

cash_amount

String

Optional

The amount paid as a dividend.

dividend_type

String

Optional

This is the type of dividend we want. Possible values are CD, SC, LT, and ST for consistent scheduled dividends, special cash, long-term capital gain, and short-term capital gain, respectively.

order

String

Optional

This orders our results according to the input parameter given as sort. Accepted values are asc and desc for ascending and descending order, respectively.

limit

Integer

Optional

This defines the number of results required. By default, it is set to 10 and the maximum limit we can provide is 1000.

sort

String

Optional

The field we select for the results to be ordered.

Accepted values: ticker, ex_dividend_date, record_date, declaration_date, pay_date, or cash_amount.

We can provide additional parameters, as explained above, to ticker, ex_dividend_date, record_date, declaration_date, pay_date, and cash_amount.

Let’s try to call this endpoint by providing some request parameters in the following code.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define API key here
const apiKey = '{{API_KEY}}';
// Define endpoint URL here
const endpointUrl = new URL('https://api.polygon.io/v3/reference/dividends');
// Define Header Parameters here
const headerParameters = {
  authorization: `Bearer ${apiKey}`
};
// Define Query Parameters here
const queryParameters = new URLSearchParams({
   order : 'asc',
   sort: 'ticker',
   limit: 6,
   ex_dividend_date: "2022-10-10"
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function Dividend() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Calling function to make API call
Dividend();

We have defined some query parameters in lines 16–21. Try to change the values of the query parameters to fetch different results.

Response fields

The details of the attributes in the response object are given in the following table:

Name

Type

Description

results

Array

This includes the details about a stock.

results.cash_amount

Integer

The cash amount to be paid per share.

results.currency

String

The currency in which the amount is paid.

results.declaration_date

String

The date on which the dividend was announced.

results.dividend_type

Enum

This is the type of dividend. Possible output is CD, SC, LT, and ST for consistent scheduled dividends, special cash, long-term capital gain, and short-term capital gain, respectively.

results.ex_dividend_date

String

This is the ex-dividend date. If a buyer buys a stock on or after this date, they are not eligible to receive the dividend.

results.frequency

Integer

This is the number of times the dividend is paid. The possible output is `0` for one time, 1 for once a year, 2 for twice a year, 4 for quarterly, or 12 for monthly.

results.pay_date

String

The date on which the dividend is paid.

results.record_date

String

The date before which a person must hold a share to be eligible to receive the dividend.

results.ticker

String

The ticker of the stock.

status

String

The response status to your query.

request_id

String

The ID associated with our query.

next_url

String

The URL to fetch the data on the next page.