ROAR APIs

What is ROAR?

The ROAR Score is a momentum-based metric that measures the current risk level of any stock or ETF on a scale of 0-100. Instead of static ratings, ROAR gives you a dynamic, real-time view of whether a security is in a strong uptrend (lower risk) or showing warning signs (higher risk).

Getting Started

Prerequisites

Reach out to us with your use-case and get an API key
Basic understanding of REST APIs
HTTP client or SDK for making requests

Authentication

All ROAR API requests require authentication via the x-api-key header:

x-api-key: YOUR_API_KEY

Include this header in every request to the ROAR API.

Base URL

https://api.pitrade.com

All endpoints are relative to this base URL.

API Endpoints

1. Get ROAR Score History

Retrieve ROAR score history for a specific ticker over a date range.

Endpoint: GET /roar/v1/ticker/{ticker}

Path Parameters:

Parameter	Type	Required	Description
ticker	string	Yes	Stock ticker symbol (e.g. AAPL)

Query Parameters:

Parameter	Type	Required	Default	Description
from	string	No	1 year ago	Start date in `YYYY-MM-DD` format (US/Eastern)
to	string	No	Today	End date in `YYYY-MM-DD` format (US/Eastern)
sort	string	No	asc	Sort order: `asc` or `desc`

Example Request:

curl -X GET "https://api.pitrade.com/roar/v1/ticker/AAPL?from=2025-01-01&to=2025-06-01&sort=asc" \
  -H "x-api-key: YOUR_API_KEY"

Success Response (200):

[
  { "timestamp": 1704067200000, "value": 42.5 },
  { "timestamp": 1704153600000, "value": 43.1 },
  { "timestamp": 1704240000000, "value": 41.8 }
]

Response Fields:

Field	Type	Description
timestamp	number	Unix timestamp in milliseconds
value	number	ROAR Score (0-100 scale, lower = lower risk)

Error Responses:

Status	Description	Example Body
400	Invalid parameters	`{"message": "sort must be 'asc' or 'desc'"}`
403	Unauthorized	`{"message": "Invalid API key"}`
500	Server error	`{"message": "An unexpected error occurred"}`

2. Get All Tickers Current ROAR Scores

Retrieve the latest ROAR scores for all available tickers.

Endpoint: GET /roar/v1/snapshot/tickers

Parameters: None

Example Request:

curl -X GET "https://api.pitrade.com/roar/v1/snapshot/tickers" \
  -H "x-api-key: YOUR_API_KEY"

Success Response (200):

{
  "AAPL": 45.2,
  "GOOGL": 38.7,
  "MSFT": 41.3,
  "TSLA": 52.1,
  "AMZN": 39.8,
  "META": 44.5
}

Response Format:

Object with ticker symbols as keys and ROAR scores (0-100) as values. Lower scores indicate lower risk/stronger uptrends.

Error Responses:

Status	Description	Example Body
403	Unauthorized	`{"message": "Invalid API key"}`
404	No data available	`{"message": "No data available"}`
500	Server error	`{"message": "An unexpected error occurred"}`

3. Get Single Ticker Current ROAR Score

Retrieve the latest ROAR score for a specific ticker.

Endpoint: GET /roar/v1/snapshot/tickers/{ticker}

Path Parameters:

Parameter	Type	Required	Description
ticker	string	Yes	Stock ticker symbol (e.g. AAPL)

Example Request:

curl -X GET "https://api.pitrade.com/roar/v1/snapshot/tickers/AAPL" \
  -H "x-api-key: YOUR_API_KEY"

Success Response (200):

{
  "ticker": "AAPL",
  "value": 45.2
}

Response Fields:

Field	Type	Description
ticker	string	The requested ticker symbol
value	number	ROAR Score (0-100, lower = lower risk)

Error Responses:

Status	Description	Example Body
400	Invalid parameter	`{"message": "Ticker must be a non-empty string"}`
403	Unauthorized	`{"message": "Invalid API key"}`
404	Ticker not found	`{"message": "Ticker 'XYZ' not found"}`
500	Server error	`{"message": "An unexpected error occurred"}`

Rate Limits

Requests are throttled per API key via usage plans. Contact your account manager for your specific rate limits.

Common Use Cases

Monitor Risk Levels in Your Portfolio

Track ROAR scores for all holdings to identify momentum changes:

# Get latest ROAR scores for all tickers
curl -X GET "https://api.pitrade.com/roar/v1/snapshot/tickers" \
  -H "x-api-key: YOUR_API_KEY"

Identify Strong Uptrends

Find securities with low ROAR scores (lower risk, strong momentum):

# Get latest ROAR score for a specific ticker
curl -X GET "https://api.pitrade.com/roar/v1/snapshot/tickers/AAPL" \
  -H "x-api-key: YOUR_API_KEY"

Detect Momentum Fading

Analyze ROAR trends over time to spot when momentum is weakening:

# Get 3-month ROAR history to track momentum changes
curl -X GET "https://api.pitrade.com/roar/v1/ticker/AAPL?from=2025-03-01&to=2025-06-01" \
  -H "x-api-key: YOUR_API_KEY"

Avoid Peak Buying

Use ROAR to identify overextended moves before pullbacks:

# Compare current ROAR with historical levels
curl -X GET "https://api.pitrade.com/roar/v1/snapshot/tickers/AAPL" \
  -H "x-api-key: YOUR_API_KEY"

Best Practices

1. Cache Results

Cache snapshot data to reduce API calls
Implement appropriate cache expiration based on your needs

2. Error Handling

Always handle 400, 403, and 500 errors gracefully
Implement retry logic with exponential backoff for 500 errors

3. Date Formats

Always use YYYY-MM-DD format for date parameters
Dates are interpreted in US/Eastern timezone

4. Rate Limiting

Monitor your API usage against your rate limit
Implement request queuing if needed

5. API Key Security

Never expose your API key in client-side code
Store API keys securely in environment variables
Rotate keys periodically

Example Integration

JavaScript/Node.js

const axios = require("axios");

const API_KEY = process.env.ROAR_API_KEY;
const BASE_URL = "https://api.pitrade.com";

// Get ROAR score history for a specific ticker
async function getRoarScoreHistory(ticker, from, to) {
  try {
    const response = await axios.get(`${BASE_URL}/roar/v1/ticker/${ticker}`, {
      params: { from, to, sort: "asc" },
      headers: { "x-api-key": API_KEY },
    });
    return response.data;
  } catch (error) {
    console.error("Error fetching ROAR score history:", error.message);
    throw error;
  }
}

// Get current ROAR scores for all tickers
async function getAllRoarScores() {
  try {
    const response = await axios.get(`${BASE_URL}/roar/v1/snapshot/tickers`, {
      headers: { "x-api-key": API_KEY },
    });
    return response.data;
  } catch (error) {
    console.error("Error fetching all ROAR scores:", error.message);
    throw error;
  }
}

// Get current ROAR score for a specific ticker
async function getRoarScore(ticker) {
  try {
    const response = await axios.get(
      `${BASE_URL}/roar/v1/snapshot/tickers/${ticker}`,
      {
        headers: { "x-api-key": API_KEY },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error fetching ROAR score:", error.message);
    throw error;
  }
}

// Usage
(async () => {
  const roarHistory = await getRoarScoreHistory(
    "AAPL",
    "2025-01-01",
    "2025-06-01",
  );
  console.log("AAPL ROAR History:", roarHistory);

  const allScores = await getAllRoarScores();
  console.log("All ROAR Scores:", allScores);

  const currentScore = await getRoarScore("AAPL");
  console.log("AAPL Current ROAR Score:", currentScore);
})();

Python

import requests
import os
from datetime import datetime, timedelta

API_KEY = os.getenv('ROAR_API_KEY')
BASE_URL = 'https://api.pitrade.com'

def get_roar_score_history(ticker, from_date=None, to_date=None):
    """Get ROAR score history for a specific ticker"""
    if not from_date:
        from_date = (datetime.now() - timedelta(days=365)).strftime('%Y-%m-%d')
    if not to_date:
        to_date = datetime.now().strftime('%Y-%m-%d')

    url = f'{BASE_URL}/roar/v1/ticker/{ticker}'
    headers = {'x-api-key': API_KEY}
    params = {'from': from_date, 'to': to_date, 'sort': 'asc'}

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

def get_all_roar_scores():
    """Get current ROAR scores for all tickers"""
    url = f'{BASE_URL}/roar/v1/snapshot/tickers'
    headers = {'x-api-key': API_KEY}

    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

def get_roar_score(ticker):
    """Get current ROAR score for a specific ticker"""
    url = f'{BASE_URL}/roar/v1/snapshot/tickers/{ticker}'
    headers = {'x-api-key': API_KEY}

    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

# Usage
if __name__ == '__main__':
    roar_history = get_roar_score_history('AAPL')
    print('AAPL ROAR History:', roar_history)

    all_scores = get_all_roar_scores()
    print('All ROAR Scores:', all_scores)

    current_score = get_roar_score('AAPL')
    print('AAPL Current ROAR Score:', current_score)

Support

For technical support or questions about the ROAR API:

Review the endpoint documentation above
Check the example integrations
Contact our team for further support