Jomashop APIjomashop.com ↗
Access Jomashop's watch and luxury goods catalog via API. Browse categories, search products, fetch reviews, and explore brands with 9 endpoints.
What is the Jomashop API?
The Jomashop API gives developers structured access to Jomashop's watch and luxury goods catalog across 9 endpoints. Use search_products to query by keyword and get back product IDs, brand names, current and discounted prices, and image URLs. Other endpoints cover category browsing, brand filtering, sale listings, new arrivals, detailed product specs, and Yotpo-sourced customer reviews — all returned as consistent, paginated JSON.
curl -X GET 'https://api.parse.bot/scraper/406cfd10-b189-4fe9-a006-9e79e55c4856/get_category_products?page=1&sort_by=bestsellers&page_size=60&category_id=871' \ -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 jomashop-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.jomashop_api import Jomashop, Sort
jomashop = Jomashop()
# Browse watches sorted by most viewed
watches = jomashop.category(id=871)
for product in watches.products(sort_by=Sort.MOST_VIEWED, limit=5):
print(product.name, product.sku, product.stock_status)
# Get full details for the first product
detail = product.details()
print(detail.name, detail.brand_url, detail.stock_status)
# Read customer reviews for that product
for review in detail.reviews.list(limit=3):
print(review.title, review.score, review.created_at)
# Search across the catalog
for result in jomashop.searchresults.search(query="Omega Seamaster", limit=5):
print(result.name, result.brand, result.price)
# Browse a specific brand's offerings
omega = jomashop.brand(name="Omega")
for item in omega.products(limit=3):
print(item.name, item.msrp)
Browse products by category with pagination, sorting, and filtering. Returns category metadata with a flat items array of product listings, total_count, current_page, and total_pages.
| Param | Type | Description |
|---|---|---|
| page | integer | Current page number. |
| sort_by | string | Sort criteria. |
| page_size | integer | Number of products per page. |
| min_rating | number | Minimum customer rating filter (e.g. 4.0). |
| category_id | integer | Category ID (e.g. 871 for Watches, 10709 for Sale). |
{
"type": "object",
"fields": {
"id": "integer category ID",
"name": "string category name",
"items": "array of product listing objects",
"total_count": "integer total products in category",
"total_pages": "integer total pages available",
"current_page": "integer current page number"
},
"sample": {
"data": {
"id": 871,
"name": "Watches",
"items": [
{
"id": 322721,
"sku": "TIST1224071105100",
"msrp": 815,
"name": "Tissot Carson Automatic Black Dial Men's Watch T122.407.11.051.00",
"url_key": "tissot-carson-watch-t1224071105100",
"stock_status": "IN_STOCK"
}
],
"total_count": 50418,
"total_pages": 841,
"current_page": 1
},
"status": "success"
}
}About the Jomashop API
Product Discovery
search_products accepts a query string (e.g. 'Rolex' or 'luxury automatic watch') and returns a data array of product objects, each containing id, name, brand, url, image, price, price_discounted, and a payload field that carries the Yotpo domain_key needed for get_product_reviews. The approximate_hits integer and has_more boolean let you implement pagination via skip and limit.
get_category_products accepts a category_id (e.g. 871 for Watches, 10709 for Sale), plus page, page_size, sort_by, and min_rating filters. It returns the category id and name, a flat items array of product listings, total_count, total_pages, and current_page. get_sale_products and get_new_arrivals are convenience wrappers around the same structure — the latter sorts by news_from_date so the freshest additions surface first.
Brand and Category Navigation
get_watch_brands returns a flat list of brand objects with a name field. Pass any of those names as the brand_name parameter to get_brand_products, optionally combined with a category_id, to scope results to a single brand within a category. get_navigation_menu returns the full site navigation tree as an items array with id, name, url_key, menu_content, and children_count per node — useful for discovering valid category IDs to pass into other endpoints.
Product Detail and Reviews
get_product_details takes a url_key (the slug from the product page URL) and returns a full record: id, sku, name, image, brand_url, description.html, moredetails (with gender_label and more_details_text), and stock_status. If the slug is invalid, the response includes a stale_input field with kind: input_not_found. Customer reviews come from get_product_reviews, which requires a product_id string and returns a reviews array (each with score, content, title, and user), a bottomline object with total_review, average_score, and star_distribution, plus pagination metadata.
The Jomashop API is a managed, monitored endpoint for jomashop.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when jomashop.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 jomashop.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 watch price comparison tool using
search_productsto pullpriceandprice_discountedfields across multiple brands. - Track new inventory additions by polling
get_new_arrivalswith a specificcategory_idand comparing returneditemsover time. - Aggregate customer sentiment by fetching
bottomline.average_scoreandstar_distributionfromget_product_reviewsacross a brand's catalog. - Populate a brand directory by calling
get_watch_brandsand then paginating throughget_brand_productsfor each brand name. - Sync a sale feed by regularly calling
get_sale_productsand comparingpriceagainstprice_discountedin the returneditemsarray. - Index Jomashop's category hierarchy for site search by extracting
id,name, andurl_keyfromget_navigation_menu. - Display enriched product pages by combining
get_product_detailsfields (description.html,stock_status,sku) with review stats fromget_product_reviews.
| 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 Jomashop have an official developer API?+
How do I get the product ID needed for `get_product_reviews`?+
get_product_reviews expects the Yotpo domain_key as its product_id parameter. You can find this value in the payload.metad field returned by search_products for any matching product.Does `get_product_details` return pricing information?+
get_product_details returns product metadata including sku, name, description, stock_status, and moredetails, but does not currently include price fields in its response. Pricing (price and price_discounted) is available from search_products and the items arrays returned by category and brand endpoints. You can fork this API on Parse and revise it to add a price field to the product detail response.Can I filter `get_category_products` by price range?+
min_rating and sorting via sort_by, but does not expose a price range filter parameter. The items array does include pricing fields, so client-side filtering is possible. You can fork the API on Parse and revise it to add min/max price filter parameters.Is `stock_status` in `get_product_details` real-time?+
stock_status field reflects availability as returned at the time of the API call. Jomashop inventory can change rapidly for in-demand items, so there may be a lag between actual stock changes and what the field reports. Treat it as indicative rather than a guaranteed real-time inventory signal.