Overview
The Companies API provides access to comprehensive company profiles, financial metrics, and segment data from PostgreSQL databases.
Search Companies (Public)
Search for companies by ticker, name, sector, or industry without authentication.
Endpoint: GET /companies/public/search
Authentication: Not required
curl "https://api.financeagent.com/companies/public/search?query=Tesla&limit=8"
Search term (ticker, company name, sector, or industry)
Maximum results to return (1-20)
Response
Whether the search was successful
Array of matching companies
Stock ticker symbol (e.g., “TSLA”)
Stock exchange (e.g., “NASDAQ”)
Number of results returned
Query execution time in seconds
Search Companies (Authenticated)
Search with higher limits and additional features.
Endpoint: GET /companies/search
Authentication: Required
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
"https://api.financeagent.com/companies/search?query=tech&limit=50"
Get Company Details
Retrieve comprehensive company information including financials.
Endpoint: GET /companies/{symbol}
Authentication: Required
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
https://api.financeagent.com/companies/AAPL
Response
Get TTM Metrics
Retrieve Trailing Twelve Months (TTM) financial metrics.
Endpoint: GET /companies/{symbol}/ttm-metrics
Authentication: Required
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
https://api.financeagent.com/companies/MSFT/ttm-metrics
Response
TTM financial metrics
Year-over-year revenue growth %
Get Product Segments
Retrieve revenue breakdown by product segment.
Endpoint: GET /companies/{symbol}/product-segments
Authentication: Required
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
https://api.financeagent.com/companies/AAPL/product-segments
Response
Array of product segments
Segment name (e.g., “iPhone”)
Human-readable revenue (e.g., “$95.23B”)
Segment summary statistics
Total revenue across all segments
Data year (defaults to 2024 for historical data)
Get Geographic Segments
Retrieve revenue breakdown by geographic region.
Endpoint: GET /companies/{symbol}/geographic-segments
Authentication: Required
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
https://api.financeagent.com/companies/GOOGL/geographic-segments
Response
Same structure as product segments, but with geographic regions:
{
"success": true,
"symbol": "GOOGL",
"segment_type": "geographic",
"segments": [
{
"segment": "United States",
"revenue": 152300000000,
"formatted_revenue": "$152.30B",
"percentage": 47.5,
"year": 2024
},
{
"segment": "EMEA",
"revenue": 98700000000,
"formatted_revenue": "$98.70B",
"percentage": 30.8,
"year": 2024
}
]
}
Get TTM History
Retrieve historical TTM data for multiple quarters.
Endpoint: GET /companies/{symbol}/ttm-history
Authentication: Required
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
"https://api.financeagent.com/companies/NVDA/ttm-history?quarters=5"
Number of quarters to retrieve (1-10)
Response
Array of quarterly data
Period (Q1, Q2, Q3, Q4, or FY)
Example: Full Company Analysis
import requests
token = "YOUR_JWT_TOKEN"
headers = {"Authorization": f"Bearer {token}"}
base_url = "https://api.financeagent.com/companies"
# 1. Search for company
response = requests.get(
f"{base_url}/search",
params={"query": "Apple", "limit": 1},
headers=headers
)
symbol = response.json()["companies"][0]["symbol"]
# 2. Get detailed company info
details = requests.get(f"{base_url}/{symbol}", headers=headers).json()
# 3. Get TTM metrics
ttm = requests.get(f"{base_url}/{symbol}/ttm-metrics", headers=headers).json()
# 4. Get product segments
segments = requests.get(
f"{base_url}/{symbol}/product-segments",
headers=headers
).json()
print(f"Company: {details['company']['companyName']}")
print(f"Revenue: ${ttm['metrics']['revenueTtm']:,.0f}")
print(f"Top Segment: {segments['segments'][0]['segment']}")