developer-api-overview

Purpose

Document eBay’s API capabilities for programmatic access to their marketplace, focusing on search functionality, authentication requirements, and getting started as a developer.

Key Findings

Yes, eBay Has a Search API

Answer: Yes, eBay provides comprehensive APIs for searching their marketplace programmatically through the eBay Browse API.

The Browse API is a RESTful API that allows you to:

Search for items by keyword, category, product ID, or GTIN
Filter results by price, condition, location, and more
Retrieve item summaries and detailed information
Access up to 10,000 search results with pagination

eBay Developer Program (2025)

The eBay Developers Program provides access to eBay’s platform and technical resources at developer.ebay.com.

Key Features

Available Resources:

Comprehensive API documentation
SDKs for multiple programming languages
Widgets and embeddable components
Developer sandbox environment
Technical support and forums

2025 Updates:

Inventory Mapping API now available for developer testing
Enhanced API License Agreement with detailed data protection measures
Compliance with international regulations
Restrictions on Restricted APIs and AI-generated content
Usernames being replaced with immutable user IDs for data protection
Financial data protection for select users

eBay Browse API - Search Functionality

The Browse API is part of eBay’s “Buy” API family and provides search and retrieval capabilities.

Search Method

Endpoint:

GET https://api.ebay.com/buy/browse/v1/item_summary/search

Example Request:

GET https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=3

Search Capabilities

Query Parameters:

q - Keyword search query
category_ids - Filter by eBay category
epid - Search by eBay Product ID
gtin - Search by Global Trade Item Number
charity_ids - Filter by supported charities
limit - Number of results per page (max 10,000 total)
offset - Pagination offset
sort - Sort order (default: Best Match)

Filtering Options:

aspect_filter - Filter by specific aspects (brand, color, size, etc.)
buyingOptions - Filter by buying format (FIXED_PRICE, AUCTION, etc.)
filter - Advanced filtering by:
- Listing format
- Item condition (new, used, refurbished)
- Price range
- Location
- Seller criteria
- And more

Search Results

Returns:

Item summaries with key information
Aspect distributions for creating filter histograms
Pagination controls
Refinement data for drill-down searches

Result Limits:

Maximum 10,000 items per search
Default sorting by “Best Match”
Only FIXED_PRICE (Buy It Now) listings returned by default

Note: To retrieve auction-only listings, use the buyingOptions filter parameter.

Authentication - OAuth 2.0

All eBay REST APIs require OAuth 2.0 authentication. You must provide a valid access token for each request.

Getting OAuth Credentials

Step 1: Create Developer Account

Sign up at developer.ebay.com
Create an application
Obtain credentials from the Application Keys page

Your Credentials Include:

client_id - Can be shared with app users
client_secret - Must be kept confidential

Important: eBay provides separate credential sets for Sandbox (testing) and Production environments.

Two Types of OAuth Tokens

1. Application Access Token (Client Credentials Grant)

Use Case: Basic API calls that don’t require user authorization (like searching items)

Request Configuration:

POST https://api.sandbox.ebay.com/identity/v1/oauth2/token

Headers:
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic <Base64(client_id:client_secret)>

Body:
  grant_type=client_credentials
  scope=<URL-encoded space-separated scopes>

Example Scopes:

https://api.ebay.com/oauth/api_scope/buy.browse - For Browse API access

2. User Access Token (Authorization Code Grant)

Use Case: Operations requiring user permission (account access, placing bids, etc.)

Three-Step Process:

Step 1: Get User Consent

Redirect user to eBay’s authorization URL
User logs in and grants permissions
eBay redirects back with authorization code

Step 2: Exchange Code for Tokens

POST https://api.ebay.com/identity/v1/oauth2/token

Body:
  grant_type=authorization_code
  code=<authorization_code>
  redirect_uri=<your_redirect_uri>

Response includes:

access_token - Short-lived token (typically 2 hours)
refresh_token - Long-lived token for getting new access tokens

Step 3: Refresh Access Token

POST https://api.ebay.com/identity/v1/oauth2/token

Body:
  grant_type=refresh_token
  refresh_token=<refresh_token>

OAuth Scopes

OAuth scopes define what API resources and methods your application can access. A token is only valid for methods that match its assigned scopes.

Example Scopes:

https://api.ebay.com/oauth/api_scope/buy.browse - Browse API
https://api.ebay.com/oauth/api_scope/buy.browse.shopping - Shopping data
https://api.ebay.com/oauth/api_scope/sell.inventory - Inventory management

Quick Testing via Developer Portal

For quick testing without implementing OAuth flows:

Navigate to your Application Keys page
Generate a User access token through the UI
Use the token for API testing

Note: These UI-generated tokens are for development only and expire quickly.

Getting Started Guide

1. Create Developer Account

Sign up at developer.ebay.com
Verify your email
Complete developer profile

2. Create an Application

Go to “My Account” → “Application Keys”
Create new application
Choose Production or Sandbox environment

3. Get OAuth Credentials

Copy your client_id and client_secret
Store client_secret securely (never commit to version control)

4. Generate Access Token

For searching items (read-only access):

# Base64 encode credentials
echo -n "client_id:client_secret" | base64

# Request token
curl -X POST 'https://api.ebay.com/identity/v1/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic <base64_credentials>' \
  -d 'grant_type=client_credentials&scope=https://api.ebay.com/oauth/api_scope/buy.browse'

5. Make Your First Search Request

curl -X GET 'https://api.ebay.com/buy/browse/v1/item_summary/search?q=laptop&limit=5' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'X-EBAY-C-MARKETPLACE-ID: EBAY_US'

6. Parse Response

The API returns JSON with:

itemSummaries[] - Array of item results
total - Total number of matching items
limit - Results per page
offset - Current offset
href - Link to current results
next - Link to next page (if available)
prev - Link to previous page (if available)

Additional Browse API Methods

Beyond search, the Browse API provides:

getItem - Retrieve detailed information for a specific item
getItems - Batch retrieval of multiple items
getItemByLegacyId - Get item using old API item ID
search_by_image - Visual search using image upload
checkCompatibility - Check if item fits specific vehicle/device

Best Practices

Security

Never expose client_secret in client-side code
Store tokens securely (encrypted storage, environment variables)
Use HTTPS for all API requests
Implement token refresh logic before expiration

Performance

Cache access tokens (they’re valid for ~2 hours)
Use appropriate pagination (limit and offset)
Implement rate limiting to stay within API quotas
Use batch methods when retrieving multiple items

Error Handling

Handle token expiration (401 Unauthorized)
Implement retry logic for transient failures
Parse error messages from API responses
Monitor API status at developer.ebay.com/support

API Rate Limits

eBay enforces rate limits based on your application tier:

Free tier: Lower limits for development/testing
Production tier: Higher limits after application review

Check your current limits in the Developer Portal under Application Settings.

Resources and Documentation

Official Documentation

eBay Developers Program - Main developer portal
Browse API Overview - API documentation
Browse API Search Method - Search endpoint details
Getting Started with eBay APIs - Quick start guide

Authentication

OAuth Access Tokens - Complete OAuth guide
Authorization Guide - Auth overview
Quick OAuth Guide - Step-by-step OAuth setup
OAuth Credentials - Getting credentials
Client Credentials Grant - Application token flow

Community and Support

Developer Forums - Community support
eBay Developers Program Search - Search documentation