kleinanzeigen-api 0.1.0__py3-none-any.whl

kleinanzeigen_api/__init__.py

@@ -0,0 +1,25 @@
+"""Unofficial Python client for the kleinanzeigen.de mobile JSON API.
+
+This calls the real api.kleinanzeigen.de REST API used by the Android app of
+Germany's Kleinanzeigen marketplace. It can search any category and returns
+structured data the website doesn't show: GPS coordinates, exact result counts,
+typed attributes, all image sizes, ISO timestamps and the price type.
+
+Not affiliated with or endorsed by Kleinanzeigen GmbH / Adevinta. See the README
+for the legal notes and rate-limiting advice.
+"""
+from __future__ import annotations
+
+from .categories import Category, all_categories, find_categories, get_category
+from .client import KleinanzeigenAPI, Listing
+
+__version__ = "0.1.0"
+__all__ = [
+    "KleinanzeigenAPI",
+    "Listing",
+    "Category",
+    "find_categories",
+    "all_categories",
+    "get_category",
+    "__version__",
+]

kleinanzeigen_api/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kleinanzeigen_api/categories.py

@@ -0,0 +1,157 @@
+"""Category catalog: look up categories, search by name, and convert names to ids.
+
+All ~159 categories are stored in data/categories.json, so lookups work without
+a network request. Use KleinanzeigenAPI.fetch_categories() to download an
+updated list if the categories change on the site.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from functools import lru_cache
+from importlib.resources import files
+from typing import List, Optional
+
+_DATA_FILE = "categories.json"
+_CAT_NS = "{http://www.ebayclassifiedsgroup.com/schema/category/v1}categories"
+
+
+@dataclass(frozen=True)
+class Category:
+    id: str
+    name: str
+    path: str                 # e.g. "Auto, Rad & Boot > Fahrräder & Zubehör"
+    real_estate: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@lru_cache(maxsize=1)
+def all_categories() -> List[Category]:
+    """Return the bundled catalog as a list of Category objects (cached)."""
+    text = (files("kleinanzeigen_api") / "data" / _DATA_FILE).read_text(encoding="utf-8")
+    return [
+        Category(str(c["id"]), c["name"], c["path"], bool(c.get("real_estate")))
+        for c in json.loads(text)
+    ]
+
+
+@lru_cache(maxsize=1)
+def _by_id() -> dict:
+    return {c.id: c for c in all_categories()}
+
+
+def get_category(category_id) -> Optional[Category]:
+    """Return the Category with this id, or None if the id is not found."""
+    if category_id is None:
+        return None
+    return _by_id().get(str(category_id))
+
+
+def find_categories(query: str, limit: int = 8) -> List[Category]:
+    """Return up to `limit` categories that match `query`, best matches first.
+
+    Matches are ranked in this order: exact name, name starts with the query,
+    name contains the query, then path contains the query.
+    """
+    q = (query or "").lower().strip()
+    if not q:
+        return []
+    scored = []
+    for c in all_categories():
+        name, path = c.name.lower(), c.path.lower()
+        if name == q:
+            s = 0
+        elif name.startswith(q):
+            s = 1
+        elif q in name:
+            s = 2
+        elif q in path:
+            s = 3
+        else:
+            continue
+        scored.append((s, len(c.name), c))
+    scored.sort(key=lambda x: (x[0], x[1]))
+    return [c for _, _, c in scored[:limit]]
+
+
+def resolve_category(value) -> Optional[str]:
+    """Convert a category name or id into an id string.
+
+    Rules:
+    - None or "" returns None, which means "search all categories".
+    - A number or numeric string is returned unchanged.
+    - A name is looked up. A case-insensitive exact match is used first,
+      otherwise the single best match from find_categories().
+
+    Raises ValueError if the name is unknown or matches more than one category.
+    The error message lists the possible matches.
+    """
+    if value is None:
+        return None
+    s = str(value).strip()
+    if not s:
+        return None
+    if s.isdigit():
+        return s
+
+    exact = [c for c in all_categories() if c.name.lower() == s.lower()]
+    if len(exact) == 1:
+        return exact[0].id
+    if len(exact) > 1:
+        opts = ", ".join(f"{c.id} ({c.path})" for c in exact)
+        raise ValueError(
+            f"Category name {value!r} is ambiguous: {opts}. Pass the numeric id instead."
+        )
+
+    cands = find_categories(s, limit=6)
+    if len(cands) == 1:
+        return cands[0].id
+    if not cands:
+        raise ValueError(
+            f"Unknown category {value!r}. Browse with find_categories({value!r}) "
+            f"or KleinanzeigenAPI().find_categories({value!r})."
+        )
+    opts = "; ".join(f"{c.name} (id {c.id})" for c in cands)
+    raise ValueError(
+        f"Ambiguous category {value!r}. Did you mean: {opts}? "
+        f"Pass an exact name or the numeric id."
+    )
+
+
+def flatten_api_categories(payload: dict) -> List[dict]:
+    """Convert a raw /api/categories.json response into the flat format used by
+    data/categories.json: [{"id", "name", "path", "real_estate"}, ...].
+
+    fetch_categories() uses this to rebuild the bundled file when categories are
+    added or renamed on the site.
+    """
+    root = payload[_CAT_NS]
+    node = root.get("value", root) if isinstance(root, dict) else root
+
+    def name_of(cat: dict) -> str:
+        return ((cat.get("localized-name") or {}).get("value")
+                or (cat.get("id-name") or {}).get("value") or "")
+
+    out: List[dict] = []
+
+    def walk(cat: dict, parts: list, real_estate: bool) -> None:
+        nm = name_of(cat)
+        path_parts = parts + [nm] if nm else parts
+        cid = cat.get("id")
+        if cid:  # skip the synthetic "Alle Kategorien" root (no id)
+            out.append({
+                "id": str(cid),
+                "name": nm,
+                "path": " > ".join(path_parts),
+                "real_estate": real_estate,
+            })
+        for child in cat.get("category", []) or []:
+            walk(child, path_parts, real_estate)
+
+    for alle in node.get("category", []) or []:        # "Alle Kategorien"
+        for branch in alle.get("category", []) or []:  # top-level branches
+            is_re = (branch.get("id-name") or {}).get("value") == "Immobilien"
+            walk(branch, [], is_re)
+    return out

kleinanzeigen_api/cli.py

@@ -0,0 +1,120 @@
+"""Command-line interface. Run as `kleinanzeigen-api` or `python -m kleinanzeigen_api`."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .client import KleinanzeigenAPI, Listing
+
+
+def _print_table(items: list) -> None:
+    """Print the listings as a short text table."""
+    for l in items:
+        price = f"{int(l.price)} €" if l.price else (l.price_type or "—")
+        loc = f"{l.zip_code} {l.city}".strip() or "—"
+        extra = []
+        if l.rooms:
+            extra.append(f"{l.rooms:g} Zi")
+        if l.size_m2:
+            extra.append(f"{l.size_m2:g} m²")
+        nk = l.attributes.get("Warmmiete")
+        if nk:
+            extra.append(f"warm {nk}€")
+        tail = (" | " + " · ".join(extra)) if extra else ""
+        print(f"[{l.id}] {price:>9} | {loc}{tail}")
+        print(f"    {l.title[:90]}")
+        print(f"    {l.url}")
+        print()
+
+
+def main(argv=None) -> int:
+    """Parse the command-line arguments, run the search, and print the results.
+
+    Returns the process exit code (0 on success, 2 on a bad argument or an
+    API error).
+    """
+    p = argparse.ArgumentParser(
+        prog="kleinanzeigen-api",
+        description="Unofficial search client for kleinanzeigen.de (Germany). "
+                    "Searches all categories by default.")
+    p.add_argument("location", nargs="?", help="city/region name or numeric location id")
+    p.add_argument("--category", default=None, metavar="NAME_OR_ID",
+                   help="restrict to a category by NAME or id (default: all categories; "
+                        "e.g. \"Fahrräder & Zubehör\" or 217). Browse with --categories.")
+    p.add_argument("--categories", nargs="?", const="", metavar="QUERY",
+                   help="list category ids matching QUERY (or all of them) and exit")
+    p.add_argument("--distance", type=int, help="radius km")
+    p.add_argument("--min-price", type=int)
+    p.add_argument("--max-price", type=int)
+    p.add_argument("--min-rooms", type=float)
+    p.add_argument("--max-rooms", type=float)
+    p.add_argument("--min-size", type=float)
+    p.add_argument("--max-size", type=float)
+    p.add_argument("--q", help="keyword (server-side)")
+    p.add_argument("--exclude", action="append", metavar="TERM",
+                   help="drop results containing TERM in title/description "
+                        "(repeatable, or comma-separated; client-side)")
+    p.add_argument("--ad-type", choices=["offered", "wanted"], default="offered",
+                   help="OFFERED listings (default) or WANTED ads")
+    p.add_argument("--pages", type=int, default=1)
+    p.add_argument("--size", type=int, default=25, help="results per page (max ~25)")
+    p.add_argument("--sort", choices=["new", "cheap", "expensive", "near"],
+                   help="server-side sort: new=newest, cheap/expensive=price, near=distance")
+    p.add_argument("--sort-price", action="store_true", help="alias for --sort cheap")
+    p.add_argument("--rate", type=float, default=1.5, help="min seconds between requests")
+    p.add_argument("--json", action="store_true", help="emit JSON instead of a table")
+    p.add_argument("--out", help="write JSON to this file")
+    args = p.parse_args(argv)
+
+    # --categories: list categories from the bundled file and exit (no network)
+    if args.categories is not None:
+        from .categories import all_categories, find_categories
+        cats = find_categories(args.categories) if args.categories else all_categories()
+        for c in cats:
+            flag = "  [real estate]" if c.real_estate else ""
+            print(f"{c.id:>5}  {c.path}{flag}")
+        if args.categories and not cats:
+            print(f"no categories match {args.categories!r}", file=sys.stderr)
+        return 0
+
+    sort_map = {"new": "DATE_DESCENDING", "cheap": "PRICE_ASCENDING",
+                "expensive": "PRICE_DESCENDING", "near": "DISTANCE_ASCENDING"}
+    sort_type = sort_map.get(args.sort) or ("PRICE_ASCENDING" if args.sort_price else None)
+
+    exclude = []
+    for chunk in (args.exclude or []):
+        exclude.extend(part.strip() for part in chunk.split(",") if part.strip())
+
+    api = KleinanzeigenAPI(rate_limit=args.rate)
+    try:
+        items = api.search(
+            location=args.location, q=args.q, exclude=exclude or None,
+            category=args.category, distance_km=args.distance,
+            min_price=args.min_price, max_price=args.max_price,
+            min_rooms=args.min_rooms, max_rooms=args.max_rooms,
+            min_size=args.min_size, max_size=args.max_size,
+            ad_type=args.ad_type.upper(),
+            sort_type=sort_type, pages=args.pages, size=args.size)
+    except (ValueError, RuntimeError) as e:
+        # ValueError: unknown/ambiguous category or location.
+        # RuntimeError: rotated credentials (401/403) or network failure from the API.
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    if args.json or args.out:
+        text = json.dumps([l.to_dict() for l in items], ensure_ascii=False, indent=2)
+        if args.out:
+            with open(args.out, "w", encoding="utf-8") as fh:
+                fh.write(text)
+            print(f"wrote {len(items)} listings -> {args.out}", file=sys.stderr)
+        else:
+            print(text)
+    else:
+        _print_table(items)
+        print(f"{len(items)} listings", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())