Kufar APIkufar.by ↗

"""Walkthrough: Kufar.by classifieds — search, drill into details, browse categories."""
from parse_apis.kufar_by_api import Kufar, SortOrder, Condition, OfferNotFound

client = Kufar()

# Search for used MacBooks, newest first; cap total items fetched.
for item in client.offer_summaries.search(
    query="macbook", sort=SortOrder.NEWEST, condition=Condition.USED, limit=5
):
    print(item.title, f"{item.price_byn} BYN", item.region)

# Drill down: take the first hit and fetch its full detail page.
hit = client.offer_summaries.search(query="macbook", limit=1).first()
if hit is not None:
    offer = hit.details()
    print(offer.title, offer.description[:120] if offer.description else "")
    for p in offer.prices:
        print(f"  {p.currency}: {p.price}")
    for param in offer.parameters[:5]:
        print(f"  {param.label}: {param.value_label}")

# Point lookup by ad_id discovered from the search above.
if hit is not None:
    try:
        detail = client.offers.get(ad_id=hit.ad_id)
        print(detail.title, detail.seller_name)
    except OfferNotFound:
        print("Ad was removed since the search.")

# Per-category counters for the same query.
breakdown = client.category_breakdowns.count(query="macbook")
print(f"{breakdown.total} total ads across {len(breakdown.categories)} categories")
for cat in breakdown.categories[:3]:
    print(f"  {cat.category} ({cat.parent}): {cat.count}")

# Browse the full category tree.
for category in client.categories.list(limit=5):
    subs = ", ".join(s.name for s in category.subcategories[:3])
    print(f"{category.name}: {subs}")

# Autocomplete suggestions for a partial query.
for suggestion in client.suggestions.search(query="macbo", limit=5):
    print(suggestion.text, suggestion.preferred_category_id)

print("exercised: offer_summaries.search / details / offers.get / category_breakdowns.count / categories.list / suggestions.search")