REST API Documentation

Access Dividend Hunting data programmatically

rocket_launch Getting Started

Base URL
https://dividendhunting.com/core/api/
Authentication

All API requests require authentication using an API key. Include your key in the request header:

Authorization: Api-Key YOUR_API_KEY_HERE
💡 Where to get your API key:
  1. Log in to your Dividend Hunting account
  2. Access Dividend Hunting here
  3. Find "API KEY" in the top left corner of the screen
  4. Click "Copy" or "Regenerate"
  5. Securely store your key
Subscription Tiers

Access to certain fields depends on your subscription tier:

  • Free: Basic fields (symbol, name, price, etc.)
  • Premium/Pro: Proprietary metrics (recovery rate, decay score, overall score, etc.)

Requests to blocked fields will return a 400 Bad Request error.

api API Endpoints

GET /core/api/stocks/

Retrieve a list of stocks with dividend data and analysis.

Example Request
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     https://dividendhunting.com/core/api/stocks/
Query Parameters
Parameter Type Description Example
symbol String Filter by stock symbol ?symbol=AAPL
ordering String Order results by field (use - for descending) ?ordering=-overall_score
fields String (comma-separated) Specify which fields to return ?fields=symbol,price,dividend_yield_ttm
limit Integer Number of results per page ?limit=50
offset Integer Pagination offset ?offset=50
search String Search across fields (Premium only) ?search=apple
Example Response (200 OK)
{
  "count": 5000,
  "next": "https://dividendhunting.com/core/api/stocks/?offset=50",
  "previous": null,
  "results": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "price": 175.43,
      "dividend_yield_ttm": 2.45,
      "recovery_rate": 85.7,
      "adjusted_recovery_avg": 12.3,
      "overall_score": 78.5,
      "decay_score": 72.1
    },
    ...
  ]
}
Error Responses
400 Bad Request - Requested blocked fields for your subscription tier 
{
  "detail": "Requesting blocked fields (recovery_rate, decay_score) is not allowed for your subscription tier."
}
401 Unauthorized - Missing or invalid API key 
{
  "detail": "Authentication credentials were not provided."
}
GET /core/api/etfs/

Retrieve a list of ETFs with dividend data and analysis.

Example Request
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     https://dividendhunting.com/core/api/etfs/
Query Parameters

Same as /stocks/ endpoint (see above)

Example Response (200 OK)
{
  "count": 1200,
  "next": "https://dividendhunting.com/core/api/etfs/?offset=50",
  "previous": null,
  "results": [
    {
      "symbol": "VYM",
      "name": "Vanguard High Dividend Yield ETF",
      "price": 112.34,
      "dividend_yield_ttm": 3.12,
      "net_assets": 42000000000,
      "expense_ratio": 0.0006,
      "recovery_rate": 78.3,
      "overall_score": 82.7
    },
    ...
  ]
}
GET /core/api/stocks/{id}/ and /core/api/etfs/{id}/

Retrieve detailed information for a specific stock or ETF by ID.

Example Request
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     https://dividendhunting.com/core/api/stocks/123/
Example Response (200 OK)
{
  "id": 123,
  "symbol": "MSFT",
  "name": "Microsoft Corporation",
  "price": 380.50,
  "dividend_yield_ttm": 0.89,
  "market_cap": 2800000000000,
  "pe_ratio": 34.5,
  "eps_ttm": 11.02,
  "recovery_rate": 82.4,
  "adjusted_recovery_avg": 14.7,
  "overall_score": 75.3,
  "decay_score": 68.9,
  ...
}

list_alt Available Fields

Common Fields (All Tiers)
Field Type Description
id Integer Unique identifier
symbol String Ticker symbol
name String Full company/ETF name
price Decimal Current market price
dividend_frequency String Payment frequency (e.g., "quarterly")
market_cap Decimal Market capitalization (stocks only)
net_assets Decimal Assets under management (ETFs only)
expense_ratio Decimal Annual expense ratio (ETFs only)
Premium/Pro Fields 🔒
Field Type Description
recovery_rate Decimal % of events recovered within 30 days
adjusted_recovery_avg Decimal Average days to recovery
dividend_yield_ttm Decimal Real dividend yield (trailing 12 months)
usd_earnings_per_1000 Decimal Earnings per $1,000 invested
overall_score Decimal Composite quality score (0-100)
decay_score Decimal Recovery reliability score (0-100)

See Metrics Guide for detailed explanations of proprietary fields.

speed Rate Limits

Tier Requests/Minute Requests/Day
Free 10 300
Premium 60 1,000
Pro Unlimited Unlimited

Rate limit exceeded: 429 Too Many Requests

code Code Examples

Python (requests) 
import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://dividendhunting.com/core/api"

headers = {
    "Authorization": f"Api-Key {API_KEY}"
}

# Get top stocks by overall score
response = requests.get(
    f"{BASE_URL}/stocks/",
    headers=headers,
    params={
        "ordering": "-overall_score",
        "limit": 10,
        "fields": "symbol,name,overall_score,recovery_rate"
    }
)

if response.status_code == 200:
    data = response.json()
    for stock in data["results"]:
        print(f"{stock['symbol']}: Score {stock['overall_score']}")
else:
    print(f"Error: {response.status_code}")
cURL 
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     "https://dividendhunting.com/core/api/stocks/?ordering=-overall_score&limit=10"
JavaScript (fetch) 
const API_KEY = "your_api_key_here";
const BASE_URL = "https://dividendhunting.com/core/api";

fetch(`${BASE_URL}/stocks/?ordering=-decay_score&limit=10`, {
  headers: {
    "Authorization": `Api-Key ${API_KEY}`
  }
})
  .then(response => response.json())
  .then(data => {
    data.results.forEach(stock => {
      console.log(`${stock.symbol}: ${stock.decay_score}`);
    });
  })
  .catch(error => console.error("Error:", error));

help_outline Support

Need help with the API? We're here to assist:

For security issues or vulnerabilities, please email: security@dividendhunting.com