Bonhams APIbonhams.com ↗
Access Bonhams auction listings, lot details, price estimates, hammer prices, and past results across fine art, collectibles, and cars via a structured API.
What is the Bonhams API?
The Bonhams API exposes 7 endpoints covering upcoming and past auctions, individual lot details, and full-text lot search across all Bonhams brands including Skinner, Bukowskis, and Cornette. get_auction_lots returns paginated lot listings with price estimates and catalog descriptions for any auction ID, while search_lots lets you query across all lots by keyword and filter by status — returning fields like estimateLow, estimateHigh, hammerPrice, and catalogDesc.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/c7a17c04-9385-4b8d-8a34-3cd85fb4c041/get_upcoming_auctions' \ -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 bonhams-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.
"""
Bonhams Auction API – Browse auctions, search lots, and explore departments.
"""
from parse_apis.bonhams_api import Bonhams, Auction, Lot, DepartmentFacet, LotStatus
client = Bonhams()
# List upcoming auctions
for auction in client.auctions.list_upcoming(limit=5):
print(auction.auction_title, auction.id, auction.auction_type)
# Construct an auction by id and browse its lots
target = client.auction(id="32176")
for lot in target.lots.list(limit=3):
print(lot.title, lot.lot_unique_id, lot.status)
# Fetch full details for one lot
full_lot = client.lots.get(lot_unique_id="6147087")
print(full_lot.title, full_lot.catalog_desc, full_lot.lot_unique_id)
# Search for watches in upcoming auctions using the LotStatus enum
for result in client.lots.search(query="watch", status=LotStatus.UPCOMING, limit=5):
print(result.title, result.price.estimate_low, result.price.estimate_high)
# List departments
for dept in client.departmentfacets.list(limit=10):
print(dept.value, dept.count, dept.highlighted)
# Past auction results
for past in client.auctions.list_past(limit=3):
print(past.auction_title, past.auction_status, past.venue.name)
Returns upcoming auctions sorted by start date ascending. Each auction includes title, date range, venue, department list, and total lot count. Covers all Bonhams brands (Bonhams, Skinner, Bukowskis, Cornette). Paginates as a single page of up to 250 auctions.
No input parameters required.
{
"type": "object",
"fields": {
"total": "integer total number of upcoming auctions",
"auctions": "array of auction objects with id, auctionTitle, dates, venue, lots.total, departments, categories, currency, region, etc."
},
"sample": {
"data": {
"total": 147,
"auctions": [
{
"id": "32176",
"lots": {
"total": 228
},
"slug": "diane-keaton-chapters-of-an-edited-life",
"brand": "bonhams",
"dates": {
"end": {
"datetime": "2026-06-11T19:00:00+00:00"
},
"start": {
"datetime": "2026-05-04T19:00:00+00:00"
}
},
"venue": {
"code": "ONLA",
"name": "Online, Los Angeles"
},
"region": {
"code": "AMERICAS",
"name": "Americas"
},
"currency": {
"iso_code": "USD",
"bonhams_code": "US$"
},
"auctionType": "ONLINE",
"departments": [
{
"code": "COL-ENT",
"name": "Popular Culture"
}
],
"description": "<p>Cover and banner photography...</p>",
"auctionTitle": "Diane Keaton: Chapters of an Edited Life",
"auctionStatus": "READY"
}
]
},
"status": "success"
}
}About the Bonhams API
Auction Discovery and Results
get_upcoming_auctions returns up to 250 upcoming sales sorted by start date, each with fields including auctionTitle, dates, venue, departments, lots.total, and currency. The corresponding get_auction_results endpoint returns the same shape for completed auctions, sorted by end date descending — useful for building historical result archives or price tracking tools. Both endpoints cover all Bonhams brands. get_auction_details accepts an auction_id and returns fuller per-sale metadata: an HTML description, bidding configuration, consignment date details, and the full departments array.
Lot-Level Data
get_auction_lots accepts an auction_id plus optional page and per_page parameters, returning lots sorted by lot number with fields for title, lotNo, price (including estimateLow, estimateHigh, hammerPrice, startingBidAmount, and currency), image, status, and catalogDesc. For deeper detail on any individual lot, get_lot_details accepts a lotUniqueId and adds an extra_details object containing live-bidding widget data such as bid count and current bid when available.
Search and Department Filtering
search_lots performs full-text search against lot titles and catalog descriptions across the entire catalog. Pass a query string and optionally set status to 'upcoming' or 'past' to restrict results. Results are paginated and sorted by relevance. get_departments returns the current list of Bonhams department names with auction counts derived from active auction facets — useful for building category filters or department-level dashboards without iterating through every auction.
The Bonhams API is a managed, monitored endpoint for bonhams.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when bonhams.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 bonhams.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?+
- Track hammer prices and estimate accuracy for a specific collecting category using
search_lotswith status'past' - Build a calendar of upcoming Bonhams sales with venue and department breakdown from
get_upcoming_auctions - Display a full catalog browser for a single auction using
get_auction_lotswith pagination - Power a lot-level detail page including images and HTML catalog notes via
get_lot_details - Monitor live bidding data and current bid amounts through the
extra_detailsfield inget_lot_details - Generate department-level sale statistics by combining
get_departmentscounts with filtered auction results - Aggregate past auction results across Bonhams brands (Skinner, Bukowskis, Cornette) into a unified price database
| 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 Bonhams offer an official public developer API?+
What does `search_lots` return and how is filtering controlled?+
search_lots matches the query string against lot titles and catalog descriptions across all auctions. The optional status parameter accepts 'upcoming' for lots in active or new auctions, or 'past' for sold and unsold lots. Results include title, price fields (estimateLow, estimateHigh, hammerPrice), catalogDesc, and the associated auctionTitle. Pagination is controlled with page and per_page.Are sale totals or buyer's premium data included in the auction or lot responses?+
hammerPrice, estimateLow, estimateHigh, and startingBidAmount, but aggregate sale totals and buyer's premium calculations are not exposed. You can fork this API on Parse and revise it to add a derived endpoint that computes sale totals from hammer prices across lots.How much auction history do the past results cover?+
get_auction_results returns up to 250 completed auctions in a single response sorted by end date descending. The endpoint does not support date-range filtering, so coverage depth depends on how many past auctions Bonhams surfaces in their catalog at the time of the call. For older historical results beyond the returned set, you can fork the API on Parse and revise it to add date-based pagination or archival filtering.Is provenance, condition report, or literature citation data available for lots?+
catalogDesc field in get_lot_details and get_auction_lots contains the HTML catalog description, which may include this information inline as formatted text. You can fork the API on Parse and revise it to parse and extract those sub-sections from the HTML into structured fields.