trawl-api 0.1.0__py3-none-any.whl

trawl_api/__init__.py

@@ -0,0 +1,63 @@
+"""Python client for the trawl API (https://trawl.dev)."""
+
+from ._client import AsyncTrawl, Trawl
+from ._errors import (
+    APIConnectionError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TrawlError,
+)
+from ._models import (
+    APIResponse,
+    Attribute,
+    CategoriesResponse,
+    Category,
+    Feedback,
+    Grading,
+    Item,
+    RateLimit,
+    Sale,
+    Seller,
+    SoldListing,
+    SoldResponse,
+)
+from ._version import __version__
+from .ebay import Condition, Site
+
+__all__ = [
+    "APIConnectionError",
+    "APIResponse",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncTrawl",
+    "Attribute",
+    "AuthenticationError",
+    "BadRequestError",
+    "CategoriesResponse",
+    "Category",
+    "Condition",
+    "Feedback",
+    "Grading",
+    "InsufficientCreditsError",
+    "Item",
+    "NotFoundError",
+    "RateLimit",
+    "RateLimitError",
+    "Sale",
+    "Seller",
+    "ServerError",
+    "Site",
+    "SoldListing",
+    "SoldResponse",
+    "Trawl",
+    "TrawlError",
+    "__version__",
+]

trawl_api/_client.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import time
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import ValidationError
+
+from ._errors import (
+    APIConnectionError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TrawlError,
+)
+from ._models import APIResponse, rate_limit_from_headers
+from ._version import __version__
+from .ebay import AsyncEbay, Ebay
+
+DEFAULT_BASE_URL = "https://api.trawl.dev"
+# A 20-page search with details is one response of up to 2,000 listings.
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+
+_RETRY_STATUSES = frozenset({500, 502, 503, 504})
+_MAX_RETRY_AFTER = 30.0
+_STATUS_ERRORS: dict[int, type[APIStatusError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: AuthenticationError,
+    404: NotFoundError,
+}
+
+Params = list[tuple[str, str]]
+ResponseT = TypeVar("ResponseT", bound=APIResponse)
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    value = response.headers.get("retry-after")
+    if value is None:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return 1.0
+
+
+def _error_message(response: httpx.Response) -> str:
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict) and isinstance(body.get("error"), str):
+        return body["error"]
+    return response.text.strip() or f"HTTP {response.status_code}"
+
+
+def _status_error(response: httpx.Response) -> APIStatusError:
+    message = _error_message(response)
+    status = response.status_code
+    if status == 429:
+        retry_after = _retry_after(response)
+        if retry_after is None:
+            return InsufficientCreditsError(message, response)
+        return RateLimitError(message, response, retry_after=retry_after)
+    if status >= 500:
+        return ServerError(message, response)
+    return _STATUS_ERRORS.get(status, APIStatusError)(message, response)
+
+
+def _parse(response: httpx.Response, model: type[ResponseT]) -> ResponseT:
+    try:
+        parsed = model.model_validate(response.json())
+    except (ValueError, ValidationError) as exc:
+        raise APIResponseValidationError(
+            f"The API's answer could not be read as {model.__name__}. "
+            "Upgrading trawl-api may fix this: pip install -U trawl-api"
+        ) from exc
+    parsed._rate_limit = rate_limit_from_headers(response.headers)
+    return parsed
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str | None,
+        timeout: float,
+        max_retries: int,
+    ) -> None:
+        api_key = api_key or os.environ.get("TRAWL_API_KEY")
+        if not api_key:
+            raise TrawlError(
+                "No API key. Pass api_key=... or set the TRAWL_API_KEY environment variable. "
+                "Create a key at https://trawl.dev/console/keys"
+            )
+        self.api_key = api_key
+        self.base_url = (base_url or os.environ.get("TRAWL_BASE_URL") or DEFAULT_BASE_URL).rstrip(
+            "/"
+        )
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {
+            "x-api-key": self.api_key,
+            "accept": "application/json",
+            "user-agent": f"trawl-python/{__version__}",
+        }
+
+    def _retry_delay(self, attempt: int, response: httpx.Response | None) -> float | None:
+        """Seconds to wait before another attempt, or None when the failure is final."""
+        if attempt >= self.max_retries:
+            return None
+        if response is not None:
+            retry_after = _retry_after(response)
+            if response.status_code == 429:
+                # Without Retry-After the credits are spent, and waiting does not help.
+                return None if retry_after is None else min(retry_after, _MAX_RETRY_AFTER)
+            if response.status_code not in _RETRY_STATUSES:
+                return None
+            if retry_after is not None:
+                return min(retry_after, _MAX_RETRY_AFTER)
+        return min(0.5 * 2**attempt, 8.0) * random.uniform(0.75, 1.25)
+
+
+class Trawl(_BaseClient):
+    """The trawl API client.
+
+        client = Trawl()  # reads TRAWL_API_KEY
+        sold = client.ebay.sold("iphone 15 pro 256gb", condition="used")
+
+    Failed requests are retried `max_retries` times on connection errors, 5xx
+    answers and per-second rate limits; errors are never billed.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http = http_client or httpx.Client()
+        self._owns_http = http_client is None
+        self.ebay = Ebay(self)
+
+    def _get(self, path: str, params: Params, model: type[ResponseT]) -> ResponseT:
+        attempt = 0
+        while True:
+            response: httpx.Response | None = None
+            cause: Exception | None = None
+            error: TrawlError
+            try:
+                response = self._http.get(
+                    self.base_url + path,
+                    params=tuple(params),
+                    headers=self._headers,
+                    timeout=self.timeout,
+                )
+            except httpx.TimeoutException as exc:
+                error, cause = APITimeoutError("The request timed out."), exc
+            except httpx.TransportError as exc:
+                error, cause = APIConnectionError(f"Could not reach the API: {exc}"), exc
+            else:
+                if response.is_success:
+                    return _parse(response, model)
+                error = _status_error(response)
+            delay = self._retry_delay(attempt, response)
+            if delay is None:
+                raise error from cause
+            time.sleep(delay)
+            attempt += 1
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Trawl:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncTrawl(_BaseClient):
+    """The trawl API client for asyncio. Same surface as `Trawl`, awaited."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http = http_client or httpx.AsyncClient()
+        self._owns_http = http_client is None
+        self.ebay = AsyncEbay(self)
+
+    async def _get(self, path: str, params: Params, model: type[ResponseT]) -> ResponseT:
+        attempt = 0
+        while True:
+            response: httpx.Response | None = None
+            cause: Exception | None = None
+            error: TrawlError
+            try:
+                response = await self._http.get(
+                    self.base_url + path,
+                    params=tuple(params),
+                    headers=self._headers,
+                    timeout=self.timeout,
+                )
+            except httpx.TimeoutException as exc:
+                error, cause = APITimeoutError("The request timed out."), exc
+            except httpx.TransportError as exc:
+                error, cause = APIConnectionError(f"Could not reach the API: {exc}"), exc
+            else:
+                if response.is_success:
+                    return _parse(response, model)
+                error = _status_error(response)
+            delay = self._retry_delay(attempt, response)
+            if delay is None:
+                raise error from cause
+            await asyncio.sleep(delay)
+            attempt += 1
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncTrawl:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()

trawl_api/_errors.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import httpx
+
+
+class TrawlError(Exception):
+    """Base class for every error this package raises."""
+
+
+class APIConnectionError(TrawlError):
+    """The request never got an answer (DNS, connection reset, TLS)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request ran past the client's timeout."""
+
+
+class APIResponseValidationError(TrawlError):
+    """The API answered 2xx with a body this version of the package cannot read."""
+
+
+class APIStatusError(TrawlError):
+    """The API answered with an error status. `message` is the API's own explanation."""
+
+    def __init__(self, message: str, response: httpx.Response) -> None:
+        super().__init__(message)
+        self.message = message
+        self.response = response
+        self.status_code = response.status_code
+
+
+class BadRequestError(APIStatusError):
+    """400: a parameter failed validation; the message names the field and the rule."""
+
+
+class AuthenticationError(APIStatusError):
+    """403: the API key is missing, invalid or deleted."""
+
+
+class NotFoundError(APIStatusError):
+    """404: nothing found, e.g. an item whose details are not available yet. Not billed."""
+
+
+class RateLimitError(APIStatusError):
+    """429 with Retry-After: the plan's per-second rate was exceeded. Wait and retry."""
+
+    def __init__(self, message: str, response: httpx.Response, *, retry_after: float) -> None:
+        super().__init__(message, response)
+        self.retry_after = retry_after
+
+
+# Deliberately not a RateLimitError: code that catches a rate limit to sleep and
+# retry would loop forever on spent credits, which only a new window or a plan fixes.
+class InsufficientCreditsError(APIStatusError):
+    """429 without Retry-After: the month's credits are spent, or too few remain to
+    cover the request's max_pages. Lower max_pages, upgrade, or wait for the reset."""
+
+
+class ServerError(APIStatusError):
+    """5xx: a failure on trawl's side. Safe to retry."""

trawl_api/_models.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+
+
+@dataclass(frozen=True)
+class RateLimit:
+    """The account's allowance, read from the response's X-RateLimit-* headers."""
+
+    limit: int | None
+    """Credits included in the plan per month."""
+    remaining: int | None
+    """Credits left in this billing window."""
+    reset: datetime | None
+    """When the window resets (the billing period's end)."""
+
+
+def rate_limit_from_headers(headers: Mapping[str, str]) -> RateLimit | None:
+    def number(name: str) -> int | None:
+        try:
+            return int(headers[name])
+        except (KeyError, ValueError):
+            return None
+
+    limit = number("x-ratelimit-limit")
+    remaining = number("x-ratelimit-remaining")
+    reset_at = number("x-ratelimit-reset")
+    if limit is None and remaining is None and reset_at is None:
+        return None
+    reset = None
+    if reset_at is not None:
+        # A Unix timestamp; read milliseconds as well as seconds.
+        seconds = reset_at / 1000 if reset_at > 100_000_000_000 else reset_at
+        reset = datetime.fromtimestamp(seconds, tz=timezone.utc)
+    return RateLimit(limit=limit, remaining=remaining, reset=reset)
+
+
+class _Model(BaseModel):
+    # extra="allow": a field the API adds later is kept on the object instead of
+    # breaking every installed version of the package.
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class APIResponse(_Model):
+    credits_charged: int = 0
+    """Credits this call cost. 0 for a search that matched nothing."""
+
+    _rate_limit: RateLimit | None = PrivateAttr(default=None)
+
+    @property
+    def rate_limit(self) -> RateLimit | None:
+        """The account's allowance after this call, when the API sent it."""
+        return self._rate_limit
+
+
+class Grading(_Model):
+    graded: bool | None = None
+    grader: str | None = None
+    grade: str | None = None
+    condition: str | None = None
+
+
+class Attribute(_Model):
+    key: str
+    value: str
+    values: list[str] = Field(default_factory=list)
+
+
+class Seller(_Model):
+    username: str
+    feedback_percent: float | None = None
+    feedback_count: int | None = None
+    items_sold: int | None = None
+
+
+class Feedback(_Model):
+    username: str | None = None
+    rating: str | None = None
+    comment: str | None = None
+    age_text: str | None = None
+
+
+class Sale(_Model):
+    date_sold: datetime
+    sale_price: float
+    shipping_price: float | None = None
+    currency: str | None = None
+    condition: str | None = None
+
+
+class Item(APIResponse):
+    """One listing in full, as GET /item answers it.
+
+    A listing eBay has removed carries only `site`, `item_id` and
+    `listing_state == "removed"`; every other field is then empty.
+    """
+
+    site: str | None = None
+    item_id: str | None = None
+    title: str | None = None
+    condition: str | None = None
+    condition_raw: str | None = None
+    condition_description: str | None = None
+    grading: Grading | None = None
+    listing_state: str | None = None
+    sold_at: datetime | None = None
+    last_updated: datetime | None = None
+    sale_price: float | None = None
+    currency: str | None = None
+    buying_format: str | None = None
+    bids: int | None = None
+    best_offer_available: bool | None = None
+    best_offer_accepted: bool | None = None
+    shipping_service: str | None = None
+    returns_text: str | None = None
+    seller_accepts_returns: bool | None = None
+    location: str | None = None
+    location_country: str | None = None
+    epid: str | None = None
+    category_id: str | None = Field(default=None, alias="categoryId")
+    item_link: str | None = None
+    images: list[str] = Field(default_factory=list)
+    attributes: list[Attribute] = Field(default_factory=list)
+    description_url: str | None = None
+    description_text: str | None = None
+    seller: Seller | None = None
+    feedback: list[Feedback] = Field(default_factory=list)
+    sales: list[Sale] = Field(default_factory=list)
+
+    @property
+    def is_removed(self) -> bool:
+        return self.listing_state == "removed"
+
+    @property
+    def specifics(self) -> dict[str, str]:
+        """The item specifics as a dict: `item.specifics["Brand"]`."""
+        return {attribute.key: attribute.value for attribute in self.attributes}
+
+
+class SoldListing(_Model):
+    title: str
+    sale_price: float
+    shipping_price: float | None = None
+    currency: str | None = None
+    condition: str | None = None
+    condition_raw: str | None = None
+    date_sold: datetime
+    buying_format: str | None = None
+    bids: int | None = None
+    best_offer_available: bool | None = None
+    location: str | None = None
+    item_id: str
+    epid: str | None = None
+    category_id: str | None = Field(default=None, alias="categoryId")
+    item_link: str | None = None
+    image_url: str | None = None
+    details: Item | None = None
+    """The listing's full /item data. Only with `details=True`."""
+    listing_state: str | None = None
+    """"removed" when eBay has taken the listing down. Only with `details=True`."""
+
+
+class SoldResponse(APIResponse):
+    site: str
+    currency: str | None = None
+    query: list[str] = Field(default_factory=list)
+    filters: dict[str, Any] = Field(default_factory=dict)
+    max_pages: int | None = None
+    count: int = 0
+    took_ms: int | None = None
+    results: list[SoldListing] = Field(default_factory=list)
+
+
+class Category(_Model):
+    category_id: str = Field(alias="categoryId")
+    name: str
+    group: str | None = None
+
+
+class CategoriesResponse(APIResponse):
+    site: str
+    total: int | None = None
+    count: int = 0
+    categories: list[Category] = Field(default_factory=list)

trawl_api/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

trawl_api/ebay.py

@@ -0,0 +1,203 @@
+"""The eBay API: sold listings, one listing in full, and category lookup."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from datetime import date, datetime
+from typing import TYPE_CHECKING, Literal
+
+from ._models import CategoriesResponse, Item, SoldResponse
+
+if TYPE_CHECKING:
+    from ._client import AsyncTrawl, Trawl
+
+Site = Literal["EBAY_US", "EBAY_GB"]
+Condition = Literal["new", "used", "parts", "other"]
+AttrFilter = Mapping[str, "str | Sequence[str]"] | Sequence[str] | str
+
+_PREFIX = "/ebay/v1"
+_Params = list[tuple[str, str]]
+
+
+def _day(value: date | str) -> str:
+    if isinstance(value, datetime):
+        return value.date().isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return value
+
+
+def _joined(value: str | Sequence[str]) -> str:
+    return value if isinstance(value, str) else ",".join(value)
+
+
+def _attr_params(attr: AttrFilter) -> _Params:
+    # The API takes one attr=Key:Value per filter, the parameter repeated.
+    if isinstance(attr, str):
+        return [("attr", attr)]
+    if isinstance(attr, Mapping):
+        params: _Params = []
+        for key, value in attr.items():
+            for one in [value] if isinstance(value, str) else value:
+                params.append(("attr", f"{key}:{one}"))
+        return params
+    return [("attr", one) for one in attr]
+
+
+def _sold_params(
+    query: str,
+    exclude: str | Sequence[str] | None,
+    site: Site | None,
+    category: str | int | None,
+    condition: Condition | Sequence[Condition] | None,
+    attr: AttrFilter | None,
+    min_price: float | None,
+    max_price: float | None,
+    date_from: date | str | None,
+    date_to: date | str | None,
+    max_pages: int | None,
+    details: bool,
+) -> _Params:
+    params: _Params = [("query", query)]
+    if exclude:
+        params.append(("exclude", _joined(exclude)))
+    if site:
+        params.append(("site", site))
+    if category is not None:
+        params.append(("category", str(category)))
+    if condition:
+        params.append(("condition", _joined(condition)))
+    if attr:
+        params.extend(_attr_params(attr))
+    if min_price is not None:
+        params.append(("min_price", str(min_price)))
+    if max_price is not None:
+        params.append(("max_price", str(max_price)))
+    if date_from is not None:
+        params.append(("date_from", _day(date_from)))
+    if date_to is not None:
+        params.append(("date_to", _day(date_to)))
+    if max_pages is not None:
+        params.append(("max_pages", str(max_pages)))
+    if details:
+        params.append(("details", "1"))
+    return params
+
+
+def _item_params(item_id: str | int, site: Site | None) -> _Params:
+    params: _Params = [("item_id", str(item_id))]
+    if site:
+        params.append(("site", site))
+    return params
+
+
+def _categories_params(query: str | int, site: Site | None) -> _Params:
+    params: _Params = [("query", str(query))]
+    if site:
+        params.append(("site", site))
+    return params
+
+
+class Ebay:
+    def __init__(self, client: Trawl) -> None:
+        self._client = client
+
+    def sold(
+        self,
+        query: str,
+        *,
+        exclude: str | Sequence[str] | None = None,
+        site: Site | None = None,
+        category: str | int | None = None,
+        condition: Condition | Sequence[Condition] | None = None,
+        attr: AttrFilter | None = None,
+        min_price: float | None = None,
+        max_price: float | None = None,
+        date_from: date | str | None = None,
+        date_to: date | str | None = None,
+        max_pages: int | None = None,
+        details: bool = False,
+    ) -> SoldResponse:
+        """Sold listings whose title contains every word of `query`, newest first.
+
+        Args:
+            query: Words that must all appear in the listing title, in any order.
+            exclude: Words that must not appear in the title.
+            site: Marketplace, "EBAY_US" (the default) or "EBAY_GB".
+            category: An eBay leaf category id; find ids with `categories()`.
+            condition: One or several of "new", "used", "parts", "other".
+            attr: Item specifics to match, e.g. `{"Brand": "Apple", "Grade": ["9", "10"]}`.
+                Different keys must all match; several values for one key match any.
+            min_price: Minimum sale price in the marketplace's own currency.
+            max_price: Maximum sale price in the marketplace's own currency.
+            date_from: Earliest sale date, inclusive (a `date` or "YYYY-MM-DD").
+            date_to: Latest sale date, inclusive.
+            max_pages: Pages of 100 results to return in this one response, 1-20
+                (1 when omitted). Also the most credits the call can cost.
+            details: Include each result's full listing details (`listing.details`).
+
+        Costs 1 credit per page of results returned, 2 with `details=True`;
+        a search that matches nothing is free.
+        """
+        params = _sold_params(
+            query, exclude, site, category, condition, attr,
+            min_price, max_price, date_from, date_to, max_pages, details,
+        )  # fmt: skip
+        return self._client._get(f"{_PREFIX}/sold", params, SoldResponse)
+
+    def item(self, item_id: str | int, *, site: Site | None = None) -> Item:
+        """One sold listing in full, by the `item_id` of any `sold()` result.
+
+        Costs 1 credit. Details become available a few minutes after a sale;
+        until then the call raises `NotFoundError`, which is never billed. A
+        listing eBay has removed answers free, with `item.is_removed` true.
+        """
+        return self._client._get(f"{_PREFIX}/item", _item_params(item_id, site), Item)
+
+    def categories(self, query: str | int, *, site: Site | None = None) -> CategoriesResponse:
+        """eBay leaf categories by name, busiest first; a numeric query looks up that id.
+
+        Costs 1 credit, nothing if no category matches. Category ids differ per
+        marketplace, so pass the same `site` you will search with.
+        """
+        return self._client._get(
+            f"{_PREFIX}/categories", _categories_params(query, site), CategoriesResponse
+        )
+
+
+class AsyncEbay:
+    def __init__(self, client: AsyncTrawl) -> None:
+        self._client = client
+
+    async def sold(
+        self,
+        query: str,
+        *,
+        exclude: str | Sequence[str] | None = None,
+        site: Site | None = None,
+        category: str | int | None = None,
+        condition: Condition | Sequence[Condition] | None = None,
+        attr: AttrFilter | None = None,
+        min_price: float | None = None,
+        max_price: float | None = None,
+        date_from: date | str | None = None,
+        date_to: date | str | None = None,
+        max_pages: int | None = None,
+        details: bool = False,
+    ) -> SoldResponse:
+        """Sold listings matching `query`, newest first. See `Ebay.sold`."""
+        params = _sold_params(
+            query, exclude, site, category, condition, attr,
+            min_price, max_price, date_from, date_to, max_pages, details,
+        )  # fmt: skip
+        return await self._client._get(f"{_PREFIX}/sold", params, SoldResponse)
+
+    async def item(self, item_id: str | int, *, site: Site | None = None) -> Item:
+        """One sold listing in full. See `Ebay.item`."""
+        return await self._client._get(f"{_PREFIX}/item", _item_params(item_id, site), Item)
+
+    async def categories(self, query: str | int, *, site: Site | None = None) -> CategoriesResponse:
+        """eBay leaf categories by name or id. See `Ebay.categories`."""
+        return await self._client._get(
+            f"{_PREFIX}/categories", _categories_params(query, site), CategoriesResponse
+        )

trawl_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.5
+Name: trawl-api
+Version: 0.1.0
+Summary: Python eBay scraper API: sold listings, prices and item details from eBay as JSON
+Project-URL: Homepage, https://trawl.dev
+Project-URL: Documentation, https://trawl.dev/docs
+Project-URL: Pricing, https://trawl.dev/pricing
+Project-URL: Repository, https://github.com/trawl-inc/trawl-python
+Project-URL: Changelog, https://github.com/trawl-inc/trawl-python/blob/main/CHANGELOG.md
+Author: trawl
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ebay,ebay api,ebay price data,ebay scraper,ebay sold listings,scraper,sold prices,trawl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.25
+Requires-Dist: pydantic<3,>=2.5
+Description-Content-Type: text/markdown
+
+# trawl-api: Python eBay scraper API for sold listings and prices
+
+[![PyPI](https://img.shields.io/pypi/v/trawl-api)](https://pypi.org/project/trawl-api/)
+[![Python](https://img.shields.io/pypi/pyversions/trawl-api)](https://pypi.org/project/trawl-api/)
+
+The official Python client for [trawl](https://trawl.dev), a data API for eBay. Search 300+
+million completed eBay sales on the US and UK marketplaces and get each one back as typed
+Python objects: final price, sale date, condition, shipping, seller, item specifics, images
+and description. One API key, no proxies, no HTML parsing, no browser to run.
+
+```bash
+pip install trawl-api
+```
+
+Requires Python 3.10 or newer. [Create a free account](https://trawl.dev/signup) to get an
+API key; the free plan needs no card.
+
+## Quickstart
+
+```python
+from trawl_api import Trawl
+
+client = Trawl()  # reads the TRAWL_API_KEY environment variable
+
+sold = client.ebay.sold("iphone 15 pro 256gb", condition="used")
+
+for listing in sold.results[:5]:
+    print(listing.date_sold.date(), listing.sale_price, listing.title)
+
+print(f"{sold.count} results, {sold.credits_charged} credit(s) charged")
+```
+
+The key can also be passed directly: `Trawl(api_key="sk_live_...")`. Keep it on your server
+and out of source control.
+
+## What you can ask
+
+| Method | Answers | Costs |
+|---|---|---|
+| `client.ebay.sold(query, ...)` | Sold listings matching a query, newest first, up to 2,000 in one response | 1 credit per page of 100 results (2 with `details=True`); free when nothing matches |
+| `client.ebay.item(item_id)` | One sold listing in full: specifics, seller, every image, description, recorded sales | 1 credit |
+| `client.ebay.categories(query)` | eBay categories by name or id, for the `category` filter | 1 credit; free when nothing matches |
+
+The full parameter and field reference is at [trawl.dev/docs](https://trawl.dev/docs).
+
+## Tutorials
+
+Each of these is a complete script in
+[`examples/`](https://github.com/trawl-inc/trawl-python/tree/main/examples).
+
+### Get the sold prices of a product
+
+```python
+from trawl_api import Trawl
+
+client = Trawl()
+sold = client.ebay.sold(
+    "iphone 15 pro 256gb",
+    condition="used",
+    exclude=["case", "cracked"],  # words that must not be in the title
+)
+
+for listing in sold.results:
+    print(
+        f"{listing.date_sold:%Y-%m-%d}  {listing.currency}{listing.sale_price:.2f}  {listing.title}"
+    )
+```
+
+### Average sold price over the last 90 days
+
+`max_pages` sets how many pages of 100 results come back in the one response, and is also the
+most credits the call can cost.
+
+```python
+from datetime import date, timedelta
+from statistics import mean, median
+
+from trawl_api import Trawl
+
+client = Trawl()
+sold = client.ebay.sold(
+    "nintendo switch oled",
+    condition="used",
+    date_from=date.today() - timedelta(days=90),
+    max_pages=5,
+)
+
+prices = [listing.sale_price for listing in sold.results]
+print(
+    f"{len(prices)} sales, average {mean(prices):.2f}, median {median(prices):.2f} {sold.currency}"
+)
+```
+
+### Filter by price, marketplace and item specifics
+
+```python
+sold = client.ebay.sold(
+    "charizard",
+    site="EBAY_GB",  # ebay.co.uk; prices are then in GBP
+    min_price=100,
+    max_price=2000,
+    attr={"Set": "Base Set", "Grade": ["9", "10"]},  # Grade 9 or 10, from Base Set
+)
+```
+
+### Export sold listings to CSV or pandas
+
+```python
+import csv
+
+from trawl_api import Trawl
+
+COLUMNS = ["date_sold", "title", "sale_price", "currency", "condition", "item_id", "item_link"]
+
+client = Trawl()
+sold = client.ebay.sold("charizard base set holo", max_pages=10)
+
+with open("sold.csv", "w", newline="", encoding="utf-8") as file:
+    writer = csv.DictWriter(file, fieldnames=COLUMNS)
+    writer.writeheader()
+    for listing in sold.results:
+        writer.writerow(listing.model_dump(mode="json", include=set(COLUMNS)))
+```
+
+For pandas: `pd.DataFrame(listing.model_dump() for listing in sold.results)`.
+
+### Get one listing's full details
+
+```python
+from trawl_api import NotFoundError, Trawl
+
+client = Trawl()
+
+try:
+    item = client.ebay.item("256637082114")
+except NotFoundError:
+    # Details arrive a few minutes after a sale. A 404 is never billed.
+    raise SystemExit("Details are not available yet.")
+
+print(item.title, item.sale_price, item.currency)
+print(item.specifics["Brand"])  # item specifics as a dict
+print(item.seller.username, item.seller.feedback_percent)
+print(len(item.images), "images")
+```
+
+To get the details of every result of a search in one call, pass `details=True` to `sold()`
+and read `listing.details`.
+
+### Find a category and search inside it
+
+```python
+found = client.ebay.categories("trading card singles", site="EBAY_US")
+for category in found.categories:
+    print(category.category_id, category.name, category.group)
+
+sold = client.ebay.sold("charizard", category=found.categories[0].category_id)
+```
+
+Category ids differ per marketplace, so look them up with the same `site` you search with.
+
+## Credits
+
+Every answer says what it cost, and how much of the month's allowance is left:
+
+```python
+sold = client.ebay.sold("rolex submariner", max_pages=3)
+
+sold.credits_charged  # 3 when three pages came back, 0 when nothing matched
+sold.rate_limit.remaining  # credits left in this billing window
+sold.rate_limit.reset  # when the allowance resets
+```
+
+Errors are never billed.
+
+## Errors
+
+```python
+import trawl_api
+
+try:
+    sold = client.ebay.sold("rolex submariner", min_price=2000)
+except trawl_api.BadRequestError as error:
+    print(error)  # the API names the field and the rule it broke
+except trawl_api.InsufficientCreditsError as error:
+    print(error)  # the month's credits are spent, or too few remain
+except trawl_api.RateLimitError as error:
+    print(error.retry_after)  # seconds to wait
+except trawl_api.APIStatusError as error:
+    print(error.status_code, error)
+```
+
+| Exception | When |
+|---|---|
+| `BadRequestError` | 400, a parameter failed validation |
+| `AuthenticationError` | 403, the key is missing, invalid or deleted |
+| `NotFoundError` | 404, e.g. an item whose details are not available yet |
+| `RateLimitError` | 429 with `Retry-After`, the plan's per-second rate was exceeded |
+| `InsufficientCreditsError` | 429 without `Retry-After`, not enough credits for the request |
+| `ServerError` | 5xx, a failure on trawl's side |
+| `APIConnectionError`, `APITimeoutError` | the request got no answer |
+
+All of them inherit from `trawl_api.TrawlError`. Connection errors, 5xx answers and
+per-second rate limits are retried twice with backoff before they are raised; change that
+with `Trawl(max_retries=...)`.
+
+## Async
+
+```python
+import asyncio
+
+from trawl_api import AsyncTrawl
+
+
+async def main():
+    async with AsyncTrawl() as client:
+        sold = await client.ebay.sold("iphone 15 pro 256gb")
+        print(sold.count)
+
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+client = Trawl(
+    api_key="sk_live_...",  # default: the TRAWL_API_KEY environment variable
+    timeout=60.0,  # seconds
+    max_retries=2,
+)
+```
+
+Responses are [pydantic](https://docs.pydantic.dev) models: `model_dump()` gives a dict,
+`model_dump_json()` a JSON string, and fields the API adds later are kept on the object.
+
+## Links
+
+- [Documentation](https://trawl.dev/docs)
+- [Pricing](https://trawl.dev/pricing)
+- [Changelog](https://github.com/trawl-inc/trawl-python/blob/main/CHANGELOG.md)
+
+trawl is an independent service and is not affiliated with or endorsed by eBay Inc.

trawl_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+trawl_api/__init__.py,sha256=5KIipVdHcogrOtITiQVF5aXcwPrmWth9p8B_JQqae-A,1205
+trawl_api/_client.py,sha256=Vrl8Y7euQkHp4D46_hq8AHHbwlQL8kV17z3eg8kotHY,8401
+trawl_api/_errors.py,sha256=BvrXcZnxKQnYAtJsWVVCTbgGvBtrsuyPwEEfNZ7YveE,1978
+trawl_api/_models.py,sha256=oy-a0yGNVuJGjUn-WAHT4NJTTIBBlSbyrgOzGKOkkp0,5852
+trawl_api/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+trawl_api/ebay.py,sha256=2_bQShPcGI4nV7WHuSdLFsw99lq0bsPwlZ5Sv4Ejt_U,7732
+trawl_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trawl_api-0.1.0.dist-info/METADATA,sha256=lHc4nLQRVq4M3vG0uvjXSvvuD47wHOxnzk4HTQqFkTM,8813
+trawl_api-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+trawl_api-0.1.0.dist-info/licenses/LICENSE,sha256=SnfM7NJTMZQQ-YkAct4d2KlWjM-cqIiRY04dAkLcfiI,1062
+trawl_api-0.1.0.dist-info/RECORD,,

trawl_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

trawl_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 trawl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.