API Documentation

You need a paid subscription to be able to use the stock predictions API endpoints. You must include the ApiKey in the request headers. You can find your ApiKey on your account profile page after signing up.

General Information

New predictions are generated each market day, approximately at 6:00 am EST before the markets open. No predictions are generated on market holidays.

Each prediction indicates the probability (as a percentage) of a price increase for the specified stock, based on the provided reference_price. A prediction above 50% suggests an expected price increase from the prediction date until the prediction_valid_until date; below 50% suggests a decrease. While higher prediction values signal a stronger likelihood of a price increase, a prediction around 50% suggests a flat trend expectation based on our algorithms.

Each prediction includes three key dates:

latest_market_date: The most recent market day that has concluded by the time the prediction is published. For example, if the prediction is published on a Tuesday before the market opens, and the market was open on Monday, the latest_market_date will be Monday's date.
prediction_sent_on: The date the prediction is published. For example, if the prediction is published on 2024-11-04, it means the prediction was sent out on 2024-11-04 before the market opened.
prediction_valid_until: The date until which the prediction is valid. Predictions indicate the price movement likelihood for the period from prediction_sent_on to prediction_valid_until.

The prediction period is currently set to 10 market days. Predictions are generated based on the latest available market data and are intended for informational purposes only. They should not be used as the sole basis for investment or trading decisions.

Endpoints

Tickers

The tickers endpoint provides a list of supported stock tickers for which predictions are available. We primarily cover companies listed on American stock exchanges, tracking over 5000 stocks daily. This endpoint helps users determine if a specific ticker is supported. Note that predictions occasionally may not be available for some tickers listed in this endpoint if up-to-date historical data is not available by the time predictions are generated.

The response includes the following fields:

ticker: The stock ticker symbol representing a company.
name: The full name of the company corresponding to the ticker symbol.

GET /api/tickers/

Headers:
    Authorization: Api-Key YOUR_API_KEY

Parameters:
    - ticker (optional, string): Filter by ticker symbol or company name (supports partial matching)

Response:
    [
        {
            "ticker": "AAPL",
            "name": "Apple Inc."
        },
        {
            "ticker": "AAL",
            "name": "American Airlines Group Inc."
        }
    ]

Examples:
    - Get all tickers: /api/tickers/
    - Get a specific ticker: /api/tickers/?ticker=AAPL
    - Get tickers starting with 'AA': /api/tickers/?ticker=AA

Code Example

import requests

url = 'https://www.sharepredictions.com/api/tickers/'
headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
}
params = {
    'ticker': 'AA'
}
response = requests.get(url, headers=headers, params=params)
print(response.json())

const url = 'https://www.sharepredictions.com/api/tickers/';
const headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
};
const params = new URLSearchParams({
    ticker: 'AA'
});

fetch(`${url}?${params}`, { headers })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));

Market Barometer Predictions

Market barometer predictions are updated daily before the market opens. We provide separate predictions for the overall market, the top 500 companies by market cap, and penny stocks. These predictions indicate the expected market direction for the prediction validity period. Higher values suggest a bullish market, while lower values suggest a bearish market. A prediction around 50% suggests a flat market trend expectation based on our algorithms.

The response includes the following fields:

latest_market_date: The most recent market day that has concluded by the time the prediction is published.
prediction_sent_on: The date when the prediction was sent.
prediction_valid_until: The date until which the prediction is valid.
market_v_weighted_avg_pred: The volume-weighted average prediction across all stock tickers for which we provide predictions, representing the overall market trend.
penny_stocks_v_weighted_avg_pred: The volume weighted average prediction for penny stocks market.
top_500_v_weighted_avg_pred: The volume weighted average prediction for the top 500 companies by market cap.

GET /api/market-barometer/

Headers:
    Authorization: Api-Key YOUR_API_KEY

Parameters:
    - latest_market_date (optional, date): Filter predictions by market date (YYYY-MM-DD)
    - prediction_sent_on (optional, date): Filter predictions by the date they were sent (YYYY-MM-DD)
    - ordering (optional, string): Sort by field (prefix with - for descending: -latest_market_date)
    - limit (optional, int): Number of results to return per page
    - offset (optional, int): The initial index from which to return the results

Response:
    [
        {
            "latest_market_date": "2024-03-25",
            "prediction_sent_on": "2024-03-26",
            "prediction_valid_until": "2024-04-08",
            "market_v_weighted_avg_pred": 0.65,
            "penny_stocks_v_weighted_avg_pred": 0.55,
            "top_500_v_weighted_avg_pred": 0.72
        }
    ]

Examples:
    - Get all predictions: /api/market-barometer/
    - Get predictions for a specific date: /api/market-barometer/?latest_market_date=2024-03-25
    - Get predictions sent on a specific date: /api/market-barometer/?prediction_sent_on=2024-03-26
    - Get last 5 predictions: /api/market-barometer/?limit=5&ordering=-latest_market_date
    - Get predictions after a specific date: /api/market-barometer/?prediction_sent_on__gt=2024-03-25

Code Example

Example implementation to retrieve updated predictions on a daily basis. It fetches the latest market barometer predictions and prints them to the console. If no predictions are available, it prints a message indicating that it is either a holiday or predictions are not yet published for today. You can update this script based on your workflow and run as a scheduled task to fetch predictions daily, roughly 2 hours before markets open. Remember to update YOUR_API_KEY with your actual values.

import requests
from datetime import datetime

url = 'https://www.sharepredictions.com/api/market-barometer/'
headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
}
params = {
    'prediction_sent_on': datetime.now().strftime('%Y-%m-%d'),
    'limit': 5,
    'ordering': '-latest_market_date'
}

def fetch_predictions(url, headers, params):
    response = requests.get(url, headers=headers, params=params)
    data = response.json()
    if data['results']:
        for prediction in data['results']:
            print(prediction)
        while data.get('next'):
            response = requests.get(data['next'], headers=headers)
            data = response.json()
            for prediction in data['results']:
                print(prediction)
    else:
        print("It is either a market holiday today or predictions are not yet published for today. Please try again later.")

fetch_predictions(url, headers, params)

const url = 'https://www.sharepredictions.com/api/market-barometer/';
const headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
};
const params = new URLSearchParams({
    prediction_sent_on: new Date().toISOString().split('T')[0],
    limit: '5',
    ordering: '-latest_market_date'
});

async function fetchPredictions(url, headers, params) {
    let response = await fetch(`${url}?${params}`, { headers });
    let data = await response.json();
    if (data.results.length > 0) {
        data.results.forEach(prediction => console.log(prediction));
        while (data.next) {
            response = await fetch(data.next, { headers });
            data = await response.json();
            data.results.forEach(prediction => console.log(prediction));
        }
    } else {
        console.log("It is either a market holiday today or predictions are not yet published for today. Please try again later.");
    }
}

fetchPredictions(url, headers, params);

Ticker-Specific Predictions

Using this endpoint, you can retrieve the latest predictions for all supported tickers. It is also possible to obtain predictions for multiple days to observe trends. The endpoint supports various filters as described below:

The response includes the following fields:

ticker: The stock ticker symbol (e.g., AAPL).
reference_price: The price on which the prediction is based. The price_increase_likelihood is calculated relative to this reference price.
last_5_days_volatility: A percentage value indicating the stock's volatility over the last 5 business days. This can help traders determine better stop loss and sell targets.
latest_market_date: The date of the latest market data used for the prediction (YYYY-MM-DD).
prediction_sent_on: The date when the prediction was generated and sent (YYYY-MM-DD).
prediction_valid_until: The date until which the prediction is considered valid (YYYY-MM-DD).
price_increase_likelihood: A percentage value indicating the likelihood of a price increase. A prediction closer to 100% indicates a higher likelihood of a price increase, while a prediction closer to 0% indicates a higher likelihood of a price decrease. A prediction around 50% suggests a flat trend expectation.

GET /api/ticker-predictions/

Headers:
    Authorization: Api-Key YOUR_API_KEY

Parameters:
    - ticker (optional, string): Filter predictions by ticker symbol (e.g., AAPL)
    - latest_market_date (optional, date): Filter by market date (YYYY-MM-DD)
    - prediction_sent_on (optional, date): Filter predictions by the date they were sent (YYYY-MM-DD)
    - ordering (optional, string): Sort by field (prefix with - for descending: -latest_market_date)
    - limit (optional, int): Number of results to return per page
    - offset (optional, int): The initial index from which to return the results

Response:
    [
        {
            "ticker": "AAPL",
            "last_5_days_volatility": 0.023,
            "reference_price": 172.45,
            "latest_market_date": "2024-03-25",
            "prediction_sent_on": "2024-03-26",
            "prediction_valid_until": "2024-04-08",
            "price_increase_likelihood": 0.68
        }
    ]

Examples:
    - Get all predictions: /api/ticker-predictions/
    
        Warning: Avoid using the /api/ticker-predictions/ endpoint without filters, 
        as it will try to retrieve all predictions of all times for all tickers, 
        which can quickly consume your rate limits.
    
    - Get predictions for a specific ticker: /api/ticker-predictions/?ticker=AAPL
    - Get predictions based on a specific latest_market_date: /api/ticker-predictions/?latest_market_date=2024-03-25
    - Get predictions sent on a specific date: /api/ticker-predictions/?prediction_sent_on=2024-03-26
    - Get last 5 predictions: /api/ticker-predictions/?limit=5&ordering=-latest_market_date
    - Get predictions after a specific date: /api/ticker-predictions/?prediction_sent_on__gt=2024-11-01
    - Get the last 20 predictions for a specific ticker: /api/ticker-predictions/?ticker=AAPL&limit=20&ordering=-latest_market_date
    - Pagination: Use limit and offset parameters to paginate results. For example, /api/ticker-predictions/?limit=5&offset=10 returns the next 5 predictions starting from the 11th prediction.

Code Example

Example implementation to retrieve updated predictions on a daily basis. It fetches the latest predictions for each ticker and prints them to the console. If no predictions are available, it prints a message indicating that it is either a holiday or predictions are not yet published for today. You can update this script based on your workflow and run as a scheduled task to fetch predictions daily, roughly 2 hours before markets open. Remember to update YOUR_API_KEY with your actual values.

import requests
from datetime import datetime

url = 'https://www.sharepredictions.com/api/ticker-predictions/'
headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
}
params = {
    'prediction_sent_on': datetime.now().strftime('%Y-%m-%d'),
    'limit': 5,
    'ordering': '-latest_market_date'
}

def fetch_predictions(url, headers, params):
    response = requests.get(url, headers=headers, params=params)
    data = response.json()
    if data['results']:
        for prediction in data['results']:
            print(prediction)
        while data.get('next'):
            response = requests.get(data['next'], headers=headers)
            data = response.json()
            for prediction in data['results']:
                print(prediction)
    else:
        print("It is either a market holiday today or predictions are not yet published for today. Please try again later.")

fetch_predictions(url, headers, params)

const url = 'https://www.sharepredictions.com/api/ticker-predictions/';
const headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
};
const params = new URLSearchParams({
    prediction_sent_on: new Date().toISOString().split('T')[0],
    limit: '5',
    ordering: '-latest_market_date'
});

async function fetchPredictions(url, headers, params) {
    let response = await fetch(`${url}?${params}`, { headers });
    let data = await response.json();
    if (data.results.length > 0) {
        data.results.forEach(prediction => console.log(prediction));
        while (data.next) {
            response = await fetch(data.next, { headers });
            data = await response.json();
            data.results.forEach(prediction => console.log(prediction));
        }
    } else {
        console.log("It is either a market holiday today or predictions are not yet published for today. Please try again later.");
    }
}

fetchPredictions(url, headers, params);