# eBay Listings Scraper (`joseolmedosotoaguirre/ebay-listings-scraper`) Actor

Scrape public eBay search listings for market research and price monitoring. Extracts itemId, title, price, currency, condition, shipping, seller (when public), and URL. Deduplicates by itemId.

- **URL**: https://apify.com/joseolmedosotoaguirre/ebay-listings-scraper.md
- **Developed by:** [jose olmedo soto aguirre](https://apify.com/joseolmedosotoaguirre) (community)
- **Categories:** E-commerce, Lead generation, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## eBay Listings Scraper

Apify Actor that scrapes **public** eBay search listings for legitimate **market research** and **price monitoring**. Supports `ebay.com`, `ebay.co.uk`, `ebay.de`, `ebay.com.au`, `ebay.ca`, `ebay.es`, `ebay.fr`, and `ebay.it`.

Built with **Crawlee + Playwright** (HTML parsed with **Cheerio**), concurrency 1, polite 1.5–3s delays, `itemId` deduplication. **Proxy is optional**; enable Apify **RESIDENTIAL** if you get blocked or empty results.

***

### What it does

1. Opens eBay search pages for your query on the selected marketplace
2. Extracts structured fields from public result cards (classic `li.s-item` and current `.s-card` markup)
3. Deduplicates by `itemId` and stops at `maxItems`
4. Writes a clean dataset for price tracking, comps, or competitive analysis

#### Output fields

| Field | Description |
|--------|-------------|
| `itemId` | eBay item / listing id |
| `title` | Listing title |
| `price` | Numeric price when shown (first value if range) |
| `currency` | Currency code as shown by eBay (`USD`, `COP`, `EUR`, `GBP`, …) — follows site localization / IP |
| `condition` | Condition text when public (e.g. Brand New, Open Box, Used) |
| `shipping` | Shipping / logistics snippet when public |
| `seller` | Seller username when shown publicly on the card |
| `url` | Canonical item URL |
| `query` | Search query used for the run |
| `marketplace` | Marketplace domain |
| `scrapedAt` | ISO timestamp |

***

### Input

| Field | Required | Default | Description |
|--------|----------|---------|-------------|
| `query` | ✅ | — | Search term, e.g. `mechanical keyboard` |
| `marketplace` | | `ebay.com` | eBay site domain |
| `maxItems` | | `20` | Max unique listings (cap 200) |
| `maxPages` | | `1` | Max search pages (cap 10) |
| `proxyConfiguration` | | off | Optional; use Apify Proxy + **RESIDENTIAL** if blocked |

#### Example input

```json
{
  "query": "mechanical keyboard",
  "marketplace": "ebay.com",
  "maxItems": 8,
  "maxPages": 1,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

If blocked, switch to:

```json
{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  }
}
```

***

### Example output (real run)

Local verification (2026-07-29): query `mechanical keyboard`, marketplace `ebay.com`, `maxItems: 8`. Extracted **8** unique listings (prices localized to **COP** for this IP; USD/EUR appear when eBay serves that locale). Full dump: `STORAGE_SAMPLES.json`.

```json
[
  {
    "itemId": "146984332653",
    "title": "GK61 Mechanical Gaming RGB LED Keyboard - White, Gaetron Optical Red Switches",
    "price": 63954.01,
    "currency": "COP",
    "condition": "Brand New",
    "shipping": "+COP $55,635.83 shipping",
    "seller": "cidhighwind",
    "url": "https://www.ebay.com/itm/146984332653",
    "query": "mechanical keyboard",
    "marketplace": "ebay.com",
    "scrapedAt": "2026-07-29T05:12:22.810Z"
  },
  {
    "itemId": "407103034170",
    "title": "AULA F99 Wireless Mechanical Keyboard RGB Hot-Swap Full Size White/Gray New",
    "price": 143968.5,
    "currency": "COP",
    "condition": "Open Box",
    "shipping": "+COP $98,410.47 shipping",
    "seller": "brookiedunlimited",
    "url": "https://www.ebay.com/itm/407103034170",
    "query": "mechanical keyboard",
    "marketplace": "ebay.com",
    "scrapedAt": "2026-07-29T05:12:22.811Z"
  },
  {
    "itemId": "800421568031",
    "title": "New Listing Ro75 Beige Creamy Aluminum Mechanical Keyboard Wired RGB Backlit",
    "price": 319930,
    "currency": "COP",
    "condition": "Open Box",
    "shipping": "+COP $159,133.18 shipping",
    "seller": "strawberryjam1986",
    "url": "https://www.ebay.com/itm/800421568031",
    "query": "mechanical keyboard",
    "marketplace": "ebay.com",
    "scrapedAt": "2026-07-29T05:12:22.812Z"
  }
]
```

***

### Suggested pricing

| Plan | Price | Notes |
|------|-------|--------|
| Pay per result | **$1–2 / 1,000 results** | Occasional comps / market checks |
| Rental | **$19–29 / month** | Recurring price monitoring |

Residential proxy compute (if used) is billed separately by Apify.

***

### Responsible use / Terms of Service

- Use only for **legitimate market research, price monitoring, and competitive analysis** on **publicly available** search result data.
- Respect [eBay User Agreement](https://www.ebay.com/help/policies/member-behaviour-policies/user-agreement?id=4259), eBay robots / crawling policies, and applicable local laws.
- Do **not** use this Actor to overwhelm eBay infrastructure, bypass authentication for private data, scrape personal information beyond what is publicly shown on search cards, or violate eBay’s anti-bot rules at abusive scale.
- Keep concurrency low (default 1), use polite delays, and enable RESIDENTIAL proxies only when needed.
- You are responsible for compliance with eBay ToS and your jurisdiction’s data / fair-use rules.

***

### Tips for reliable runs

1. Start with `maxItems` ≤ 20 and `maxPages` = 1.
2. If you get 0 items or challenges, enable **Apify Proxy → RESIDENTIAL** and match proxy country to the marketplace.
3. Displayed **currency** follows eBay’s localization for the request IP / site — not always the marketplace’s home currency.
4. Avoid aggressive schedules; space recurring runs by minutes, not seconds.
5. Seller is included only when eBay shows it publicly on the search card.

***

### Local development

```bash
export APIFY_TOKEN=$(grep '^APIFY_TOKEN=' ../.env | cut -d= -f2-)
npm install --registry https://registry.npmjs.org/
apify run
```

On Apify Cloud:

```bash
apify push -f
apify call joseolmedosotoaguirre/ebay-listings-scraper --input '{...}'
```

**Actor:** https://console.apify.com/actors/pG4rCWzw33sl4FWZi\
**Username slug:** `joseolmedosotoaguirre/ebay-listings-scraper`

# Actor input Schema

## `query` (type: `string`):

eBay search keywords (e.g. "mechanical keyboard", "vintage camera").

## `marketplace` (type: `string`):

eBay site domain. Default ebay.com (US).

## `maxItems` (type: `integer`):

Maximum unique listings to save (deduplicated by itemId).

## `maxPages` (type: `integer`):

Maximum eBay search result pages to crawl.

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

Optional. Enable Apify Proxy with RESIDENTIAL group if you get blocked or empty results.

## Actor input object example

```json
{
  "query": "mechanical keyboard",
  "marketplace": "ebay.com",
  "maxItems": 5,
  "maxPages": 1,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

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

Items pushed to the default dataset.

# 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 = {
    "query": "mechanical keyboard",
    "maxItems": 5,
    "maxPages": 1,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("joseolmedosotoaguirre/ebay-listings-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 = {
    "query": "mechanical keyboard",
    "maxItems": 5,
    "maxPages": 1,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("joseolmedosotoaguirre/ebay-listings-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 '{
  "query": "mechanical keyboard",
  "maxItems": 5,
  "maxPages": 1,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call joseolmedosotoaguirre/ebay-listings-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/pG4rCWzw33sl4FWZi/builds/8n0hb9GFgFuJdoG52/openapi.json