curl --request POST \
--url https://scrapebadger.com/v1/ebay/search/by-image \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"image_url": "https://example.com/sneaker.jpg",
"domain": "com"
}
'{
"query": "<string>",
"domain": "<string>",
"category_id": "<string>",
"sold": true,
"results": [
{
"position": 123,
"item_id": "<string>",
"product_id": "<string>",
"title": "<string>",
"url": "<string>",
"image": "<string>",
"price": {
"value": 123,
"currency": "<string>",
"symbol": "<string>",
"raw": "<string>"
},
"original_price": {
"value": 123,
"currency": "<string>",
"symbol": "<string>",
"raw": "<string>"
},
"discount_percent": 123,
"currency": "<string>",
"condition": "<string>",
"brand": "<string>",
"buying_format": "<string>",
"is_auction": true,
"bids": 123,
"time_left": "<string>",
"current_bid": {
"value": 123,
"currency": "<string>",
"symbol": "<string>",
"raw": "<string>"
},
"shipping": "<string>",
"shipping_cost": {
"value": 123,
"currency": "<string>",
"symbol": "<string>",
"raw": "<string>"
},
"free_shipping": true,
"location": "<string>",
"returns": "<string>",
"sold_count": 123,
"sold_date": "2 Jul 2026",
"sold_date_at": "2026-07-02",
"watchers": 123,
"coupon": "<string>",
"rating": 123,
"ratings_total": 123,
"seller_name": "<string>",
"seller_feedback_percent": 123,
"seller_feedback_score": 123,
"program_badge": "<string>",
"is_sponsored": true
}
],
"facets": {},
"pagination": {
"current_page": 123,
"per_page": 123,
"total_pages": 123,
"total_results": 123,
"has_more": true
},
"scraped_utc": 123,
"scraped_at": "<string>"
}Search
Search by Image
Search eBay with a photo instead of keywords, using eBay’s own visual search.
POST
/
v1
/
ebay
/
search
/
by-image
curl --request POST \
--url https://scrapebadger.com/v1/ebay/search/by-image \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"image_url": "https://example.com/sneaker.jpg",
"domain": "com"
}
'{
"query": "<string>",
"domain": "<string>",
"category_id": "<string>",
"sold": true,
"results": [
{
"position": 123,
"item_id": "<string>",
"product_id": "<string>",
"title": "<string>",
"url": "<string>",
"image": "<string>",
"price": {
"value": 123,
"currency": "<string>",
"symbol": "<string>",
"raw": "<string>"
},
"original_price": {
"value": 123,
"currency": "<string>",
"symbol": "<string>",
"raw": "<string>"
},
"discount_percent": 123,
"currency": "<string>",
"condition": "<string>",
"brand": "<string>",
"buying_format": "<string>",
"is_auction": true,
"bids": 123,
"time_left": "<string>",
"current_bid": {
"value": 123,
"currency": "<string>",
"symbol": "<string>",
"raw": "<string>"
},
"shipping": "<string>",
"shipping_cost": {
"value": 123,
"currency": "<string>",
"symbol": "<string>",
"raw": "<string>"
},
"free_shipping": true,
"location": "<string>",
"returns": "<string>",
"sold_count": 123,
"sold_date": "2 Jul 2026",
"sold_date_at": "2026-07-02",
"watchers": 123,
"coupon": "<string>",
"rating": 123,
"ratings_total": 123,
"seller_name": "<string>",
"seller_feedback_percent": 123,
"seller_feedback_score": 123,
"program_badge": "<string>",
"is_sponsored": true
}
],
"facets": {},
"pagination": {
"current_page": 123,
"per_page": 123,
"total_pages": 123,
"total_results": 123,
"has_more": true
},
"scraped_utc": 123,
"scraped_at": "<string>"
}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
There is no
eBay ignores sorting on a visual results page — asking for
/v1/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 ofimage_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 for all
supported values.Examples: com, co.uk, de, fr, com.auRestrict results to an eBay category id. Use
/v1/ebay/categories to look
up ids.Page number for paginated results. Range:
1 - 1000.Use pagination.has_more to know when to stop.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 |
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
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"}'
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\"}"
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)
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',
})
scrapebadger ebay search-by-image --image ./sneaker.jpg --domain com
Response
Identical to/v1/ebay/search: results,
facets, pagination, domain and the scrape timestamps. query is null,
since the search was made from a picture rather than words.Body
application/json
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.
Available options:
domestic, worldwide 
