Documentation
Sign up for free!
Get instant access to the API with your free API token. No billing details required!
Getting Started
Introduction
thewatchapi was developed to provide various easy access to watch data and prices via a REST API.
We provide comprehensive access to data regarding watch brands, their watch models and reference numbers.
Our watch price APIs are indicative of asking prices in USD. These are calculated from thousands of online listings daily from various watch boards and posts. Our APIs allow you to filter to get the average price for an entire brand or refine further to get prices for exact models or even specific reference numbers.
To get started simply sign up and use your API token in any of the available API endpoints documented below for instant access.
If you have any questions or concerns, feel free to contact us.
Authentication
As mentioned above, when you sign up for free you will find your API token on your dashboard. Simply add this to any of our API endpoints as a GET or POST parameter to gain access. Examples of how this is done can be found below.
API Endpoints
Lists
Brand List Available on: All plans
Endpoint
GET https://api.thewatchapi.com/v1/brand/list HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
Response Objects
name | description |
---|---|
data |
Array list of brands. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/brand/list?api_token=YOUR_API_TOKEN
Example Response
{
"data":[
"A. Lange & Söhne",
"Alpina",
"Andersen Genève",
"Andreas Strehler",
"Angelus",
"Angular Momentum",
...
"Zenith",
"Zeno-Watch Basel",
"ZentRa",
"Zeppelin",
"Zodiac",
"ZRC"
]
}
Model List Available on: All plans
Endpoint
GET https://api.thewatchapi.com/v1/model/list HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
brand |
true | Specify the brand to list their models. |
Response Objects
name | description |
---|---|
data |
Array list of models. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/model/list?brand=rolex&api_token=YOUR_API_TOKEN
Example Response
{
"data":[
"Rolex Air King",
"Rolex Air King Date",
"Rolex Cellini",
"Rolex Cellini Danaos",
"Rolex Cellini Date",
"Rolex Cellini Dual Time",
"Rolex Cellini Moonphase",
"Rolex Cellini Prince",
"Rolex Cellini Time",
"Rolex Chronograph",
"Rolex Datejust",
"Rolex Datejust 31",
"Rolex Datejust 36",
"Rolex Datejust 41",
"Rolex Datejust II",
...
]
}
Reference List Available on: All plans
Endpoint
GET https://api.thewatchapi.com/v1/reference/list HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
brand |
true | Specify the brand to list their reference numbers. |
Response Objects
name | description |
---|---|
data |
Array list of reference numbers. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/reference/list?brand=rolex&api_token=YOUR_API_TOKEN
Example Response
{
"data":[
"226570",
"14000M",
"126900",
"76080",
"1601",
"6609",
"15053",
"124060",
"116520",
"16233",
...
]
}
Search
Brand Search Available on: All plans
Endpoint
GET https://api.thewatchapi.com/v1/brand/search HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
search |
true | Refine brands with search criteria. |
Response Objects
name | description |
---|---|
meta > results |
Number of results returned. |
data |
Array list of brands. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/brand/search?search=rolex&api_token=YOUR_API_TOKEN
Example Response
{
"data":[
"Rolex"
]
}
Model Search HIGH USAGE Available on: All plans
Endpoint
GET https://api.thewatchapi.com/v1/model/search HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
search |
true | Refine data with search criteria. Use the search_attributes parameter to
specify which attributes to search. |
search_attributes |
false | Specify which attributes to apply the search parameter to (comma separated).
Available: brand,model,reference_number,description,case_material,movement
Default: model,description
|
brand |
false | Filter the data by brand (exact matches only). |
model |
false | Filter the data by model (exact matches only). |
reference_number |
false | Filter the data by reference_number (exact matches only). |
movement |
false | Filter the data by movement (exact matches only). |
case_material |
false | Filter the data by case material (exact matches only). |
case_diameter |
false | Filter the data by case diameter (exact matches only). |
Response Objects
name | description |
---|---|
meta > results |
Number of results returned. |
data > brand |
Brand of the watch. |
data > reference_number |
reference_number of the watch. |
data > model |
Model of the watch. |
data > movement |
Movement of the watch. |
data > year_of_production |
Years of production range. |
data > case_material |
Case material of the watch. |
data > case_diameter |
Case diameter of the watch. |
data > description |
Description of the watch. |
data > last_updated |
Last time the record was updated. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/model/search?search=rolex%20daytona&search_attributes=model&case_material=steel&api_token=YOUR_API_TOKEN
Example Response
{
"data":[
{
"brand":"Rolex",
"reference_number":"116520",
"model":"Rolex Daytona",
"movement":"Automatic",
"year_of_production":"1989 - 2018",
"case_material":"Steel",
"case_diameter":"40 mm",
"description":"Introducing the pinnacle of luxury and style - the Rolex Daytona reference number 116520. Meticulously designed and skillfully crafted, this breathtaking timepiece has established itself as the epitome of sophistication and excellence.
Inspired by the fast-paced world of motorsports, the Daytona line has consistently stood out for its sporty appeal and superior performance. The reference number 116520 takes that legacy to a whole new level with its elegant design and exceptional features.
Every aspect of this incredible timekeeping tool showcases Rolex's dedication to precision and quality. Each piece is meticulously handcrafted with the finest materials, ensuring that it surpasses the highest standards of watchmaking.
The case of the Daytona 116520 is made from a solid block of 904L steel which is known for its exceptional corrosion resistance and polishability. Its mirror-like finish and smooth edges make it both stylish and durable. The 40mm size fits comfortably on the wrist and exudes a sense of strength and masculinity.
But it is inside the case where the true magic of this timepiece lies. The heart of the Daytona is the iconic Calibre 4130 movement - a self-winding mechanical chronograph entirely developed and manufactured by Rolex. This revolutionary movement comprises about 290 parts, fewer than a standard chronograph, making it not only more reliable but also incredibly precise.
The black dial perfectly complements the steel material, featuring 3 sub-dials that display the functions of the watch - the small seconds at 6 o'clock, a 30-minute counter at 3 o'clock, and a 12-hour counter at 9 o'clock. The luminescent hands and hour markers make it easy to read the time even in the dark, making it a perfect companion for any adventurer.
The Daytona 116520 is not only a well-crafted timepiece but also a symbol of ultimate style. Its slick design, intricate details, and perfect functionality make it a statement piece for any formal or casual setting.
Besides impeccable functionality, this watch is also water-resistant up to 100 meters and comes with a scratch-resistant sapphire crystal, making it a perfect choice for any outdoor activity. What's more, the Daytona reference number 116520 also features a comfortable Oyster bracelet with an Oysterlock clasp for secure wearing.
In conclusion, Rolex Daytona reference number 116520 is the ultimate combination of sleek design, precision, and functionality. For those who desire nothing but the best in life, this watch is a must-have, and owning it adds an element of luxury to any sophisticated collection. Indulge in a legacy of excellence; own the legendary Rolex Daytona 116520 today.",
"last_updated":"2023-10-12 12:12:33"
},
{
"brand":"Rolex",
"reference_number":"116500LN",
"model":"Rolex Daytona",
"movement":"Automatic",
"year_of_production":"2010 - 2023",
"case_material":"Steel",
"case_diameter":"40 mm",
"description":"The Rolex Daytona reference number 116500LN is the pinnacle of precision timekeeping and ultimate luxury for watch enthusiasts. Crafted with exceptional attention to detail, this watch redefines elegance and sets new standards for chronographic instruments.
At first glance, the 116500LN leaves a lasting impression with its stunning minimalist design. The polished Oystersteel case with a black Cerachrom bezel exudes a sense of sophistication and accentuates the bold, sleek lines of the watch. Complemented by a scratch-resistant sapphire crystal and a Triplock winding crown, this timepiece is built to withstand the test of time.
The face of the watch is equally impressive, with a flawless black dial featuring contrasting white sub-dials. These sub-dials serve as a focal point for the chronograph functions, including a 30-minute counter, 12-hour counter, and a central second hand. All are designed with ultra-precise fine-tuned movements to ensure chronographic accuracy to the second.
The beating heart of this impressive timepiece is the caliber 4130 movement, which is entirely developed and manufactured by Rolex. With 44 jewel bearings and a power reserve of 72 hours, the movement provides optimal performance that far surpasses industry standards. It is also fitted with a shock-absorbing Syschron-II, making the watch exceptionally reliable in extreme conditions.
The functionality of the 116500LN extends beyond its precise timekeeping capabilities. The sturdy Oyster bracelet and Oyster safety clasp ensure a secure and comfortable fit for the wearer, even during the most active of lifestyles. The combination of strength, durability, and comfort is a testament to the fine craftsmanship of this iconic watch brand.
Not only is the Daytona reference number 116500LN a masterful instrument for accurate timekeeping, but also a visual masterpiece. The timeless design, combined with cutting-edge materials and functionality, make this watch a true work of art.
Whether gracing the wrist of a seasoned collector or adorning the arm of a trendsetter, the Rolex Daytona reference number 116500LN is a choice that speaks for itself. From intimate celebration to special events, this watch embodies a sense of refinement and prestige. With a Rolex Daytona 116500LN, you will join the ranks of distinguished individuals and immerse yourself in the prestige and reputation of this illustrious timepiece.",
"last_updated":"2023-10-12 12:29:54"
},
...
]
}
Reference Search Available on: All plans
Endpoint
GET https://api.thewatchapi.com/v1/reference/search HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
search |
true | Refine reference numbers with search criteria. |
Response Objects
name | description |
---|---|
meta > results |
Number of results returned. |
data |
Array list of brands. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/reference/search?search=116520&api_token=YOUR_API_TOKEN
Example Response
{
"data":[
{
"brand":"Rolex",
"reference_number":"116520"
}
]
}
Historical Prices
Brand Price History HIGH USAGE Available on: Standard plan and above
Endpoint
GET https://api.thewatchapi.com/v1/brand/price/history HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
brand |
true | Brand to get historical prices for. |
date_from |
false | Refine data by retrieving data after and including the specified date.
Default is the max allowed on your plan.
Format: Y-m-d
|
date_to |
false | Refine data by retrieving data before and including the specified date.
Default is the max allowed on your plan.
Format: Y-m-d
|
Response Objects
name | description |
---|---|
meta > brand |
Watch brand. |
data > date |
Date of the relative price. |
data > price |
Price on that day in USD. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/brand/price/history?brand=rolex&api_token=YOUR_API_TOKEN
Example Response
{
"meta":{
"brand":"Rolex"
},
"data":[
{
"date":"2023-10-13T00:00:00.000Z",
"price":20588.861509
},
{
"date":"2023-10-12T00:00:00.000Z",
"price":19965.662642
},
...
]
}
Model Prices History HIGH USAGE Available on: Standard plan and above
Endpoint
GET https://api.thewatchapi.com/v1/model/price/history HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
model |
true | Model to get historical prices for. |
date_from |
false | Refine data by retrieving data after and including the specified date.
Default is the max allowed on your plan.
Format: Y-m-d
|
date_to |
false | Refine data by retrieving data before and including the specified date.
Default is the max allowed on your plan.
Format: Y-m-d
|
Response Objects
name | description |
---|---|
meta > brand |
Watch brand. |
meta > model |
Watch model. |
data > date |
Date of the relative price. |
data > price |
Price on that day in USD. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/model/price/history?model=rolex%20daytona&api_token=YOUR_API_TOKEN
Example Response
{
"meta":{
"brand":"Rolex",
"model":"Rolex Daytona"
},
"data":[
{
"date":"2023-10-13T00:00:00.000Z",
"price":51427.676364
},
{
"date":"2023-10-12T00:00:00.000Z",
"price":50877.049091
},
...
]
}
Reference Price History Available on: Standard plan and above
Endpoint
GET https://api.thewatchapi.com/v1/reference/price/history HTTP/1.1
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
reference_number |
true | Reference number to get historical prices for. |
date_from |
false | Refine data by retrieving data after and including the specified date.
Default is the max allowed on your plan.
Format: Y-m-d
|
date_to |
false | Refine data by retrieving data before and including the specified date.
Default is the max allowed on your plan.
Format: Y-m-d
|
Response Objects
name | description |
---|---|
meta > brand |
Watch brand. |
meta > model |
Watch model. |
data > date |
Date of the relative price. |
data > price |
Price on that day in USD. |
Example Request (HTTP GET)
GET https://api.thewatchapi.com/v1/reference/price/history?reference_number=116520&api_token=YOUR_API_TOKEN
Example Response
{
"meta":{
"brand":"Rolex",
"reference_number":"116520"
},
"data":[
{
"date":"2023-10-13T00:00:00.000Z",
"price":24653.12
},
{
"date":"2023-10-12T00:00:00.000Z",
"price":24640.94
},
...
]
}
Errors
Errors
If your request was unsuccessful, you will receive a JSON formatted error. Below you will find the potential errors you may encounter when using the API.
Errors
error code | HTTP status | description |
---|---|---|
malformed_parameters |
400 |
Validation of parameters failed. The failed parameters are usually shown in the error message. |
too_many_results |
400 |
The number of results exceeds your plan allowance. The number of results is usually shown in the error message. You must refine your search criteria further. |
invalid_api_token |
401 |
Invalid API token. |
usage_limit_reached |
402 |
Usage limit of your plan has been reached. Usage limit and remaining requests can be found on the X-UsageLimit-Limit header. |
endpoint_access_restricted |
403 |
Access to the endpoint is not available on your current subscription plan. |
resource_not_found |
404 |
Resource could not be found. |
invalid_api_endpoint |
404 |
API route does not exist. |
rate_limit_reached |
429 |
Too many requests in the past 60 seconds. Rate limit and remaining requests can be found on the X-RateLimit-Limit header. |
server_error |
500 |
A server error occured. |
maintenance_mode |
503 |
The service is currently under maintenance. |
Example Error Response
{
"error": {
"code": "malformed_parameters",
"message": "The brand parameter(s) are incorrectly formatted."
}
}
Examples
Code Examples
See our prepared examples below to quickly get started implementing our API into your next project.
PHP
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.thewatchapi.com/v1/model/search?api_token=YOUR_API_TOKEN&search=rolex%20daytona&search_attributes=model%2Cdescription&case_material=steel',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Python
import http.client
conn = http.client.HTTPSConnection("api.thewatchapi.com")
payload = ''
headers = {}
conn.request("GET", "/v1/model/search?api_token=YOUR_API_TOKEN&search=rolex%20daytona&search_attributes=model%2Cdescription&case_material=steel", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Go
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.thewatchapi.com/v1/model/search?api_token=YOUR_API_TOKEN&search=rolex%20daytona&search_attributes=model%2Cdescription&case_material=steel"
method := "GET"
client := &http.Client {
}
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
JavaScript
var requestOptions = {
method: 'GET',
redirect: 'follow'
};
fetch("https://api.thewatchapi.com/v1/model/search?api_token=YOUR_API_TOKEN&search=rolex%20daytona&search_attributes=model%2Cdescription&case_material=steel", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
C#
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.thewatchapi.com/v1/model/search?api_token=YOUR_API_TOKEN&search=rolex%20daytona&search_attributes=model%2Cdescription&case_material=steel");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Java
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://api.thewatchapi.com/v1/model/search?api_token=YOUR_API_TOKEN&search=rolex%20daytona&search_attributes=model%2Cdescription&case_material=steel")
.method("GET", body)
.build();
Response response = client.newCall(request).execute();