Holts APIholts.com ↗
Access Holts.com cigar products, brand listings, customer reviews, and staff editorial reviews via 5 structured endpoints. Search, browse, and retrieve ratings.
What is the Holts API?
The Holts.com API provides structured access to the full Holts Cigar Co. catalog across 5 endpoints, covering keyword search, brand listings, product details, paginated customer reviews, and editorial staff reviews. The get_staff_review endpoint returns a numeric score out of 100, full HTML review body, author profile fields, and a direct URL to the review page on holts.com — data not easily extracted through manual browsing at scale.
curl -X GET 'https://api.parse.bot/scraper/bfbba235-bb92-44cf-bc25-b0c351fd6209/search_cigars?query=montecristo' \ -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 holts-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.
"""Walkthrough: Holts Cigar Co. SDK — browse brands, search products, read reviews."""
from parse_apis.holts_cigar_co._api import Holts, ReviewSort, SortDirection, BrandNotFound
client = Holts()
# Search for cigar products by keyword; limit= caps total items fetched.
for product in client.brands.search(query="montecristo", limit=3):
print(product.name, product.price_range, product.rating)
# List all brands, take the first one, then drill into its sub-resources.
brand = client.brands.list(limit=1).first()
if brand:
# Get product variants for this brand
for bp in brand.products.list(limit=3):
print(bp.name, bp.price, bp.size)
# Read customer reviews sorted by rating (descending)
for review in brand.reviews.list(sort=ReviewSort.RATING_QUALITY, direction=SortDirection.DESC, limit=3):
print(review.nickname, review.title, review.rating_quality, review.city)
# Get the staff review for this brand
try:
staff = brand.staff_review.get()
print(staff.title, staff.score, staff.author.first_name)
except BrandNotFound as exc:
print(f"No staff review found: {exc}")
# Fetch a specific brand by URL and inspect its details
detail = client.brands.get(url="https://www.holts.com/cigars/all-cigar-brands/montecristo-white.html")
print(detail.name, detail.url)
print("exercised: brands.search / brands.list / brands.get / products.list / reviews.list / staff_review.get")
Full-text keyword search across cigar product lines and accessories. Returns matching products with name, price range, rating, review count, and image. Results are not paginated; a single page of matches is returned.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword (e.g. 'montecristo', 'romeo', 'rocky patel'). |
{
"type": "object",
"fields": {
"query": "string — the search term used",
"products": "array of product objects with name, url, price_range, review_count, rating, and image_url"
},
"sample": {
"data": {
"query": "montecristo",
"products": [
{
"url": "https://www.holts.com/cigars/all-cigar-brands/montecristo.html",
"name": "Montecristo",
"rating": null,
"image_url": "https://www.holts.com/media//categoryimage//thumb/135x135/m/o/montecristo-robusto-larga_13.png",
"price_range": "$2.91-$29.87",
"review_count": 0
}
]
},
"status": "success"
}
}About the Holts API
Search and Brand Discovery
The search_cigars endpoint accepts a query string — such as 'montecristo' or 'rocky patel' — and returns a flat list of matching products, each with name, url, price_range, rating, review_count, and image_url. Results are returned as a single page with no pagination. The get_all_brands endpoint requires no inputs and returns a complete brand directory: a count integer and an array of {name, url} objects covering every brand listed on holts.com.
Product Detail and ID Extraction
get_brand_products takes the full URL of a brand page and returns the brand_name, a products array with name, price, and optional size dimensions, plus two IDs critical for downstream calls: category_id and product_line_id. These IDs are the required inputs for the review endpoints, so get_brand_products effectively acts as a lookup step before fetching reviews.
Customer and Staff Reviews
get_product_reviews uses the category_id from get_brand_products to fetch paginated customer reviews — up to 10 per page. Each review object includes nickname, title, detail, rating_quality, created_at, city, state, and a verified flag. The response also exposes total_pages, current_page, visible_pages, and total_individual_reviews to support full pagination loops. Sort order is controllable via optional sort and direction parameters.
get_staff_review uses product_line_id and returns the Holts editorial perspective: a score string out of 100, body in HTML, date, title, and an author object with first_name, last_name, cigar_preference, favorite_cigar, portrait, and a url linking to the author's profile on holts.com.
The Holts API is a managed, monitored endpoint for holts.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when holts.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 holts.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 cigar comparison tool that surfaces staff scores and customer ratings side-by-side using
get_staff_reviewandget_product_reviews. - Aggregate price ranges across an entire brand lineup by iterating
get_brand_productsover URLs fromget_all_brands. - Track review volume trends over time using
total_individual_reviewsfrom paginatedget_product_reviewscalls. - Populate a cigar recommendation engine using
rating,review_count, andprice_rangefromsearch_cigars. - Build an author-centric review archive by grouping staff reviews by
author.idorauthor.urlacross multiple product lines. - Monitor new brand additions to the Holts catalog by periodically diffing
get_all_brandsoutput against a stored snapshot. - Filter high-scoring cigars within a budget by combining
get_brand_productsprices withget_staff_reviewscores.
| 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 Holts.com have an official developer API?+
What does get_product_reviews return, and can I sort results?+
nickname, title, detail, rating_quality, created_at, city, state, and a verified boolean. The endpoint accepts optional sort and direction parameters to control ordering. Pagination is supported via the page parameter; total_pages and total_individual_reviews are returned so you can loop through all results.Does search_cigars support pagination or filtering by price or rating?+
search_cigars returns a single page of results for a given query string. Filtering by price range or minimum rating is not a built-in parameter; the full result set is returned and any filtering would need to happen client-side. You can fork this API on Parse and revise it to add paginated or filtered search behavior.Is individual product-level review data available, or only brand/category-level?+
category_id from get_brand_products. There is no current endpoint that scopes reviews to a single SKU within a category. You can fork this API on Parse and revise it to add a product-specific review endpoint if finer granularity is needed.