kleinanzeigen-api 0.1.0__tar.gz

kleinanzeigen_api-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+wheelhouse/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Local secrets / scratch
+.env
+*.local

kleinanzeigen_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 monkrel
+
+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.

kleinanzeigen_api-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: kleinanzeigen-api
+Version: 0.1.0
+Summary: Unofficial Python client + CLI for kleinanzeigen.de (Germany): search any category and get structured listing data (GPS, attributes, prices, images).
+Project-URL: Homepage, https://github.com/monkrel/kleinanzeigen-api
+Project-URL: Repository, https://github.com/monkrel/kleinanzeigen-api
+Project-URL: Issues, https://github.com/monkrel/kleinanzeigen-api/issues
+Author-email: monkrel <dev.monkrel@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,classifieds,ebay-kleinanzeigen,germany,kleinanzeigen,rentals,scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: curl-cffi>=0.7
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kleinanzeigen-api
+
+Unofficial Python client + CLI for **[kleinanzeigen.de](https://www.kleinanzeigen.de)**,
+Germany's classifieds marketplace (formerly *eBay Kleinanzeigen*). It talks to
+the same mobile JSON API (`api.kleinanzeigen.de`) the official Android app uses.
+
+- **Search any category** — cars, electronics, furniture, jobs, rentals… — by
+  keyword, location, price, and more (not just apartments).
+- **`exclude` terms** to drop unwanted results (e.g. `defekt`, `bastler`).
+- Returns **structured data the website never exposes**: GPS coordinates, exact
+  result counts, typed attributes (Wohnfläche, Zimmer, Nebenkosten, …), all
+  image sizes, ISO timestamps and price type.
+
+> [!NOTE]
+> This is for **Germany's kleinanzeigen.de only**, and is **not affiliated with, authorized, or endorsed
+> by** Kleinanzeigen GmbH / Adevinta. It talks to a private app API and is
+> provided for educational and personal use. See [Legal & etiquette](#legal--etiquette).
+
+## Install
+
+```bash
+pip install kleinanzeigen-api
+```
+
+## Quickstart (library)
+
+```python
+from kleinanzeigen_api import KleinanzeigenAPI
+
+api = KleinanzeigenAPI()
+
+# Search EVERY category by keyword, newest first, excluding junk
+ads = api.search(q="ThinkPad X1", exclude=["defekt", "bastler"],
+                 sort_type="DATE_DESCENDING", pages=2)
+for a in ads:
+    print(a.price, a.zip_code, a.city, a.title, a.url)
+
+# Restrict to a category by NAME (or id) + a location, cheapest first
+bikes = api.search("Berlin", category="Fahrräder & Zubehör", q="Rennrad",
+                   distance_km=20, max_price=400, sort_type="PRICE_ASCENDING")
+
+# Convenience wrapper for apartment rentals (category 203 = Mietwohnungen)
+flats = api.search_rentals("Oranienburg", max_price=900, min_rooms=2,
+                           exclude=["tausch", "wg-zimmer"],  # works here too
+                           sort_type="PRICE_ASCENDING")
+for f in flats:
+    print(f.price, f.rooms, f.size_m2, f.latitude, f.longitude, f.attributes)
+
+# A single ad by id
+ad = api.get_ad("123456789")
+```
+
+`exclude` takes a string or a list and drops any result whose **title or
+description** contains one of those terms (case-insensitive, applied
+client-side). `q` is the server-side keyword.
+
+### `Listing` fields
+
+```
+id, title, description, price, price_type, url, city, zip_code,
+latitude, longitude, size_m2, rooms, posted, poster_type, images, attributes
+```
+
+`attributes` is a `{localized_label: value}` dict of everything the ad carries
+(`size_m2` and `rooms` are also surfaced as typed top-level fields).
+
+## Quickstart (CLI)
+
+Installing the package also adds a `kleinanzeigen-api` command
+(`python -m kleinanzeigen_api` works too):
+
+```bash
+# Search ALL categories by keyword, newest first, excluding junk
+kleinanzeigen-api --q "ThinkPad X1" --exclude defekt,bastler --sort new
+
+# Berlin within 20 km, a keyword, cheapest first, JSON to a file
+kleinanzeigen-api Berlin --distance 20 --q "Rennrad" --max-price 400 \
+    --sort cheap --json --out bikes.json
+
+# Restrict to a category id (203 = Wohnung mieten), 2+ rooms, 3 pages
+kleinanzeigen-api Oranienburg --category 203 --max-price 900 \
+    --min-rooms 2 --pages 3 --sort cheap
+```
+
+`--exclude` is repeatable or comma-separated. You can pass a numeric location id
+instead of a name (`kleinanzeigen-api 3331` == Berlin). Run
+`kleinanzeigen-api --help` for all flags.
+
+## Categories — you never need to memorize ids
+
+Pass a **name or an id** to `category`; names are resolved against a catalog of
+all ~159 categories **bundled with the package** (works offline). Unknown or
+ambiguous names raise a `ValueError` listing concrete suggestions.
+
+```python
+from kleinanzeigen_api import find_categories, KleinanzeigenAPI
+
+find_categories("Fahrr")        # -> [Category(id='217', name='Fahrräder & Zubehör', …)]
+KleinanzeigenAPI().search(category="Notebooks", q="ThinkPad")   # by name
+KleinanzeigenAPI().search(category=161, q="ThinkPad")           # or by id
+```
+
+From the CLI, browse with `--categories` (offline, no request):
+
+```bash
+kleinanzeigen-api --categories            # list all
+kleinanzeigen-api --categories fahrr      # filter
+#   217  Auto, Rad & Boot > Fahrräder & Zubehör
+```
+
+> Category **names are German** (it's a German marketplace) — e.g. `Notebooks`,
+> `Fahrräder & Zubehör`, `Mietwohnungen`. When unsure, `find_categories(...)` or
+> `--categories <query>` shows the exact name and id. The bundled catalog can be
+> refreshed from the live API with `KleinanzeigenAPI().fetch_categories()`.
+
+## Search parameters
+
+`search(location=None, *, q, exclude, category, category_id, distance_km,
+min_price, max_price, min_rooms, max_rooms, min_size, max_size, ad_type,
+sort_type, pages, size)`
+
+- **location** — city/region name (resolved automatically) or a numeric id. An
+  unresolvable name raises `ValueError` (no silent nationwide fallback); pass
+  `location=None` to deliberately search all of Germany.
+- **category** — name **or** id; `None` (default) searches **all categories**.
+  `category_id` is the raw-id alias (pass only one).
+- **q** — server-side keyword. **exclude** — string or list; drops results whose
+  title/description contains any term (client-side, case-insensitive).
+- **sort_type** — `PRICE_ASCENDING`, `PRICE_DESCENDING`, `DATE_DESCENDING`,
+  `DISTANCE_ASCENDING` (server-side).
+- **min_rooms / max_rooms / min_size / max_size** — applied client-side; ignored
+  for ads without those attributes.
+- **ad_type** — `OFFERED` (default) or `WANTED`. **pages / size** — paging.
+
+`search_rentals(location, **kwargs)` is the same thing with `category_id=203`
+("Mietwohnungen", apartments to rent) pre-set.
+
+## How the transport works
+
+A plain `requests` client is blocked at the TLS layer, and the API expects app
+headers. This client:
+
+- impersonates a real Chrome TLS fingerprint via [`curl_cffi`](https://github.com/lexiforest/curl_cffi),
+- sends the app version + a self-generated `X-EBAYK-APP` install id
+  (a `uuid4` + millisecond timestamp, exactly how the app mints its own), and
+- authenticates with the app's HTTP Basic credentials.
+
+### Credentials & rotation
+
+The Basic-auth username/password are **app-distribution values baked into the
+Android client**, not personal secrets. They ship as defaults so `pip install`
+just works — but Kleinanzeigen **can rotate them**. If you start getting
+`401`/`403`, supply fresh values without editing the package:
+
+```python
+api = KleinanzeigenAPI(basic_user="…", basic_pw="…")
+```
+
+```bash
+export KLEINANZEIGEN_BASIC_USER=…
+export KLEINANZEIGEN_BASIC_PW=…
+```
+
+Resolution order: constructor arg → environment variable → bundled default.
+
+## Legal & etiquette
+
+- Kleinanzeigen's Terms of Service **forbid automated access**. This library is
+  published for educational/personal use; **you are responsible** for how you
+  use it. Don't scrape at scale, don't redistribute the data, and don't build
+  anything that harms the service or its users.
+- Be polite to the API: the client rate-limits to ~1.5 s/request by default
+  (with jitter). Don't lower it much, and cache results instead of tight polling.
+- No warranty — see [LICENSE](LICENSE).
+
+## Development
+
+```bash
+git clone https://github.com/monkrel/kleinanzeigen-api
+cd kleinanzeigen-api
+pip install -e ".[dev]"
+pytest -q          # offline parsing tests, no network
+```
+
+## License
+
+[MIT](LICENSE) © monkrel

kleinanzeigen_api-0.1.0/README.md

@@ -0,0 +1,187 @@
+# kleinanzeigen-api
+
+Unofficial Python client + CLI for **[kleinanzeigen.de](https://www.kleinanzeigen.de)**,
+Germany's classifieds marketplace (formerly *eBay Kleinanzeigen*). It talks to
+the same mobile JSON API (`api.kleinanzeigen.de`) the official Android app uses.
+
+- **Search any category** — cars, electronics, furniture, jobs, rentals… — by
+  keyword, location, price, and more (not just apartments).
+- **`exclude` terms** to drop unwanted results (e.g. `defekt`, `bastler`).
+- Returns **structured data the website never exposes**: GPS coordinates, exact
+  result counts, typed attributes (Wohnfläche, Zimmer, Nebenkosten, …), all
+  image sizes, ISO timestamps and price type.
+
+> [!NOTE]
+> This is for **Germany's kleinanzeigen.de only**, and is **not affiliated with, authorized, or endorsed
+> by** Kleinanzeigen GmbH / Adevinta. It talks to a private app API and is
+> provided for educational and personal use. See [Legal & etiquette](#legal--etiquette).
+
+## Install
+
+```bash
+pip install kleinanzeigen-api
+```
+
+## Quickstart (library)
+
+```python
+from kleinanzeigen_api import KleinanzeigenAPI
+
+api = KleinanzeigenAPI()
+
+# Search EVERY category by keyword, newest first, excluding junk
+ads = api.search(q="ThinkPad X1", exclude=["defekt", "bastler"],
+                 sort_type="DATE_DESCENDING", pages=2)
+for a in ads:
+    print(a.price, a.zip_code, a.city, a.title, a.url)
+
+# Restrict to a category by NAME (or id) + a location, cheapest first
+bikes = api.search("Berlin", category="Fahrräder & Zubehör", q="Rennrad",
+                   distance_km=20, max_price=400, sort_type="PRICE_ASCENDING")
+
+# Convenience wrapper for apartment rentals (category 203 = Mietwohnungen)
+flats = api.search_rentals("Oranienburg", max_price=900, min_rooms=2,
+                           exclude=["tausch", "wg-zimmer"],  # works here too
+                           sort_type="PRICE_ASCENDING")
+for f in flats:
+    print(f.price, f.rooms, f.size_m2, f.latitude, f.longitude, f.attributes)
+
+# A single ad by id
+ad = api.get_ad("123456789")
+```
+
+`exclude` takes a string or a list and drops any result whose **title or
+description** contains one of those terms (case-insensitive, applied
+client-side). `q` is the server-side keyword.
+
+### `Listing` fields
+
+```
+id, title, description, price, price_type, url, city, zip_code,
+latitude, longitude, size_m2, rooms, posted, poster_type, images, attributes
+```
+
+`attributes` is a `{localized_label: value}` dict of everything the ad carries
+(`size_m2` and `rooms` are also surfaced as typed top-level fields).
+
+## Quickstart (CLI)
+
+Installing the package also adds a `kleinanzeigen-api` command
+(`python -m kleinanzeigen_api` works too):
+
+```bash
+# Search ALL categories by keyword, newest first, excluding junk
+kleinanzeigen-api --q "ThinkPad X1" --exclude defekt,bastler --sort new
+
+# Berlin within 20 km, a keyword, cheapest first, JSON to a file
+kleinanzeigen-api Berlin --distance 20 --q "Rennrad" --max-price 400 \
+    --sort cheap --json --out bikes.json
+
+# Restrict to a category id (203 = Wohnung mieten), 2+ rooms, 3 pages
+kleinanzeigen-api Oranienburg --category 203 --max-price 900 \
+    --min-rooms 2 --pages 3 --sort cheap
+```
+
+`--exclude` is repeatable or comma-separated. You can pass a numeric location id
+instead of a name (`kleinanzeigen-api 3331` == Berlin). Run
+`kleinanzeigen-api --help` for all flags.
+
+## Categories — you never need to memorize ids
+
+Pass a **name or an id** to `category`; names are resolved against a catalog of
+all ~159 categories **bundled with the package** (works offline). Unknown or
+ambiguous names raise a `ValueError` listing concrete suggestions.
+
+```python
+from kleinanzeigen_api import find_categories, KleinanzeigenAPI
+
+find_categories("Fahrr")        # -> [Category(id='217', name='Fahrräder & Zubehör', …)]
+KleinanzeigenAPI().search(category="Notebooks", q="ThinkPad")   # by name
+KleinanzeigenAPI().search(category=161, q="ThinkPad")           # or by id
+```
+
+From the CLI, browse with `--categories` (offline, no request):
+
+```bash
+kleinanzeigen-api --categories            # list all
+kleinanzeigen-api --categories fahrr      # filter
+#   217  Auto, Rad & Boot > Fahrräder & Zubehör
+```
+
+> Category **names are German** (it's a German marketplace) — e.g. `Notebooks`,
+> `Fahrräder & Zubehör`, `Mietwohnungen`. When unsure, `find_categories(...)` or
+> `--categories <query>` shows the exact name and id. The bundled catalog can be
+> refreshed from the live API with `KleinanzeigenAPI().fetch_categories()`.
+
+## Search parameters
+
+`search(location=None, *, q, exclude, category, category_id, distance_km,
+min_price, max_price, min_rooms, max_rooms, min_size, max_size, ad_type,
+sort_type, pages, size)`
+
+- **location** — city/region name (resolved automatically) or a numeric id. An
+  unresolvable name raises `ValueError` (no silent nationwide fallback); pass
+  `location=None` to deliberately search all of Germany.
+- **category** — name **or** id; `None` (default) searches **all categories**.
+  `category_id` is the raw-id alias (pass only one).
+- **q** — server-side keyword. **exclude** — string or list; drops results whose
+  title/description contains any term (client-side, case-insensitive).
+- **sort_type** — `PRICE_ASCENDING`, `PRICE_DESCENDING`, `DATE_DESCENDING`,
+  `DISTANCE_ASCENDING` (server-side).
+- **min_rooms / max_rooms / min_size / max_size** — applied client-side; ignored
+  for ads without those attributes.
+- **ad_type** — `OFFERED` (default) or `WANTED`. **pages / size** — paging.
+
+`search_rentals(location, **kwargs)` is the same thing with `category_id=203`
+("Mietwohnungen", apartments to rent) pre-set.
+
+## How the transport works
+
+A plain `requests` client is blocked at the TLS layer, and the API expects app
+headers. This client:
+
+- impersonates a real Chrome TLS fingerprint via [`curl_cffi`](https://github.com/lexiforest/curl_cffi),
+- sends the app version + a self-generated `X-EBAYK-APP` install id
+  (a `uuid4` + millisecond timestamp, exactly how the app mints its own), and
+- authenticates with the app's HTTP Basic credentials.
+
+### Credentials & rotation
+
+The Basic-auth username/password are **app-distribution values baked into the
+Android client**, not personal secrets. They ship as defaults so `pip install`
+just works — but Kleinanzeigen **can rotate them**. If you start getting
+`401`/`403`, supply fresh values without editing the package:
+
+```python
+api = KleinanzeigenAPI(basic_user="…", basic_pw="…")
+```
+
+```bash
+export KLEINANZEIGEN_BASIC_USER=…
+export KLEINANZEIGEN_BASIC_PW=…
+```
+
+Resolution order: constructor arg → environment variable → bundled default.
+
+## Legal & etiquette
+
+- Kleinanzeigen's Terms of Service **forbid automated access**. This library is
+  published for educational/personal use; **you are responsible** for how you
+  use it. Don't scrape at scale, don't redistribute the data, and don't build
+  anything that harms the service or its users.
+- Be polite to the API: the client rate-limits to ~1.5 s/request by default
+  (with jitter). Don't lower it much, and cache results instead of tight polling.
+- No warranty — see [LICENSE](LICENSE).
+
+## Development
+
+```bash
+git clone https://github.com/monkrel/kleinanzeigen-api
+cd kleinanzeigen-api
+pip install -e ".[dev]"
+pytest -q          # offline parsing tests, no network
+```
+
+## License
+
+[MIT](LICENSE) © monkrel

kleinanzeigen_api-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kleinanzeigen-api"
+dynamic = ["version"]
+description = "Unofficial Python client + CLI for kleinanzeigen.de (Germany): search any category and get structured listing data (GPS, attributes, prices, images)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "monkrel", email = "dev.monkrel@gmail.com" }]
+keywords = ["kleinanzeigen", "ebay-kleinanzeigen", "api", "scraping", "germany", "classifieds", "rentals"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "curl_cffi>=0.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/monkrel/kleinanzeigen-api"
+Repository = "https://github.com/monkrel/kleinanzeigen-api"
+Issues = "https://github.com/monkrel/kleinanzeigen-api/issues"
+
+[project.scripts]
+kleinanzeigen-api = "kleinanzeigen_api.cli:main"
+
+[tool.hatch.version]
+path = "src/kleinanzeigen_api/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kleinanzeigen_api"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kleinanzeigen_api-0.1.0/src/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-0.1.0/src/kleinanzeigen_api/__main__.py

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