companiesmarketcap APIcompaniesmarketcap.com ↗
Access global market cap rankings, company financial profiles, and historical metrics for publicly traded companies via the companiesmarketcap.com API.
What is the companiesmarketcap API?
This API exposes 4 endpoints covering global public-company data from companiesmarketcap.com, including paginated market cap rankings, company search, detailed financial profiles, and full historical metric series. The get_ranking endpoint returns up to 100 companies per page with rank, ticker, price, daily change, and country. The get_company_metric_history endpoint lets you pull year-by-year series for metrics like P/E ratio, EPS, dividend yield, and total assets for any tracked company.
curl -X GET 'https://api.parse.bot/scraper/15cf1f63-f346-498c-b7fe-f15e39921723/get_ranking?page=1' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace companiesmarketcap-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: CompaniesMarketCap SDK — market cap rankings, search, and financial metrics."""
from parse_apis.companiesmarketcap_api import CompaniesMarketCap, Metric, CompanyNotFound
client = CompaniesMarketCap()
# List top companies by market cap — limit caps total items fetched.
for company in client.companies.list(limit=5):
print(company.name, company.ticker, company.market_cap.formatted, company.country)
# Search for a company by name; take one result with .first().
result = client.searchresults.search(query="Tesla", limit=1).first()
if result:
print(result.name, result.identifier, result.type)
# Fetch full company details using the identifier.
try:
detail = client.companydetails.get(identifier="AAPL")
print(detail.name, detail.ticker, detail.market_cap_info.marketcap)
for entry in detail.revenue_history[:3]:
print(entry.year, entry.value, entry.change)
except CompanyNotFound as exc:
print(f"Company not found: {exc.identifier}")
# Get a specific financial metric history using the Metric enum.
history = client.metrichistories.get(identifier="MSFT", metric=Metric.PE_RATIO)
for entry in history.history[:3]:
print(entry.year, entry.value, entry.change)
print("exercised: companies.list / searchresults.search / companydetails.get / metrichistories.get")
Retrieve the global ranking of companies by market capitalization. Returns 100 companies per page, ordered by descending market cap. Each company includes rank, name, ticker, market cap (formatted and raw), price, daily change, and country. Paginate with the page parameter.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number to retrieve (100 companies per page). |
{
"type": "object",
"fields": {
"page": "integer, current page number",
"companies": "array of company objects with rank, name, ticker, market_cap, price, today_change, and country",
"total_results": "integer, number of companies returned on this page"
}
}About the companiesmarketcap API
Market Cap Rankings and Company Search
The get_ranking endpoint returns ranked lists of publicly traded companies by market capitalization, 100 per page. Each record includes rank, name, ticker, market_cap, price, today_change, and country. Use the page parameter to paginate through the full global list. The search endpoint accepts a company name or ticker symbol via the query parameter and returns matching companies and ETFs with their identifier, name, url, and type — useful for resolving a user-supplied name to the slug or ticker needed by other endpoints.
Company Profiles and Financial History
The get_company_details endpoint accepts a ticker or company slug (e.g., AAPL or tesla) and returns a market_cap_info object containing rank, marketcap, country, share_price, change_1_day, change_1_year, categories, and a text description. It also includes revenue_history and earnings_history arrays, each with annual year, value, and change fields, giving a longitudinal view of top-line and bottom-line performance.
Historical Metric Series
The get_company_metric_history endpoint retrieves the full annual history for any supported metric. Pass a metric string — options include pe-ratio, eps, dividend-yield, shares-outstanding, total-assets, revenue, earnings, operating-margin, and pb-ratio — alongside an identifier. The response returns a history array of { year, value, change } objects, making it straightforward to chart trends or compute derived statistics over time.
Coverage Notes
Data covers globally listed public companies tracked by companiesmarketcap.com. Rankings reflect real-time market capitalization. Historical metric coverage depth varies by company; smaller or recently listed companies may have shorter histories than large-cap incumbents.
The companiesmarketcap API is a managed, monitored endpoint for companiesmarketcap.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when companiesmarketcap.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official companiesmarketcap.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a market cap leaderboard that pages through global rankings using
get_rankingwith thepageparameter. - Resolve user-typed company names or tickers to canonical identifiers before querying detailed data via
search. - Chart 10-year P/E ratio trends for any public company using
get_company_metric_historywithmetric=pe-ratio. - Compare annual EPS and operating margin histories across a watchlist of companies.
- Display a company profile card with current market cap, rank, 1-day and 1-year price change from
get_company_details. - Screen stocks by dividend yield history using the
dividend-yieldmetric and flagging multi-year growth patterns. - Aggregate country-level market cap totals by collecting the
countryfield from paginated ranking results.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does companiesmarketcap.com offer an official developer API?+
What does `get_company_metric_history` return, and which metrics are supported?+
history array of annual { year, value, change } records for the requested metric. Supported metric strings include pe-ratio, eps, dividend-yield, shares-outstanding, total-assets, revenue, earnings, operating-margin, and pb-ratio, among others available on the site. Pass any of these as the metric parameter along with a ticker or slug as the identifier.Does the API return intraday price data or only daily snapshots?+
today_change (daily change), and a change_1_year figure. Intraday OHLCV bars or minute-level price history are not currently covered. You can fork this API on Parse and revise it to add an endpoint targeting intraday or tick-level data if your source supports it.Are ETFs included in search results?+
search endpoint returns both companies and ETFs, distinguished by the type field in each result object. The get_company_details and get_company_metric_history endpoints work with any identifier returned by search, including ETF slugs, though metric history depth for ETFs may be limited compared to individual equities.Is there a way to filter the ranking by country or sector?+
get_ranking endpoint does not currently accept country or sector filter parameters — it returns the global ranked list paginated by page. The country field is present in each result, so client-side filtering is possible. You can fork this API on Parse and revise it to add country- or category-filtered ranking endpoints if the source exposes those views.