feat(gumtree): add Gumtree UK classifieds API (SCR-254)

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.59.0 — 2026-10-12
+
+- **Gumtree API — 8 endpoints via `client.gumtree`.** UK classifieds (gumtree.com): `search` (keywords, `category` slug, `location` slug/town/postcode with a `distance` radius in miles, `min_price`/`max_price` in GBP, `sort`, `seller_type`, `urgent_only`, `with_photos`, category-specific `filters="key:value,..."`, `page` 1–50), `search_filters` (a category's filters, sort orders and radius options with live counts), `get_listing` (description, every attribute incl. full vehicle spec and history-check flags, images, location, seller with rating, verification and masked phone, similar listings), `get_seller_listings`, `autocomplete`, `location_autocomplete`, `list_locations` and `list_categories`. Dates come as both Unix `*_utc` and ISO 8601 `*_at`. Models are exported top-level with a `Gumtree` prefix (e.g. `GumtreeListingDetail`).
+
 ## 0.58.0 — 2026-10-11
 
 - **Wallapop API — 10 endpoints via `client.wallapop`.** A typed client for the Spanish, Italian and Portuguese second-hand marketplace (`market`: `es`, `it`, `pt`): `search` (40 listings per page with Wallapop's own filters — location and radius, category, price, condition, brand, model, colour, listing age, shipping, warranty, refurbished, and the cars filters year, km, gearbox and horsepower; cursor pagination via `next_page`), `get_item`, `get_user`, `get_user_items`, `get_user_reviews`, `autocomplete`, `list_categories`, `list_filters`, `list_filter_options` and `list_markets`. Boolean filters are only sent when `True`. Models are exported top-level with a `Wallapop` prefix (`WallapopSearchResponse`, `WallapopItemDetail`, `WallapopUserProfile`, ...).

README.md

@@ -99,6 +99,7 @@ export SCRAPEBADGER_API_KEY="sb_live_xxxxxxxxxxxxx"
 | **Apartments.com** | US rental listings with UNIT-LEVEL pricing — search by location with bed/price filters, plus per-unit rent, beds, baths, sqft and availability for every rentable unit | [Apartments Guide](docs/apartments.md) |
 | **Wallapop** | 10 endpoints across Spain, Italy and Portugal — listing search with Wallapop's own filters (incl. cars: year, km, gearbox, horsepower), listing detail, user profile/listings/reviews, autocomplete, categories, search filters and filter options, markets | [Wallapop Docs](https://docs.scrapebadger.com/wallapop/overview) |
 | **Walmart** | 11 endpoints (US-only) — search, category browse, deals feed, autocomplete, product detail, reviews, seller profile/products, store detail, markets | [Walmart Guide](docs/walmart.md) |
+| **Gumtree** | 8 endpoints (UK-only) — search (category, postcode radius, price, seller type, urgent/photos, category-specific filters), search filters with live counts, listing detail (full vehicle spec, seller rating/verification, masked phone), seller listings, keyword and location autocomplete, location and category trees | [Gumtree Docs](https://docs.scrapebadger.com/gumtree/overview) |
 | **Baidu** | 4 endpoints — web search (language + date filters), news vertical, image search, autocomplete. Results carry the **real target URL**, not just Baidu's tracking redirect | [Baidu Docs](https://docs.scrapebadger.com/baidu/overview) |
 | **Bing** | 6 endpoints — web search (with ads + related searches), image search, video search, news vertical, autocomplete, markets | [Bing Docs](https://docs.scrapebadger.com/bing/overview) |
 | **DuckDuckGo** | 7 endpoints — web search (with abstract box), image/news/video search, autocomplete, instant answers, regions | [DuckDuckGo Docs](https://docs.scrapebadger.com/duckduckgo/overview) |

src/scrapebadger/__init__.py

@@ -293,6 +293,70 @@ async def main():
     SearchResult as GeminiSearchResult,
 )
 from scrapebadger.google.client import GoogleClient
+from scrapebadger.gumtree.client import GumtreeClient
+from scrapebadger.gumtree.models import (
+    Attribute as GumtreeAttribute,
+)
+from scrapebadger.gumtree.models import (
+    AutocompleteResponse as GumtreeAutocompleteResponse,
+)
+from scrapebadger.gumtree.models import (
+    Breadcrumb as GumtreeBreadcrumb,
+)
+from scrapebadger.gumtree.models import (
+    CategoryFacet as GumtreeCategoryFacet,
+)
+from scrapebadger.gumtree.models import (
+    CategoryRef as GumtreeCategoryRef,
+)
+from scrapebadger.gumtree.models import (
+    FilterOption as GumtreeFilterOption,
+)
+from scrapebadger.gumtree.models import (
+    FiltersResponse as GumtreeFiltersResponse,
+)
+from scrapebadger.gumtree.models import (
+    ListingDetail as GumtreeListingDetail,
+)
+from scrapebadger.gumtree.models import (
+    ListingSummary as GumtreeListingSummary,
+)
+from scrapebadger.gumtree.models import (
+    LocationAutocompleteResponse as GumtreeLocationAutocompleteResponse,
+)
+from scrapebadger.gumtree.models import (
+    LocationSuggestion as GumtreeLocationSuggestion,
+)
+from scrapebadger.gumtree.models import (
+    SearchFilter as GumtreeSearchFilter,
+)
+from scrapebadger.gumtree.models import (
+    SearchResponse as GumtreeSearchResponse,
+)
+from scrapebadger.gumtree.models import (
+    Seller as GumtreeSeller,
+)
+from scrapebadger.gumtree.models import (
+    SellerListingsResponse as GumtreeSellerListingsResponse,
+)
+from scrapebadger.gumtree.models import (
+    SellerRating as GumtreeSellerRating,
+)
+from scrapebadger.gumtree.models import (
+    SellerVerification as GumtreeSellerVerification,
+)
+from scrapebadger.gumtree.models import (
+    SortOption as GumtreeSortOption,
+)
+from scrapebadger.gumtree.models import (
+    Suggestion as GumtreeSuggestion,
+)
+from scrapebadger.gumtree.models import (
+    TreeNode as GumtreeTreeNode,
+)
+from scrapebadger.gumtree.models import (
+    TreeResponse as GumtreeTreeResponse,
+)
 from scrapebadger.immobiliare.client import ImmobiliareClient
 from scrapebadger.immobiliare.models import (
     Agency as ImmobiliareAgency,
@@ -1408,6 +1472,29 @@ async def main():
     "GeminiSearchResult",
     # Google Scraper
     "GoogleClient",
+    # Gumtree
+    "GumtreeAttribute",
+    "GumtreeAutocompleteResponse",
+    "GumtreeBreadcrumb",
+    "GumtreeCategoryFacet",
+    "GumtreeCategoryRef",
+    "GumtreeClient",
+    "GumtreeFilterOption",
+    "GumtreeFiltersResponse",
+    "GumtreeListingDetail",
+    "GumtreeListingSummary",
+    "GumtreeLocationAutocompleteResponse",
+    "GumtreeLocationSuggestion",
+    "GumtreeSearchFilter",
+    "GumtreeSearchResponse",
+    "GumtreeSeller",
+    "GumtreeSellerListingsResponse",
+    "GumtreeSellerRating",
+    "GumtreeSellerVerification",
+    "GumtreeSortOption",
+    "GumtreeSuggestion",
+    "GumtreeTreeNode",
+    "GumtreeTreeResponse",
     "IPNotAllowedError",
     # Immobiliare
     "ImmobiliareAgency",

src/scrapebadger/client.py

@@ -25,6 +25,7 @@
 from scrapebadger.gemini.client import GeminiClient
 from scrapebadger.google.client import GoogleClient
 from scrapebadger.google_play.client import GooglePlayClient
+from scrapebadger.gumtree.client import GumtreeClient
 from scrapebadger.idealista.client import IdealistaClient
 from scrapebadger.immobiliare.client import ImmobiliareClient
 from scrapebadger.instagram.client import InstagramClient
@@ -173,6 +174,7 @@ def __init__(
         self._gemini: GeminiClient | None = None
         self._instagram: InstagramClient | None = None
         self._walmart: WalmartClient | None = None
+        self._gumtree: GumtreeClient | None = None
         self._duckduckgo: DuckDuckGoClient | None = None
         self._baidu: BaiduClient | None = None
         self._bing: BingClient | None = None
@@ -498,6 +500,30 @@ def walmart(self) -> WalmartClient:
             self._walmart = WalmartClient(self._base_client)
         return self._walmart
 
+    @property
+    def gumtree(self) -> GumtreeClient:
+        """Access Gumtree Scraper API operations.
+
+        Returns:
+            GumtreeClient providing access to all 8 Gumtree endpoints.
+            UK-only: gumtree.com is the single supported market.
+
+        Example:
+            ```python
+            # Search
+            results = await client.gumtree.search("mountain bike", category="bicycles")
+
+            # Listing detail
+            detail = await client.gumtree.get_listing("1803293391")
+
+            # The seller's other listings
+            others = await client.gumtree.get_seller_listings("1803293391")
+            ```
+        """
+        if self._gumtree is None:
+            self._gumtree = GumtreeClient(self._base_client)
+        return self._gumtree
+
     @property
     def duckduckgo(self) -> DuckDuckGoClient:
         """Access DuckDuckGo Search API operations.

src/scrapebadger/gumtree/__init__.py

@@ -0,0 +1,72 @@
+"""Gumtree API module for ScrapeBadger SDK.
+
+This module provides an async client for scraping gumtree.com (United Kingdom)
+classifieds through the ScrapeBadger API. All methods are async and return
+strongly-typed Pydantic models. Gumtree is UK-only, so no method takes a
+market/country parameter.
+
+Example:
+    ```python
+    from scrapebadger import ScrapeBadger
+
+    async with ScrapeBadger(api_key="your-key") as client:
+        # Search
+        results = await client.gumtree.search("mountain bike", category="bicycles")
+        for listing in results.listings:
+            print(listing.title, listing.price_text)
+
+        # Listing detail
+        detail = await client.gumtree.get_listing("1803293391")
+        print(detail.title, detail.seller.name if detail.seller else None)
+    ```
+"""
+
+from scrapebadger.gumtree.client import GumtreeClient
+from scrapebadger.gumtree.models import (
+    Attribute,
+    AutocompleteResponse,
+    Breadcrumb,
+    CategoryFacet,
+    CategoryRef,
+    FilterOption,
+    FiltersResponse,
+    ListingDetail,
+    ListingSummary,
+    LocationAutocompleteResponse,
+    LocationSuggestion,
+    SearchFilter,
+    SearchResponse,
+    Seller,
+    SellerListingsResponse,
+    SellerRating,
+    SellerVerification,
+    SortOption,
+    Suggestion,
+    TreeNode,
+    TreeResponse,
+)
+
+__all__ = [
+    "Attribute",
+    "AutocompleteResponse",
+    "Breadcrumb",
+    "CategoryFacet",
+    "CategoryRef",
+    "FilterOption",
+    "FiltersResponse",
+    "GumtreeClient",
+    "ListingDetail",
+    "ListingSummary",
+    "LocationAutocompleteResponse",
+    "LocationSuggestion",
+    "SearchFilter",
+    "SearchResponse",
+    "Seller",
+    "SellerListingsResponse",
+    "SellerRating",
+    "SellerVerification",
+    "SortOption",
+    "Suggestion",
+    "TreeNode",
+    "TreeResponse",
+]