Documentation

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",
                  ...
               ]
            }
        
            
        

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"
               ]
            }
        
            
        

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"
                  },
                  ...
               ]
            }
        
            
        

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();