> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search by Image
> Search eBay with a photo instead of keywords, using eBay's own visual search.
Search active listings **by image**. This is what the camera icon in eBay's own
search bar does: the picture is uploaded to eBay, eBay answers with a handle for
it, and that handle is searched like a keyword.
What comes back is ordinary listings, in exactly the same shape as
[`/v1/ebay/search`](/api-reference/endpoint/ebay/search), with `query` set to
`null`. Every filter below behaves the way it does there.
**Credits:** 10 — twice a keyword search, because each call is two round trips
to eBay: one to upload the image, one to fetch the results.
## Body Parameters
Send exactly one of `image_url` or `image_base64`. Sending both, or neither, is
a `422`.
Public http(s) URL of the image to search with. We download it for you.
The URL is fetched through the same egress-isolated path that serves the Web
Scraping API, so private addresses, cloud metadata endpoints and non-HTTP
schemes are refused.
The image itself, base64-encoded — use this when the picture is on your own
disk and has no public URL.
A bare base64 payload and a `data:image/jpeg;base64,...` URL are both
accepted, so you can paste one straight out of a browser. JPEG and PNG are
verified; the decoded image must be at most **10 MB**.
eBay marketplace domain TLD or alias. See
[`/v1/ebay/markets`](/api-reference/endpoint/ebay/list-markets) for all
supported values.
Examples: `com`, `co.uk`, `de`, `fr`, `com.au`
Restrict results to an eBay category id. Use
[`/v1/ebay/categories`](/api-reference/endpoint/ebay/list-categories) to look
up ids.
Page number for paginated results. Range: `1` - `1000`.
Use `pagination.has_more` to know when to stop.
Results per page. Clamped to one of `60`, `120`, or `240`.
Item condition filter.
| Value | Description |
| ------------- | ---------------------------------------- |
| `new` | Brand new |
| `open_box` | New (other) / open box |
| `refurbished` | Refurbished (any grade) |
| `used` | Pre-owned |
| `for_parts` | For parts or not working |
| `graded` | Trading cards: slabbed (PSA / BGS / CGC) |
| `ungraded` | Trading cards: raw |
Buying format filter: `auction`, `buy_it_now` or `best_offer`.
Minimum price, in the marketplace's own currency.
Maximum price, in the marketplace's own currency.
Only return listings with free shipping.
Item location. `domestic` keeps only items located in that marketplace's own
country; `worldwide` widens to every country.
Filter by the item's Language aspect: `english`, `japanese`, `chinese` or
`korean`. Resolved to each marketplace's own localized aspect name, so one
value works on all 18.
## There is no `sort_by`
eBay ignores sorting on a visual results page — asking for
`price_low_to_high` returns the same first row as best match. Rather than accept
a parameter that quietly does nothing, this endpoint does not have one.
To order by price, use `min_price` / `max_price` to narrow the band and sort the
returned rows yourself.
## Errors
A picture eBay cannot read is an error, never an empty result list — so a bad
upload is always distinguishable from a genuine no-match.
| Status | Meaning |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `400` `invalid_image` | The bytes are not a readable image, the image is over 10 MB, `image_url` did not return an image, or the URL was refused. |
| `422` | Both `image_url` and `image_base64` were sent, or neither was. |
| `422` `blocking_page_detected` | eBay refused the request. Retry. |
| `503` `upstream_unavailable` | Our own fetch layer timed out before eBay answered. Retry; you are not charged. |
## Examples
```bash By image URL theme={null}
curl -X POST https://scrapebadger.com/v1/ebay/search/by-image \
-H "X-API-Key: $SCRAPEBADGER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image_url": "https://example.com/sneaker.jpg", "domain": "com"}'
```
```bash By upload theme={null}
curl -X POST https://scrapebadger.com/v1/ebay/search/by-image \
-H "X-API-Key: $SCRAPEBADGER_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"image_base64\": \"$(base64 -w0 sneaker.jpg)\", \"domain\": \"com\"}"
```
```python Python theme={null}
from scrapebadger import ScrapeBadger
async with ScrapeBadger(api_key="YOUR_KEY") as client:
results = await client.ebay.search.search_by_image(
image_url="https://example.com/sneaker.jpg",
domain="com",
)
for item in results.results:
print(item.title, item.price.value, item.price.currency)
```
```typescript Node theme={null}
import { ScrapeBadger } from 'scrapebadger'
const client = new ScrapeBadger({ apiKey: 'YOUR_KEY' })
const results = await client.ebay.search.searchByImage({
imageUrl: 'https://example.com/sneaker.jpg',
domain: 'com',
})
```
```bash CLI theme={null}
scrapebadger ebay search-by-image --image ./sneaker.jpg --domain com
```
## Response
Identical to [`/v1/ebay/search`](/api-reference/endpoint/ebay/search): `results`,
`facets`, `pagination`, `domain` and the scrape timestamps. `query` is `null`,
since the search was made from a picture rather than words.
## OpenAPI
````yaml POST /v1/ebay/search/by-image
openapi: 3.1.0
info:
title: ScrapeBadger eBay API
version: 1.0.0
description: >-
eBay marketplace scraping API for searching active and completed (sold)
listings, fetching item details, reviews, sellers, seller listings and
feedback, category browsing, autocomplete, and reference data across 18
marketplaces.
servers:
- url: https://scrapebadger.com
description: Production
security:
- apiKeyAuth: []
paths:
/v1/ebay/search/by-image:
post:
tags:
- eBay Search
summary: Search by Image
description: >-
Search active listings by image, running eBay's own visual search — the
camera icon in eBay's search bar. Returns the same shape as
`/v1/ebay/search`, with `query` set to null. There is deliberately no
`sort_by`: eBay ignores sorting on a visual results page. Costs 10
credits (two round trips to eBay); failed requests are free.
operationId: searchEbayByImage
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
image_url:
type: string
format: uri
description: >-
Public http(s) URL of the image to search with. Exactly one
of `image_url` or `image_base64` is required.
image_base64:
type: string
description: >-
The image itself, base64-encoded. A bare payload or a
`data:image/jpeg;base64,...` URL are both accepted. JPEG and
PNG are verified; the decoded image must be at most 10 MB.
domain:
type: string
default: com
description: >-
eBay marketplace domain TLD or alias (com, co.uk, de, fr,
...).
category_id:
type: string
description: Restrict results to a category id.
page:
type: integer
default: 1
minimum: 1
maximum: 1000
description: Page number for paginated results.
per_page:
type: integer
minimum: 1
maximum: 240
description: Results per page. Clamped to 60, 120 or 240.
condition:
type: string
enum:
- new
- open_box
- refurbished
- used
- for_parts
- graded
- ungraded
description: >-
Item condition. `graded` / `ungraded` are eBay's
trading-card conditions — slabbed (PSA/BGS/CGC) vs raw — so
a card can be priced separately from its slabs.
buying_format:
type: string
enum:
- auction
- buy_it_now
- best_offer
description: Buying format filter.
min_price:
type: number
minimum: 0
description: Minimum price filter in the marketplace's local currency.
max_price:
type: number
minimum: 0
description: Maximum price filter in the marketplace's local currency.
free_shipping:
type: boolean
default: false
description: Only return listings with free shipping.
location:
type: string
enum:
- domestic
- worldwide
description: >-
Item location. `domestic` returns only items located in this
marketplace's own country (`domain=fr` → France only);
`worldwide` widens to every country. Foreign listings are
priced in the marketplace's currency after eBay CONVERTS
them, so `domestic` is also how you get untouched native
sale prices.
language:
type: string
enum:
- english
- japanese
- chinese
- korean
description: >-
Filter by the item's Language aspect, resolved to each
marketplace's own localized aspect name. Measured on
ebay.com books: 11.0M results unfiltered, 7.8M `english`,
99k `japanese`.
examples:
byUrl:
summary: By image URL
value:
image_url: https://example.com/sneaker.jpg
domain: com
byUpload:
summary: By base64 upload
value:
image_base64: /9j/4AAQSkZJRgABAQ...
domain: com
per_page: 120
responses:
'200':
description: Listings matching the image
content:
application/json:
schema:
type: object
properties:
query:
type:
- string
- 'null'
domain:
type: string
category_id:
type:
- string
- 'null'
sold:
type: boolean
results:
type: array
items:
type: object
properties:
position:
type: integer
item_id:
type:
- string
- 'null'
product_id:
type:
- string
- 'null'
title:
type:
- string
- 'null'
url:
type:
- string
- 'null'
image:
type:
- string
- 'null'
price:
type: object
properties:
value:
type:
- number
- 'null'
currency:
type:
- string
- 'null'
symbol:
type:
- string
- 'null'
raw:
type:
- string
- 'null'
original_price:
type: object
properties:
value:
type:
- number
- 'null'
currency:
type:
- string
- 'null'
symbol:
type:
- string
- 'null'
raw:
type:
- string
- 'null'
discount_percent:
type:
- number
- 'null'
currency:
type:
- string
- 'null'
condition:
type:
- string
- 'null'
brand:
type:
- string
- 'null'
buying_format:
type:
- string
- 'null'
is_auction:
type: boolean
bids:
type:
- integer
- 'null'
time_left:
type:
- string
- 'null'
current_bid:
type:
- object
- 'null'
description: >-
Current high bid for auction listings; mirrors
`price`. Null for non-auction (fixed-price)
listings.
properties:
value:
type:
- number
- 'null'
currency:
type:
- string
- 'null'
symbol:
type:
- string
- 'null'
raw:
type:
- string
- 'null'
shipping:
type:
- string
- 'null'
shipping_cost:
type: object
properties:
value:
type:
- number
- 'null'
currency:
type:
- string
- 'null'
symbol:
type:
- string
- 'null'
raw:
type:
- string
- 'null'
free_shipping:
type:
- boolean
- 'null'
location:
type:
- string
- 'null'
returns:
type:
- string
- 'null'
sold_count:
type:
- integer
- 'null'
sold_date:
type:
- string
- 'null'
description: >-
Sale date text as rendered by eBay on the sold card,
e.g. "2 Jul 2026". Localized on non-English
marketplaces (e.g. "Verkauft 5. Okt. 2024"). Null on
active listings.
examples:
- 2 Jul 2026
sold_date_at:
type:
- string
- 'null'
description: >-
Best-effort ISO 8601 date parsed from sold_date,
e.g. "2026-07-02". Null when the marketplace's date
format is not English.
examples:
- '2026-07-02'
watchers:
type:
- integer
- 'null'
coupon:
type:
- string
- 'null'
rating:
type:
- number
- 'null'
ratings_total:
type:
- integer
- 'null'
seller_name:
type:
- string
- 'null'
seller_feedback_percent:
type:
- number
- 'null'
seller_feedback_score:
type:
- integer
- 'null'
program_badge:
type:
- string
- 'null'
is_sponsored:
type:
- boolean
- 'null'
description: >-
Always null — eBay renders its Sponsored badge into
every card as anti-scraping bait, so promoted
placements cannot be distinguished from organic
results.
facets:
type: object
additionalProperties:
type: array
items:
type: string
pagination:
type: object
properties:
current_page:
type: integer
per_page:
type:
- integer
- 'null'
total_pages:
type:
- integer
- 'null'
total_results:
type:
- integer
- 'null'
has_more:
type:
- boolean
- 'null'
description: >-
True while eBay still offers a next page — the stop
signal for bulk extraction. total_results is populated
on completed/sold; total_pages may be null. Past the
last page eBay re-serves it, so page on has_more
rather than looping until empty.
scraped_utc:
type:
- number
- 'null'
scraped_at:
type:
- string
- 'null'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````