eBay Search

Search eBay to retrieve listing results with pricing, condition, seller, and shipping data in JSON format.

Endpoint

GET /v1/ebay/search/{query}

Description

The eBay Search endpoint allows you to search eBay listings and retrieve structured result data. The query parameter should be a URL-encoded query string.

Authentication

All requests require authentication using the X-Api-Key header. See the Authentication guide for more details.

Path Parameters

query (required)

Type: string

A URL-encoded query string for the eBay search.

Examples:

  • q=vinyl+records
  • q=iphone+15+case

Request Headers

X-Proxy-Location (optional)

Type: string

Specify the proxy location for the search. Supported countries: EU, CA, US, IE, GB, FR, DE, SE, IN, JP, KR, SG, AU, BR.

X-User-Agent (optional)

Type: string

Optional header to specify device type desktop or mobile. Defaults to desktop.

Allowed values: desktop, mobile

Example Requests

cURL

curl --request GET \
  --url 'https://api.serply.io/v1/ebay/search/q=vinyl+records' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY'

JavaScript

const response = await fetch('https://api.serply.io/v1/ebay/search/q=vinyl+records', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

Python

import requests

url = "https://api.serply.io/v1/ebay/search/q=vinyl+records"
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

Response

The response is a JSON object containing organic listing results from eBay.

Response Structure

{
  "results": [
    {
      "title": "string",
      "link": "string",
      "position": "number",
      "result_type": "string",
      "metadata": {
        "price": "string",
        "was_price": "string",
        "condition": "string",
        "image": "string",
        "seller": "string",
        "seller_feedback": "string",
        "attributes": ["string"]
      }
    }
  ],
  "total": "number",
  "query": "string",
  "ts": "number",
  "device_region": "string",
  "device_type": "null"
}

Response Fields

results (array)

An array of listing objects, each containing:

  • title (string): Listing title
  • link (string): URL to the listing on eBay
  • position (number): Position of the listing in search results
  • result_type (string): Result classification, e.g. organic
  • metadata (object): Additional listing details
    • price (string): Current listing price, as displayed
    • was_price (string, optional): Pre-discount price, present only when the listing shows a markdown
    • condition (string): Item condition, e.g. Pre-Owned, New
    • image (string): URL to the listing's thumbnail image
    • seller (string): Seller username
    • seller_feedback (string): Seller feedback score and percentage, as displayed
    • attributes (array of strings): Additional listing details such as shipping cost, delivery estimate, item location, or or Best Offer

total (number)

Reported total match count. This field is not yet reliable and currently returns 0 regardless of the actual number of matching listings — use the length of results for a real count.

query (string)

The search query that was run.

ts (number)

Time in seconds the request took to complete.

device_region (string)

Proxy region used for the request, if specified via X-Proxy-Location.

device_type (null)

Device type used for the search.

Example Response

{
  "results": [
    {
      "title": "Prince - Welcome 2 America 12” Vinyl Album 2x Records With One Etched Side",
      "link": "https://www.ebay.com/itm/267755938013?epid=...",
      "position": 1,
      "result_type": "organic",
      "metadata": {
        "price": "$27.06",
        "was_price": "$27.00",
        "condition": "Pre-Owned",
        "image": "https://i.ebayimg.com/images/g/.../s-l500.webp",
        "seller": "dshvinyl",
        "seller_feedback": "100% positive (1.2K)",
        "attributes": [
          "or Best Offer",
          "+$4.94 delivery in 2-3 days",
          "Located in United Kingdom"
        ]
      }
    }
  ],
  "total": 0,
  "query": "vinyl records",
  "ts": 2.53,
  "device_region": "",
  "device_type": null
}

Status Codes

  • 200 OK: Successful request
  • 201 Created: Request processed successfully
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation error
  • 429 Too Many Requests: Rate limit exceeded

Error Handling

If an error occurs, the API will return an appropriate HTTP status code with an error message in the response body.

View as Markdown