watchcharts.com 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.
curl -X GET 'https://api.parse.bot/scraper/06180d8c-0b10-4aca-ba50-436679893e5b/search_watches?query=rolex' \ -H 'X-API-Key: $PARSE_API_KEY'
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.
| 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.com 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.
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.
- 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 | 250 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.