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>"
}

POST

ebay

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 /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 of image_url or image_base64. Sending both, or neither, is a 422.

string

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.

string

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.

string

default:"com"

eBay marketplace domain TLD or alias. See /v1/ebay/markets for all supported values.Examples: com, co.uk, de, fr, com.au

string

Restrict results to an eBay category id. Use /v1/ebay/categories to look up ids.

integer

default:1

Page number for paginated results. Range: 1 - 1000.Use pagination.has_more to know when to stop.

integer

Results per page. Clamped to one of 60, 120, or 240.

string

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

string

Buying format filter: auction, buy_it_now or best_offer.

number

Minimum price, in the marketplace’s own currency.

number

Maximum price, in the marketplace’s own currency.

boolean

default:false

Only return listings with free shipping.

string

Item location. domestic keeps only items located in that marketplace’s own country; worldwide widens to every country.

string

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.

Authorizations

x-api-key

string

header

required

Body

application/json

image_url

string<uri>

Public http(s) URL of the image to search with. Exactly one of image_url or image_base64 is required.

image_base64

string

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

string

default:com

eBay marketplace domain TLD or alias (com, co.uk, de, fr, ...).

category_id

string

Restrict results to a category id.

page

integer

default:1

Page number for paginated results.

Required range: 1 <= x <= 1000

per_page

integer

Results per page. Clamped to 60, 120 or 240.

Required range: 1 <= x <= 240

condition

enum<string>

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.

Available options:

new,

open_box,

refurbished,

used,

for_parts,

graded,

ungraded

buying_format

enum<string>

Buying format filter.

Available options:

auction,

buy_it_now,

best_offer

min_price

number

Minimum price filter in the marketplace's local currency.

Required range: x >= 0

max_price

number

Maximum price filter in the marketplace's local currency.

Required range: x >= 0

free_shipping

boolean

default:false

Only return listings with free shipping.

location

enum<string>

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

language

enum<string>

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.

Available options:

english,

japanese,

chinese,

korean

Response

200 - application/json

Listings matching the image

query

string | null

domain

string

category_id

string | null

sold

boolean

results

object[]

Show child attributes

facets

object

Show child attributes

pagination

object

Show child attributes

scraped_utc

number | null

scraped_at

string | null

Overview

Search

Items

Sellers

Categories

Reference

Body Parameters

There is no `sort_by`

Errors

Examples

Response

Authorizations

Body

Response

​Body Parameters

​There is no sort_by

​Errors

​Examples

​Response

Authorizations

Body

Response

Body Parameters

There is no `sort_by`

Errors

Examples

Response