# Bidsquare Auction Lot Scraper (`lulzasaur/bidsquare-scraper`) Actor

Scrape art, antiques & collectibles auction lots from Bidsquare. Per-lot data: title, low/high estimate, realized/current price (when public), currency, auction house, sale date, category, image and lot URL. Search by keyword and paginate all results.

- **URL**: https://apify.com/lulzasaur/bidsquare-scraper.md
- **Developed by:** [lulz bot](https://apify.com/lulzasaur) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Bidsquare Auction Lot Scraper

Scrape **art, antiques & collectibles** auction lots from [Bidsquare](https://www.bidsquare.com) — the online marketplace connecting bidders with respected auction houses. Search by keyword and export clean, structured lot data: titles, estimates, realized/current prices, auction house, sale date, category and images.

### What it does

- Searches Bidsquare for one or more keywords (e.g. `oil painting`, `Rolex`, `Tiffany lamp`).
- Paginates through all matching lots (or stops at your `maxResults` limit).
- Returns one record per lot with estimate range, publicly-shown price, auction house, image and canonical lot URL.
- Optionally visits each lot's detail page (`scrapeDetails`) to add description, hi-res image, canonical price/currency, sale close date and category from the page's schema.org data.

### Input

| Field | Type | Description |
|-------|------|-------------|
| `searchQueries` | array of strings | Keywords to search. Leave empty / use `""` to browse all lots. |
| `maxResults` | integer | Max lots per query. `0` = fetch everything via pagination. Default `100`. |
| `scrapeDetails` | boolean | Visit each lot page for extra fields (description, sale date, category, currency). Default `false`. |
| `proxyConfiguration` | object | Proxy settings. Defaults to Apify **Residential** proxy (recommended — the site is behind Cloudflare). |

#### Example input

```json
{
  "searchQueries": ["oil painting", "Tiffany lamp"],
  "maxResults": 100,
  "scrapeDetails": true,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}
```

### Output

Each dataset item looks like:

```json
{
  "itemId": "8343520",
  "eventId": "21098",
  "eventName": "ARTE CONTEMPORANEO EN OAXACA : TALLER IXRAEL MONTES Y DIVERSOS",
  "eventStatus": "past",
  "title": "IXRAEL MONTES, S/T(amarillo), mixta sobre cilindro, 45 x 9 cm., 2025",
  "lotUrl": "https://www.bidsquare.com/online-auctions/jp-auctions-mexico/...-8343520",
  "imageUrl": "https://s1.img.bidsquare.com/item/m/3349/33490949.png",
  "auctionHouse": "JP Auctions Mexico",
  "auctionHouseUrl": "https://www.bidsquare.com/auction-house/jp-auctions-mexico",
  "estimateLow": 30000,
  "estimateHigh": 35000,
  "estimateCurrency": "MXN$",
  "estimateDisplay": "MXN$30,000 - MXN$35,000",
  "priceDisplay": null,
  "priceAmount": null,
  "priceGated": true,
  "description": "IXRAEL MONTES, S/T(amarillo), mixta sobre cilindro... (scrapeDetails)",
  "priceCurrency": "MXN",
  "saleDate": "2025-10-30T21:00:00-04:00 EDT",
  "availability": "Discontinued",
  "category": "Paintings",
  "scrapedAt": "2026-07-03T00:00:00.000Z"
}
```

#### Field notes

- **Estimates** are always public. `estimateLow` / `estimateHigh` are numbers in the lot's native currency (`estimateCurrency`), with a human-readable `estimateDisplay`.
- **Realized / current prices**: Bidsquare only shows sold/hammer prices for some auction houses. When a price is public it appears in `priceDisplay` / `priceAmount`; when it's behind login, `priceGated` is `true` and the amounts are `null`.
- **Detail fields** (`description`, `saleDate`, `priceCurrency`, `availability`, `category`, `detailImageUrl`) are only populated when `scrapeDetails` is enabled.

### How it works

Bidsquare's search results are server-rendered, so the scraper reads structured lot cards directly from the search HTML (no browser needed) and, in detail mode, parses each lot page's schema.org `Product` JSON-LD. It runs behind a residential proxy with a browser fingerprint for reliability.

### Pricing

Pay per result — you're charged a small fixed fee per lot record returned, plus a tiny actor-start fee. No monthly subscription.

### Disclaimer

This scraper collects publicly available data for research and analysis. Respect Bidsquare's Terms of Service and applicable laws. Not affiliated with Bidsquare.

# Actor input Schema

## `searchQueries` (type: `array`):

Keywords to search Bidsquare for, e.g. \['oil painting', 'Rolex', 'Tiffany lamp']. Each query is scraped independently and paginated. Leave empty (or add one empty string) to browse all lots without a keyword filter.

## `maxResults` (type: `integer`):

Maximum number of lot records to return per query. Use 0 to fetch ALL matching lots via pagination (can be very large). Default 100.

## `scrapeDetails` (type: `boolean`):

If enabled, visit each lot's detail page to enrich records with description, hi-res image, canonical price/currency, sale close date and category (from schema.org JSON-LD). Slower — one extra request per lot.

## `proxyConfiguration` (type: `object`):

Proxy settings. Bidsquare is fronted by Cloudflare; a residential proxy is recommended for reliability and is used by default.

## Actor input object example

```json
{
  "searchQueries": [
    "painting"
  ],
  "maxResults": 100,
  "scrapeDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchQueries": [
        "painting"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("lulzasaur/bidsquare-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchQueries": ["painting"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("lulzasaur/bidsquare-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "painting"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call lulzasaur/bidsquare-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=lulzasaur/bidsquare-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/amjL0q9LMpLlN70zo/builds/PsWor1h7g0YAH7NmB/openapi.json