WatchCharts APIwatchcharts.com ↗
Access WatchCharts data via API: search brands and models, browse the watch directory with retail/market prices, and pull historical trends, listings, and recent sales.
What is the WatchCharts API?
The WatchCharts API exposes luxury watch market data across 3 endpoints, covering brand and model search, paginated directory browsing, and detailed per-model market intelligence. The get_watch_details endpoint returns historical USD price trend data, active listings with source attribution, and recent sale records for any watch identified by its numeric ID. Data covers major brands including Rolex, Patek Philippe, and Omega.
curl -X GET 'https://api.parse.bot/scraper/06180d8c-0b10-4aca-ba50-436679893e5b/search_watches?query=rolex' \ -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 watchcharts-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.
from parse_apis.watchcharts_market_data_api import WatchCharts, Watch, WatchDetails, Brand, PriceTrend, Listing
client = WatchCharts()
# Search for watch brands
for brand in client.brands.search(query="rolex"):
print(brand.name, brand.model_count, brand.display_top_level_brand)
# Browse watches filtered by brand
for watch in client.watches.list(query="omega"):
print(watch.name, watch.retail_price, watch.market_price)
# Get detailed market data for a specific watch
details = client.watch(id="727").details()
print(details.watch_id, details.trend.retail_price, details.trend.currency_symbol)
print(details.listings.currency_symbol, details.sales.currency_symbol)
Search for watch brands and model families using the WatchCharts suggestion API. Returns matching brands and models with metadata like image URLs, model counts, and brand hierarchy. Each brand result includes its parent brand relationship and the number of models within it.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search term for finding watch brands or model families. Supports multi-word queries (e.g. 'patek philippe', 'rolex submariner'). |
{
"type": "object",
"fields": {
"brands": "array of brand objects with id, name, image, model_count, and brand hierarchy fields",
"models": "array of model objects (populated when query matches specific models)"
},
"sample": {
"data": {
"brands": [
{
"id": 24,
"name": "Rolex",
"uuid": "c3c48e9a-0f23-4186-b7bf-937bef6420bf",
"brand": "",
"image": "https://cdn.watchcharts.com/brands/73a5e99a-6990-4ab4-8b41-3161fd925250",
"parent_id": null,
"model_count": 12,
"display_brand": "",
"top_level_brand": "rolex",
"collection_count": 18,
"display_top_level_brand": "Rolex"
}
],
"models": []
},
"status": "success"
}
}About the WatchCharts API
Search and Browse
The search_watches endpoint accepts a free-text query string and returns two arrays: brands (with fields for id, name, image, model_count, and brand hierarchy) and models (populated when the query resolves to a specific model family). Multi-word brand names like patek philippe or rolex daytona are supported. This is the right starting point for resolving user input into structured brand and model identifiers.
The list_watches endpoint browses the watch directory with optional query filtering by brand name and integer page pagination. Each result in the watches array includes id, slug, name, retail_price, market_price, and url. Omitting the query parameter returns popular watches across all brands, making it useful for trending-watch feeds or seeding a database with widely-traded references.
Per-Watch Market Data
The get_watch_details endpoint takes a watch_id (numeric string from list_watches) and returns three top-level objects. The trend object maps timestamps to USD prices, and also carries retail_price and currency_symbol, giving enough data to plot a historical price curve. The listings object groups current and sold listings by status; each listing record includes id, title, price, source, and image. The sales object contains recent sale records with price and date fields, useful for calculating realized-price distributions.
Coverage Notes
Watch IDs are stable numeric identifiers that appear in both list_watches results and detail URLs on WatchCharts. IDs like 727 or 22557 can be hardcoded once discovered. The directory covers luxury and collectible watch references across major Swiss and independent brands tracked by WatchCharts.
The WatchCharts API is a managed, monitored endpoint for watchcharts.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when watchcharts.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 watchcharts.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?+
- Track historical USD price trends for a specific reference using
get_watch_detailstrend timestamps - Build a brand-filtered watch inventory browser using
list_watcheswith a brandqueryandpagepagination - Compare
retail_pricevsmarket_priceacross models to surface watches trading at a premium or discount - Aggregate recent sale records from
get_watch_detailsto estimate realized-price distributions for a reference - Power a watch search autocomplete using
search_watchesbrand and model result arrays - Monitor active listing counts and sources per reference by parsing the
listingsobject fromget_watch_details - Build a trending-watches feed by calling
list_watcheswithout a query to get popular references across all brands
| 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 WatchCharts have an official developer API?+
What does `get_watch_details` return and how do I get the right `watch_id`?+
trend (timestamp-to-USD-price map plus retail price), listings (active and sold listings grouped by status, each with price, source, and image), and sales (recent sale records with price and date). Obtain a valid watch_id by calling list_watches first — the id field on any watch object in that response is the numeric string you pass here.Can I filter `list_watches` by price range or case size?+
list_watches endpoint filters only by brand name via the query parameter. It returns retail_price and market_price per watch, so client-side price filtering is possible after fetching results. You can fork this API on Parse and revise it to add a price-range or specification filter endpoint.Does the API return watch specifications like case diameter, movement type, or reference number?+
How fresh is the listings and sales data from `get_watch_details`?+
listings and sales objects reflect what WatchCharts currently shows for a given reference. There is no explicit freshness timestamp in the response, so the data should be treated as a point-in-time snapshot rather than a continuously updated feed. For time-sensitive use cases, polling on a schedule is advisable.