ebay-rest


Nameebay-rest JSON
Version 1.0.13 PyPI version JSON
download
home_pageNone
SummaryWraps the eBay REST APIs.
upload_time2025-07-20 19:28:37
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseMIT
keywords ebay api rest
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # ebay_rest
A Python 3 pip package that wraps eBay’s REST APIs.

## Table of Contents
- [Installation](#installation)
  - [Basic Installation](#basic-installation)
  - [Complete Installation](#complete-installation)
- [Setup](#setup)
- [Usage](#usage)
- [FAQ](#faq)
- [Optimization & Performance](#optimization--performance)
- [Contributing](#contributing)
- [Legal](#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.

```bash
pip install ebay_rest
```
If Python 2 is installed, use `pip3` instead.

### Complete Installation
The complete installation includes browser automation for getting eBay user tokens.

```bash
pip install ebay_rest[complete]
```
After installing the package, install Playwright and Chromium:
```bash
playwright install chromium
```
**Note:** Playwright may require additional system dependencies. See [Playwright installation guide](https://playwright.dev/python/docs/intro) for details.

---

## Setup
Follow the setup instructions in the [example configuration file](https://github.com/matecsaj/ebay_rest/blob/main/tests/ebay_rest_EXAMPLE.json).

---

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

```python
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

<details>
  <summary><strong>How are API results structured?</strong></summary>
  <ul>
    <li>Basic types: strings, integers, dates.</li>
    <li><code>dict</code> (objects): Groups related elements.</li>
    <li><code>list</code> (arrays): Repetitive structures with one or more elements.</li>
    <li>Optional elements may be omitted, mandatory elements are set to <code>None</code> if empty.</li>
  </ul>
</details>

<details>
  <summary><strong>How are paged API results handled?</strong></summary>
  <ul>
    <li>A Python <a href="https://www.python.org/dev/peps/pep-0255/">generator</a> is used instead of a list.</li>
    <li>Do <strong>not</strong> supply an "offset" parameter.</li>
    <li>"limit" controls how many records to retrieve.</li>
    <li>To retrieve all records, omit "limit." Be aware of eBay's 10,000 record count limit.</li>
  </ul>
</details>

<details>
  <summary><strong>Can the browser automation be avoided?</strong></summary>
  <p>Yes, reuse the refresh token after the first retrieval. Modify your <code>ebay_rest.json</code> file:</p>
  <pre>
"refresh_token": "your_refresh_token",
"refresh_token_expiry": "your_token_expiry"
  </pre>
</details>

<details>
  <summary><strong>Does this library support threading/multiprocessing?</strong></summary>
  <p>Threading is safe. Multiprocessing is untested (<a href="https://github.com/matecsaj/ebay_rest/issues/20">help wanted</a>).</p>
</details>

<details>
  <summary><strong>Why does eBay return "Internal Error"?</strong></summary>
  <p>Making repeated calls with the same parameters in a short time can trigger this error.</p>
</details>

---

## 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`](CONTRIBUTING.md).

---

## Legal
- Licensed under [MIT](https://github.com/matecsaj/ebay_rest/blob/main/LICENSE).
- "Python" is a trademark of the [Python Software Foundation](https://www.python.org/psf/).
- "eBay" is a trademark of [eBay Inc](https://www.ebay.com).
- This project is **not affiliated with or endorsed by eBay Inc.**


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "ebay-rest",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "ebay, api, rest",
    "author": null,
    "author_email": "Peter JOHN Matecsa <matecsaj@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/2e/de/31dbc3cb271906ff3937a023599b2ab5e0044d78abd9438bc94ee7c5c376/ebay_rest-1.0.13.tar.gz",
    "platform": null,
    "description": "# ebay_rest\nA Python 3 pip package that wraps eBay\u2019s REST APIs.\n\n## Table of Contents\n- [Installation](#installation)\n  - [Basic Installation](#basic-installation)\n  - [Complete Installation](#complete-installation)\n- [Setup](#setup)\n- [Usage](#usage)\n- [FAQ](#faq)\n- [Optimization & Performance](#optimization--performance)\n- [Contributing](#contributing)\n- [Legal](#legal)\n\n---\n\n## Installation\n\n### Basic Installation\nThe basic installation provides core functionality without browser automation. It is lighter, easier to install, and sufficient for most use cases.\n\n```bash\npip install ebay_rest\n```\nIf Python 2 is installed, use `pip3` instead.\n\n### Complete Installation\nThe complete installation includes browser automation for getting eBay user tokens.\n\n```bash\npip install ebay_rest[complete]\n```\nAfter installing the package, install Playwright and Chromium:\n```bash\nplaywright install chromium\n```\n**Note:** Playwright may require additional system dependencies. See [Playwright installation guide](https://playwright.dev/python/docs/intro) for details.\n\n---\n\n## Setup\nFollow the setup instructions in the [example configuration file](https://github.com/matecsaj/ebay_rest/blob/main/tests/ebay_rest_EXAMPLE.json).\n\n---\n\n## Usage\nHere is a basic example of using `ebay_rest` to retrieve eBay's global site IDs and search for iPhones:\n\n```python\nfrom ebay_rest import API, DateTime, Error, Reference\n\nprint(f\"eBay's official date and time is {DateTime.to_string(DateTime.now())}.\\n\")\n\nprint(\"All valid eBay global id values, also known as site ids.\")\nprint(Reference.get_global_id_values(), '\\n')\n\ntry:\n    api = API(application='production_1', user='production_1', header='US')\nexcept Error as error:\n    print(f'Error {error.number} is {error.reason}  {error.detail}.\\n')\nelse:\n    try:\n        print(\"The five least expensive iPhone things now for sale on-eBay:\")        \n        for record in api.buy_browse_search(q='iPhone', sort='price', limit=5):\n            if 'record' not in record:\n                pass    # TODO Refer to non-records, they contain optimization information.\n            else:\n                item = record['record']\n                print(f\"item id: {item['item_id']} {item['item_web_url']}\")\n    except Error as error:\n        print(f'Error {error.number} is {error.reason} {error.detail}.\\n')\n    else:\n        pass\n\nprint(\"\\nClass documentation:\")\nprint(help(API))    # Over a hundred methods are available!\nprint(help(DateTime))\nprint(help(Error))\nprint(help(Reference))\n```\n\n---\n\n## FAQ\n\n<details>\n  <summary><strong>How are API results structured?</strong></summary>\n  <ul>\n    <li>Basic types: strings, integers, dates.</li>\n    <li><code>dict</code> (objects): Groups related elements.</li>\n    <li><code>list</code> (arrays): Repetitive structures with one or more elements.</li>\n    <li>Optional elements may be omitted, mandatory elements are set to <code>None</code> if empty.</li>\n  </ul>\n</details>\n\n<details>\n  <summary><strong>How are paged API results handled?</strong></summary>\n  <ul>\n    <li>A Python <a href=\"https://www.python.org/dev/peps/pep-0255/\">generator</a> is used instead of a list.</li>\n    <li>Do <strong>not</strong> supply an \"offset\" parameter.</li>\n    <li>\"limit\" controls how many records to retrieve.</li>\n    <li>To retrieve all records, omit \"limit.\" Be aware of eBay's 10,000 record count limit.</li>\n  </ul>\n</details>\n\n<details>\n  <summary><strong>Can the browser automation be avoided?</strong></summary>\n  <p>Yes, reuse the refresh token after the first retrieval. Modify your <code>ebay_rest.json</code> file:</p>\n  <pre>\n\"refresh_token\": \"your_refresh_token\",\n\"refresh_token_expiry\": \"your_token_expiry\"\n  </pre>\n</details>\n\n<details>\n  <summary><strong>Does this library support threading/multiprocessing?</strong></summary>\n  <p>Threading is safe. Multiprocessing is untested (<a href=\"https://github.com/matecsaj/ebay_rest/issues/20\">help wanted</a>).</p>\n</details>\n\n<details>\n  <summary><strong>Why does eBay return \"Internal Error\"?</strong></summary>\n  <p>Making repeated calls with the same parameters in a short time can trigger this error.</p>\n</details>\n\n---\n\n## Optimization & Performance\nTo optimize API calls:\n1. **Cache responses** to avoid redundant API calls.\n2. **Use filters** to limit response data.\n3. **Use generators** instead of lists for paged results.\n4. **Utilize threading** (but be mindful of rate limits).\n5. **Reuse the API instance** to avoid unnecessary authentication overhead.\n6. **Optimize your network** (faster internet connection, lower latency).\n\n---\n\n## Contributing\nContributions are welcome! Please fork this repository and submit a pull request. Follow the coding standards outlined in [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n---\n\n## Legal\n- Licensed under [MIT](https://github.com/matecsaj/ebay_rest/blob/main/LICENSE).\n- \"Python\" is a trademark of the [Python Software Foundation](https://www.python.org/psf/).\n- \"eBay\" is a trademark of [eBay Inc](https://www.ebay.com).\n- This project is **not affiliated with or endorsed by eBay Inc.**\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Wraps the eBay REST APIs.",
    "version": "1.0.13",
    "project_urls": {
        "Homepage": "https://github.com/matecsaj/ebay_rest",
        "Issues": "https://github.com/matecsaj/ebay_rest/issues",
        "Repository": "https://github.com/matecsaj/ebay_rest.git"
    },
    "split_keywords": [
        "ebay",
        " api",
        " rest"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "2573a9750e56c6276951c8fd9d8fcce4c05c9a744cfa18bb7dd65787393bbe2e",
                "md5": "b9fa6b7ac606e9f0e41597da1d641097",
                "sha256": "b62dbef6da6261059882e961d96d2dd61135180a2c17c1169b503401efaca799"
            },
            "downloads": -1,
            "filename": "ebay_rest-1.0.13-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "b9fa6b7ac606e9f0e41597da1d641097",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 2940517,
            "upload_time": "2025-07-20T19:28:35",
            "upload_time_iso_8601": "2025-07-20T19:28:35.129573Z",
            "url": "https://files.pythonhosted.org/packages/25/73/a9750e56c6276951c8fd9d8fcce4c05c9a744cfa18bb7dd65787393bbe2e/ebay_rest-1.0.13-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "2ede31dbc3cb271906ff3937a023599b2ab5e0044d78abd9438bc94ee7c5c376",
                "md5": "07153a39770c289f73d23162ca4e183c",
                "sha256": "7d2f667974598f870132df5527a11d5de00c5440b1911af18a5c25a7e8798065"
            },
            "downloads": -1,
            "filename": "ebay_rest-1.0.13.tar.gz",
            "has_sig": false,
            "md5_digest": "07153a39770c289f73d23162ca4e183c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 1412609,
            "upload_time": "2025-07-20T19:28:37",
            "upload_time_iso_8601": "2025-07-20T19:28:37.579114Z",
            "url": "https://files.pythonhosted.org/packages/2e/de/31dbc3cb271906ff3937a023599b2ab5e0044d78abd9438bc94ee7c5c376/ebay_rest-1.0.13.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-20 19:28:37",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "matecsaj",
    "github_project": "ebay_rest",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "ebay-rest"
}
        
Elapsed time: 2.90793s