Join our Telegram channel for free daily stock & options signals Join Now

API Documentation

Access financial market predictions through our REST API endpoints. This documentation provides details on available endpoints, request formats, and sample implementations.

Video Tutorials Available!

Watch our step-by-step video series on how to use the Share Predictions API effectively. View Tutorial Playlist

Authentication

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.

Authorization: Api-Key YOUR_API_KEY

General Information

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())
            

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 starting from a specific date: /api/market-barometer/?prediction_sent_on__gte=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)
            

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/
    
    - 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 starting from a specific date: /api/ticker-predictions/?prediction_sent_on__gte=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': 10,
    '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)
            

Active Options Predictions

Retrieve all currently active AI options predictions. Each signal includes a buy target, first and second profit-taking sell targets, and a stop-loss level for call and put options on US stocks. Active signals are updated throughout market hours. Stop-loss levels are recalculated once daily before market open, based on the previous day's closing premium.

The response includes the following fields:

  • ticker: The underlying stock ticker symbol (e.g., PINS).
  • contract_type: Option type — CALL or PUT.
  • strike_price: The strike price of the option contract.
  • expiration_date: The expiration date of the option contract (YYYY-MM-DD).
  • buy_target: Recommended entry price for the option contract.
  • first_sell_target: First profit-taking sell target. Half the position is sold here.
  • second_sell_target: Second profit-taking sell target. The remaining half is sold here.
  • stop_loss: Risk management level to limit downside.
  • up_10d_pct: Model-derived probability of a price increase in the underlying stock over the next 10 trading days, expressed as a decimal between 0 and 1 (e.g. 0.79 = 79% bullish probability). Values above 0.5 indicate bullish conviction; below 0.5 indicate bearish. This is a snapshot from the day the prediction was added to the active list and is not updated while the signal remains active. Can be null.
  • prediction_sent_on: The date when the prediction was generated (YYYY-MM-DD).
GET /api/options-active/

Headers:
    Authorization: Api-Key YOUR_API_KEY

Response:
    {
        "count": 12,
        "results": [
            {
                "ticker": "PINS",
                "contract_type": "PUT",
                "strike_price": 25.0,
                "expiration_date": "2026-02-20",
                "buy_target": 5.05,
                "first_sell_target": 6.38,
                "second_sell_target": 6.83,
                "stop_loss": 5.13,
                "up_10d_pct": 0.79,
                "prediction_sent_on": "2026-02-04"
            }
        ]
    }

Examples:
    - Get all active signals: /api/options-active/
        

Code Example

Fetch currently active options signals. This can be run as a scheduled task to check for new signals before or during market hours. Remember to replace YOUR_API_KEY with your actual API key.

import requests

url = 'https://www.sharepredictions.com/api/options-active/'
headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
data = response.json()

if data['count'] > 0:
    for signal in data['results']:
        ticker = signal['ticker']
        ct = signal['contract_type']
        buy = signal['buy_target']
        t1 = signal['first_sell_target']
        sl = signal['stop_loss']
        print(f"{ticker} {ct}: Buy ${buy}, T1 ${t1}, SL ${sl}")
else:
    print("No active options signals at this time.")
            

Concluded Options Predictions

Retrieve the archive of concluded (closed) AI options predictions. Each prediction includes the original signal levels plus the computed result and simulated profit/loss percentage. Up to 2,000 of the most recent concluded predictions are returned, newest first.

The P/L percentage is calculated based on the prediction outcome:

  • Stop Loss — full position was closed at the stop-loss level.
  • 1st Target + SL — half sold at the 1st target, remaining half hit stop loss; P/L is the average.
  • 1st Target — half sold at the 1st target, remaining half expired; P/L is half the 1st target gain.
  • 2nd Target — half sold at the 1st target, half at the 2nd target; P/L is the average of both.
  • Expired — position expired without hitting any target or stop loss.

The response includes the following fields:

  • ticker: The underlying stock ticker symbol (e.g., PINS).
  • contract_type: Option type — CALL or PUT.
  • strike_price: The strike price of the option contract.
  • expiration_date: The expiration date of the option contract (YYYY-MM-DD).
  • buy_target: Recommended entry price for the option contract.
  • first_sell_target: First profit-taking sell target.
  • second_sell_target: Second profit-taking sell target.
  • stop_loss: Risk management stop-loss level.
  • result: Prediction outcome — "2nd Target", "1st Target + SL", "Stop Loss", "1st Target", or "Expired".
  • pl_pct: Simulated profit/loss as a percentage (e.g., 30.88 means +30.88%). Calculated according to the rules above.
  • first_target_hit_at: Datetime when the 1st target was hit, or null.
  • second_target_hit_at: Datetime when the 2nd target was hit, or null.
  • stop_loss_hit_at: Datetime when the stop loss was hit, or null.
  • prediction_sent_on: The date the prediction was generated (YYYY-MM-DD).
  • finalized_at: The date the prediction was finalized.
GET /api/options-concluded/

Headers:
    Authorization: Api-Key YOUR_API_KEY

Response:
    {
        "count": 1850,
        "results": [
            {
                "ticker": "PINS",
                "contract_type": "PUT",
                "strike_price": 25.0,
                "expiration_date": "2026-02-20",
                "buy_target": 5.05,
                "first_sell_target": 6.38,
                "second_sell_target": 6.83,
                "stop_loss": 5.13,
                "result": "2nd Target",
                "pl_pct": 30.88,
                "first_target_hit_at": "2026-02-12",
                "second_target_hit_at": "2026-02-13",
                "stop_loss_hit_at": null,
                "prediction_sent_on": "2026-02-04",
                "finalized_at": "2026-02-13"
            }
        ]
    }

Examples:
    - Get all concluded predictions: /api/options-concluded/
        

Code Example

Fetch the full archive of concluded options predictions to evaluate the algorithm's track record or build your own analytics. The response includes up to 2,000 predictions. Remember to replace YOUR_API_KEY with your actual API key.

import requests

url = 'https://www.sharepredictions.com/api/options-concluded/'
headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
data = response.json()

wins = [t for t in data['results'] if t['pl_pct'] > 0]
losses = [t for t in data['results'] if t['pl_pct'] <= 0]

print(f"Total: {data['count']} predictions")
print(f"Wins: {len(wins)}, Losses: {len(losses)}")

if wins:
    avg_win = sum(t['pl_pct'] for t in wins) / len(wins)
    print(f"Avg win: +{avg_win:.2f}%")
if losses:
    avg_loss = sum(t['pl_pct'] for t in losses) / len(losses)
    print(f"Avg loss: {avg_loss:.2f}%")
            

Active Stock Predictions

Retrieve all currently active AI stock portfolio predictions. Each signal includes a buy target, sell target, and stop-loss level for US stocks. Active positions are updated daily before market open. Use the ?penny=true query parameter to retrieve only penny stock predictions.

The response includes the following fields:

  • ticker: The stock ticker symbol (e.g., AAPL).
  • buy_target: Recommended entry price for the stock.
  • sell_target: Profit-taking sell target price.
  • stop_loss: Risk management stop-loss price level.
  • days_held: Number of trading days the position has been active, or null if not yet available.
  • up_10d_pct: Model-derived probability of a price increase in the stock over the next 10 trading days, expressed as a decimal between 0 and 1 (e.g. 0.79 = 79% bullish probability). Values above 0.5 indicate bullish conviction; below 0.5 indicate bearish. Snapshot from the day the signal was added. Can be null.
  • latest_price: Most recent market price of the stock, or null.
  • volatility: Recent price volatility measure for the stock, or null.
  • prediction_sent_on: The date the prediction was generated (YYYY-MM-DD).
GET /api/stocks-active/

Headers:
    Authorization: Api-Key YOUR_API_KEY

Query Parameters (optional):
    penny=true  — Return only penny stock predictions

Response:
    {
        "count": 8,
        "results": [
            {
                "ticker": "AAPL",
                "buy_target": 182.450,
                "sell_target": 195.120,
                "stop_loss": 176.800,
                "days_held": 3,
                "up_10d_pct": 0.74,
                "latest_price": 188.52,
                "volatility": 0.032,
                "prediction_sent_on": "2026-02-14"
            }
        ]
    }

Examples:
    - Get all active signals: /api/stocks-active/
    - Get penny stocks only: /api/stocks-active/?penny=true
        

Code Example

Fetch currently active stock portfolio signals. This can be run as a scheduled task to check for new signals before or during market hours. Remember to replace YOUR_API_KEY with your actual API key.

import requests

url = 'https://www.sharepredictions.com/api/stocks-active/'
headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
}

# Get all active stock signals
response = requests.get(url, headers=headers)

# Or get penny stocks only
# response = requests.get(url, headers=headers, params={'penny': 'true'})

data = response.json()

if data['count'] > 0:
    for signal in data['results']:
        ticker = signal['ticker']
        buy = signal['buy_target']
        sell = signal['sell_target']
        sl = signal['stop_loss']
        print(f"{ticker}: Buy ${buy}, Sell ${sell}, SL ${sl}")
else:
    print("No active stock signals at this time.")
            

Concluded Stock Predictions

Retrieve the archive of concluded (closed) AI stock portfolio predictions. Each prediction includes the original signal levels plus the computed result and profit/loss percentage. Up to 2,000 of the most recent concluded predictions are returned, newest first. Use the ?penny=true query parameter to retrieve only penny stock results.

The result field indicates how the position was closed:

  • Target Hit — the stock price reached the sell target, position closed at a profit.
  • Stop Loss — the stock price hit the stop-loss level, position closed to limit downside.
  • Closed — the position was closed based on bearish signals before hitting either the sell target or stop loss.

The response includes the following fields:

  • ticker: The stock ticker symbol (e.g., AAPL).
  • buy_target: The recommended entry price for the stock.
  • sell_target: The profit-taking sell target price.
  • stop_loss: The risk management stop-loss price level.
  • result: Prediction outcome — "Target Hit", "Stop Loss", or "Closed".
  • pl_pct: Profit/loss as a percentage (e.g., 15.0 means +15%). Negative values indicate a loss.
  • days_held: Number of trading days the position was held, or null.
  • prediction_sent_on: The date the prediction was generated (YYYY-MM-DD).
  • finalized_at: The date the position was closed.
GET /api/stocks-concluded/

Headers:
    Authorization: Api-Key YOUR_API_KEY

Query Parameters (optional):
    penny=true  — Return only penny stock predictions

Response:
    {
        "count": 1850,
        "results": [
            {
                "ticker": "AAPL",
                "buy_target": 182.450,
                "sell_target": 195.120,
                "stop_loss": 176.800,
                "result": "Target Hit",
                "pl_pct": 6.95,
                "days_held": 7,
                "prediction_sent_on": "2026-02-04",
                "finalized_at": "2026-02-13"
            }
        ]
    }

Examples:
    - Get all concluded predictions: /api/stocks-concluded/
    - Get penny stocks only: /api/stocks-concluded/?penny=true
        

Code Example

Fetch the full archive of concluded stock predictions to evaluate the algorithm's track record or build your own analytics. The response includes up to 2,000 predictions. Remember to replace YOUR_API_KEY with your actual API key.

import requests

url = 'https://www.sharepredictions.com/api/stocks-concluded/'
headers = {
    'Authorization': 'Api-Key YOUR_API_KEY'
}

# Get all concluded stock predictions
response = requests.get(url, headers=headers)

# Or get penny stocks only
# response = requests.get(url, headers=headers, params={'penny': 'true'})

data = response.json()

wins = [t for t in data['results'] if t['pl_pct'] > 0]
losses = [t for t in data['results'] if t['pl_pct'] <= 0]

print(f"Total: {data['count']} predictions")
print(f"Wins: {len(wins)}, Losses: {len(losses)}")

if wins:
    avg_win = sum(t['pl_pct'] for t in wins) / len(wins)
    print(f"Avg win: +{avg_win:.2f}%")
if losses:
    avg_loss = sum(t['pl_pct'] for t in losses) / len(losses)
    print(f"Avg loss: {avg_loss:.2f}%")