ebay_rest

A Python 3 pip package that wraps eBay’s REST APIs.

Table of Contents

• Installation
  • Basic Installation
  • Complete Installation
• Setup
• Usage
• FAQ
• Optimization & Performance
• Contributing
• Legal

---

Installation

Basic Installation

The basic installation provides core functionality without browser automation. It is lighter, easier to install, and sufficient for most use cases.

pip install ebay_rest

If Python 2 is installed, use pip3 instead.

Complete Installation

The complete installation includes browser automation for obtaining eBay user tokens.

pip install ebay_rest[complete]

After installing the package, install Playwright and Chromium:

playwright install chromium

Note: Playwright may require additional system dependencies. See Playwright installation guide for details.

---

Setup

Follow the setup instructions in the example configuration file.

---

Usage

Here is a basic example of using ebay_rest to retrieve eBay's global site IDs and search for iPhones:

from ebay_rest import API, DateTime, Error, Reference

print(f"eBay's official date and time is {DateTime.to_string(DateTime.now())}.\n")

print("All valid eBay global id values, also known as site ids.")
print(Reference.get_global_id_values(), '\n')

try:
    api = API(application='production_1', user='production_1', header='US')
except Error as error:
    print(f'Error {error.number} is {error.reason}  {error.detail}.\n')
else:
    try:
        print("The five least expensive iPhone things now for sale on-eBay:")        
        for record in api.buy_browse_search(q='iPhone', sort='price', limit=5):
            if 'record' not in record:
                pass    # TODO Refer to non-records, they contain optimization information.
            else:
                item = record['record']
                print(f"item id: {item['item_id']} {item['item_web_url']}")
    except Error as error:
        print(f'Error {error.number} is {error.reason} {error.detail}.\n')
    else:
        pass

print("\nClass documentation:")
print(help(API))    # Over a hundred methods are available!
print(help(DateTime))
print(help(Error))
print(help(Reference))

---

FAQ

How are API results structured?

• Basic types: strings, integers, dates.
• dict (objects): Groups related elements.
• list (arrays): Repetitive structures with 0 or more elements.
• Optional elements may be omitted, mandatory elements are set to None if empty.

How are paged API results handled?

• A Python generator is used instead of a list.
• Do not supply an "offset" parameter.
• "limit" controls how many records to retrieve.
• To retrieve all records, omit "limit." Be aware of eBay's 10,000 record limit.

Can the browser automation be avoided?

Yes, reuse the refresh token after the first retrieval. Modify your ebay_rest.json file:

"refresh_token": "your_refresh_token",
"refresh_token_expiry": "your_token_expiry"
  

Does this library support threading/multiprocessing?

Threading is safe. Multiprocessing is untested (help wanted).

Why does eBay return "Internal Error"?

Making repeated calls with the same parameters in a short time can trigger this error.

---

Optimization & Performance

To optimize API calls:

1. Cache responses to avoid redundant API calls.
2. Use filters to limit response data.
3. Use generators instead of lists for paged results.
4. Utilize threading (but be mindful of rate limits).
5. Reuse the API instance to avoid unnecessary authentication overhead.
6. Optimize your network (faster internet connection, lower latency).

---

Contributing

Contributions are welcome! Please fork this repository and submit a pull request. Follow the coding standards outlined in CONTRIBUTING.md.

---

Legal

• Licensed under MIT.
• "Python" is a trademark of the Python Software Foundation.
• "eBay" is a trademark of eBay Inc.
• This project is not affiliated with or endorsed by eBay Inc.