Ticker Predictions API

Retrieve AI-powered price predictions for a specific ticker. Returns daily or monthly forecasts with directional signals and confidence scores.

Endpoint

GET /v1/ticker/{ticker}/predictions/{type}

Authentication

Requires API key via token query parameter.

Parameters

Path Parameters

Parameter	Type	Required	Description
`ticker`	string	Yes	Stock ticker symbol (e.g., `AAPL`, `MSFT`)
`type`	string	Yes	Prediction type: `daily` or `monthly`

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	Your API key
`dateFrom`	string	No	Start date (YYYY-MM-DD)
`dateTo`	string	No	End date (YYYY-MM-DD)

Request

# Get daily predictions
curl "https://api.finbrain.tech/v1/ticker/AAPL/predictions/daily?token=YOUR_API_KEY"

# Get monthly predictions
curl "https://api.finbrain.tech/v1/ticker/AAPL/predictions/monthly?token=YOUR_API_KEY"

# Get historical predictions
curl "https://api.finbrain.tech/v1/ticker/AAPL/predictions/daily?token=YOUR_API_KEY&dateFrom=2024-01-01&dateTo=2024-01-31"

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

# Get predictions as DataFrame (recommended)
df = fb.predictions.ticker("AAPL", prediction_type="daily", as_dataframe=True)
print(df)
#                   main    lower    upper
# date
# 2024-11-04     201.33   197.21   205.45
# 2024-11-05     202.77   196.92   208.61

# Get raw JSON response
predictions = fb.predictions.ticker("AAPL", prediction_type="daily")
print(predictions)

# Get monthly predictions
monthly = fb.predictions.ticker("AAPL", prediction_type="monthly", as_dataframe=True)
print(monthly)

# Get historical predictions
historical = fb.predictions.ticker(
    "AAPL",
    prediction_type="daily",
    date_from="2024-01-01",
    date_to="2024-01-31",
    as_dataframe=True
)

#include <iostream>
#include <string>
#include <curl/curl.h>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

size_t WriteCallback(void* contents, size_t size, size_t nmemb, std::string* userp) {
    userp->append((char*)contents, size * nmemb);
    return size * nmemb;
}

json get_predictions(const std::string& ticker, const std::string& type,
                     const std::string& api_key) {
    CURL* curl = curl_easy_init();
    std::string response;

    if (curl) {
        std::string url = "https://api.finbrain.tech/v1/ticker/" + ticker +
                          "/predictions/" + type + "?token=" + api_key;

        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);
        curl_easy_perform(curl);
        curl_easy_cleanup(curl);
    }

    return json::parse(response);
}

int main() {
    auto data = get_predictions("AAPL", "daily", "YOUR_API_KEY");
    auto pred = data["prediction"];

    std::cout << "Ticker: " << data["ticker"].get<std::string>() << std::endl;
    std::cout << "Expected Short: " << pred["expectedShort"].get<std::string>() << "%" << std::endl;
    std::cout << "Expected Mid: " << pred["expectedMid"].get<std::string>() << "%" << std::endl;
    std::cout << "Expected Long: " << pred["expectedLong"].get<std::string>() << "%" << std::endl;

    // Access sentiment analysis
    auto sentiment = data["sentimentAnalysis"];
    for (auto& [date, score] : sentiment.items()) {
        std::cout << date << ": " << score.get<std::string>() << std::endl;
    }

    return 0;
}

use reqwest::blocking::Client;
use serde::Deserialize;
use serde_json::Value;
use std::collections::HashMap;
use std::error::Error;

#[derive(Debug, Deserialize)]
struct TickerPrediction {
    ticker: String,
    name: String,
    prediction: HashMap<String, Value>,
    #[serde(rename = "sentimentAnalysis")]
    sentiment_analysis: HashMap<String, String>,
}

fn get_predictions(ticker: &str, pred_type: &str, api_key: &str)
    -> Result<TickerPrediction, Box<dyn Error>> {
    let url = format!(
        "https://api.finbrain.tech/v1/ticker/{}/predictions/{}?token={}",
        ticker, pred_type, api_key
    );

    let client = Client::new();
    let response: TickerPrediction = client.get(&url).send()?.json()?;

    Ok(response)
}

fn main() -> Result<(), Box<dyn Error>> {
    let data = get_predictions("AAPL", "daily", "YOUR_API_KEY")?;

    println!("Ticker: {}", data.ticker);

    // Access expected values from prediction
    if let Some(Value::String(short)) = data.prediction.get("expectedShort") {
        println!("Expected Short: {}%", short);
    }
    if let Some(Value::String(long)) = data.prediction.get("expectedLong") {
        println!("Expected Long: {}%", long);
    }

    // Access sentiment history
    for (date, score) in &data.sentiment_analysis {
        println!("{}: {}", date, score);
    }

    Ok(())
}

import requests

response = requests.get(
    "https://api.finbrain.tech/v1/ticker/AAPL/predictions/daily",
    params={"token": "YOUR_API_KEY"}
)
predictions = response.json()

const response = await fetch(
  "https://api.finbrain.tech/v1/ticker/AAPL/predictions/daily?token=YOUR_API_KEY"
);
const predictions = await response.json();
console.log(predictions);

Response

Success Response (200 OK)

{
  "ticker": "AAPL",
  "name": "Apple Inc.",
  "prediction": {
    "2024-11-04": "201.33,197.21,205.45",
    "2024-11-05": "202.77,196.92,208.61",
    "2024-11-06": "203.99,196.90,211.08",
    "2024-11-07": "204.68,196.78,212.59",
    "2024-11-08": "204.72,195.56,213.88",
    "2024-11-11": "203.48,193.22,213.73",
    "2024-11-12": "203.32,191.97,214.66",
    "2024-11-13": "203.11,190.97,215.26",
    "2024-11-14": "203.32,190.66,215.97",
    "2024-11-15": "204.05,190.93,217.18",
    "expectedShort": "0.22",
    "expectedMid": "0.58",
    "expectedLong": "0.25",
    "type": "daily",
    "lastUpdate": "2024-11-01T23:24:18.371Z"
  },
  "sentimentAnalysis": {
    "2024-11-04": "0.186",
    "2024-11-01": "0.339",
    "2024-10-31": "0.565",
    "2024-10-30": "0.437",
    "2024-10-29": "0.433",
    "2024-10-28": "0.398",
    "2024-10-25": "0.443",
    "2024-10-24": "0.426",
    "2024-10-23": "0.426",
    "2024-10-22": "0.426"
  }
}

Response Fields

Field	Type	Description
`ticker`	string	Stock ticker symbol
`name`	string	Company name
`prediction`	object	Prediction data object with date-keyed forecasts
`sentimentAnalysis`	object	Historical sentiment scores keyed by date

Prediction Object Fields

Field	Type	Description
`{date}`	string	Date-keyed price predictions in format `"predicted,low,high"`
`expectedShort`	string	Expected short-term price change % (~3 days)
`expectedMid`	string	Expected mid-term price change % (~5 days)
`expectedLong`	string	Expected long-term price change % (~10 days)
`type`	string	Prediction type (`daily` or `monthly`)
`lastUpdate`	string	When prediction was last updated (ISO 8601)

Date-Keyed Price Predictions

Each date entry contains a comma-separated string with three values:

Predicted price: The model’s price forecast
Low bound: Lower confidence bound
High bound: Upper confidence bound

Example: "201.33,197.21,205.45" means predicted price of $201.33, with range $197.21 - $205.45

Sentiment Analysis Object

The sentimentAnalysis object contains historical sentiment scores keyed by date:

Field	Type	Description
`{date}`	string	Sentiment score for that date (-1 to 1)

Expected Move Interpretation

The expected move fields indicate percentage price change predictions:

Field	Time Horizon
`expectedShort`	~3 trading days
`expectedMid`	~5 trading days
`expectedLong`	~10 trading days

Usage Examples

Basic Prediction Lookup

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

data = fb.predictions.ticker("AAPL", prediction_type="daily")
pred = data["prediction"]

print(f"AAPL Prediction (updated {pred['lastUpdate']})")
print(f"  Expected Short-term: {pred['expectedShort']}%")
print(f"  Expected Mid-term: {pred['expectedMid']}%")
print(f"  Expected Long-term: {pred['expectedLong']}%")

# Parse date-keyed predictions
for key, value in pred.items():
    if key.startswith("202"):  # Date keys start with year
        predicted, low, high = value.split(",")
        print(f"  {key}: ${predicted} (range: ${low} - ${high})")

Extract Price Forecasts

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

def get_price_forecasts(ticker):
    """Extract price forecasts from predictions"""
    data = fb.predictions.ticker(ticker, prediction_type="daily")
    pred = data["prediction"]

    forecasts = []
    for key, value in pred.items():
        # Date keys are in YYYY-MM-DD format
        if "-" in key and len(key) == 10:
            predicted, low, high = value.split(",")
            forecasts.append({
                "date": key,
                "predicted": float(predicted),
                "low": float(low),
                "high": float(high)
            })

    return sorted(forecasts, key=lambda x: x["date"])

forecasts = get_price_forecasts("AAPL")
for f in forecasts:
    print(f"{f['date']}: ${f['predicted']:.2f} (${f['low']:.2f} - ${f['high']:.2f})")

Analyze Sentiment History

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

data = fb.predictions.ticker("AAPL", prediction_type="daily")
sentiment = data["sentimentAnalysis"]

# Convert to sorted list
sentiment_history = [
    {"date": date, "score": float(score)}
    for date, score in sentiment.items()
]
sentiment_history.sort(key=lambda x: x["date"], reverse=True)

print("Recent Sentiment History:")
for s in sentiment_history[:5]:
    sentiment_label = "Positive" if s["score"] > 0 else "Negative"
    print(f"  {s['date']}: {s['score']:.3f} ({sentiment_label})")

Analyze Multiple Tickers

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

tickers = ["AAPL", "MSFT", "GOOGL", "NVDA"]

for ticker in tickers:
    data = fb.predictions.ticker(ticker, prediction_type="daily")
    pred = data["prediction"]
    print(f"{ticker}: Short {pred['expectedShort']}%, Mid {pred['expectedMid']}%, Long {pred['expectedLong']}%")

Errors

Code	Error	Description
400	Bad Request	Invalid ticker or prediction type
401	Unauthorized	Invalid or missing API key
404	Not Found	Ticker not found
500	Internal Server Error	Server-side error

AI Price Forecasts Dataset - Use cases and analysis examples
Market Predictions - Get predictions for all tickers in a market
Available Tickers - Check if a ticker has predictions
Sentiments - Get sentiment data for a ticker