lbc 1.0.0__tar.gz

lbc-1.0.0/.gitignore

@@ -0,0 +1,194 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the enitre vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

lbc-1.0.0/CHANGELOG.md

@@ -0,0 +1,2 @@
+## v1.0.0
+* Initial release 

lbc-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Étienne Hodé
+
+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.

lbc-1.0.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: lbc
+Version: 1.0.0
+Summary: Unofficial client for Leboncoin API
+Project-URL: Homepage, https://github.com/etienne-hd/lbc-py
+Project-URL: Repository, https://github.com/etienne-hd/lbc-py
+Project-URL: Changelog, https://github.com/etienne-hd/lbc-py/blob/main/CHANGELOG.md
+Author-email: Etienne HODE <hode.etienne@gmail.com>
+Maintainer-email: Etienne HODE <hode.etienne@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,lbc,leboncoin,wrapper
+Requires-Python: >=3.9
+Requires-Dist: curl-cffi==0.11.3
+Description-Content-Type: text/markdown
+
+# lbc
+[![Latest version](https://img.shields.io/pypi/v/lbc?style=for-the-badge)](https://pypi.org/project/lbc)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/lbc?style=for-the-badge)
+[![GitHub license](https://img.shields.io/github/license/etienne-hd/lbc?style=for-the-badge)](https://github.com/etienne-hd/lbc/blob/master/LICENSE)
+
+**Unofficial client for Leboncoin API**
+
+```python
+import lbc
+
+client = lbc.Client()
+
+location = lbc.City( 
+    lat=48.85994982004764,
+    lng=2.33801967847424,
+    radius=10_000, # 10 km
+    city="Paris"
+)
+
+result = client.search(
+    text="maison",
+    locations=[location],
+    page=1,
+    limit=35,
+    sort=lbc.Sort.NEWEST,
+    ad_type=lbc.AdType.OFFER,
+    category=lbc.Category.IMMOBILIER,
+    square=[200, 400],
+    price=[300_000, 700_000]
+)
+
+for ad in result.ads:
+    print(ad.url, ad.subject, ad.price)
+```
+*lbc is not affiliated with, endorsed by, or in any way associated with Leboncoin or its services. Use at your own risk.*
+
+## Installation
+Required Python 3.9+
+```bash
+pip install lbc
+```
+
+## Usage
+### Client
+To create client you need to use lbc.Client class
+```python
+import lbc
+
+client = lbc.Client()
+```
+
+#### Proxy
+You can also configure the client to use a proxy by providing a `Proxy` object:
+```python
+proxy = lbc.Proxy(
+    host=...,
+    port=...,
+    username=...,
+    password=...
+)
+client = lbc.Client(proxy=proxy)
+```
+
+
+### Search
+
+To perform a search, use the `client.search` method.
+
+This function accepts keyword arguments (`**kwargs`) to customize your query.
+For example, if you're looking for houses that include both land and parking, you can specify:
+
+```python
+real_estate_type=["3", "4"]
+```
+
+These values correspond to what you’d find in a typical Leboncoin URL, like:
+
+```
+https://www.leboncoin.fr/recherche?category=9&text=maison&...&real_estate_type=3,4
+```
+
+Here's a complete example of a search query:
+
+```python
+client.search(
+    text="maison",
+    locations=[location],
+    page=1,
+    limit=35,
+    limit_alu=0,
+    sort=lbc.Sort.NEWEST,
+    ad_type=lbc.AdType.OFFER,
+    category=lbc.Category.IMMOBILIER,
+    owner_type=lbc.OwnerType.ALL,
+    search_in_title_only=True,
+    square=[200, 400],
+    price=[300_000, 700_000],
+)
+```
+
+### Location
+
+The `locations` parameter accepts a list of one or more location objects. You can use one of the following:
+
+* `lbc.Region(...)`
+* `lbc.Department(...)`
+* `lbc.City(...)`
+
+Each one corresponds to a different level of geographic granularity.
+
+#### City example
+
+```python
+location = lbc.City(
+    lat=48.85994982004764,
+    lng=2.33801967847424,
+    radius=10_000,  # in meters
+    city="Paris"
+)
+```
+
+#### Region / Department example
+
+```python
+from lbc import Region, Department
+
+region = Region.ILE_DE_FRANCE
+department = Department.PARIS
+```
+
+### 403 Error
+
+If you encounter a **403 Forbidden** error, it usually means your requests are being blocked by [Datadome](https://datadome.co).
+To resolve this:
+
+* Try reducing the request frequency (add delays between requests).
+* If you're using a proxy, make sure it is **clean** and preferably located in **France**.
+
+Using residential or mobile proxies can also help avoid detection.
+
+## License
+
+This project is licensed under the MIT License.
+
+## Support
+
+<a href="https://www.buymeacoffee.com/etienneh" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+You can contact me via [Telegram](https://t.me/etienne_hd) or [Discord](https://discord.com/users/1153975318990827552) if you need help with scraping services or want to write a library.

lbc-1.0.0/README.md

@@ -0,0 +1,149 @@
+# lbc
+[![Latest version](https://img.shields.io/pypi/v/lbc?style=for-the-badge)](https://pypi.org/project/lbc)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/lbc?style=for-the-badge)
+[![GitHub license](https://img.shields.io/github/license/etienne-hd/lbc?style=for-the-badge)](https://github.com/etienne-hd/lbc/blob/master/LICENSE)
+
+**Unofficial client for Leboncoin API**
+
+```python
+import lbc
+
+client = lbc.Client()
+
+location = lbc.City( 
+    lat=48.85994982004764,
+    lng=2.33801967847424,
+    radius=10_000, # 10 km
+    city="Paris"
+)
+
+result = client.search(
+    text="maison",
+    locations=[location],
+    page=1,
+    limit=35,
+    sort=lbc.Sort.NEWEST,
+    ad_type=lbc.AdType.OFFER,
+    category=lbc.Category.IMMOBILIER,
+    square=[200, 400],
+    price=[300_000, 700_000]
+)
+
+for ad in result.ads:
+    print(ad.url, ad.subject, ad.price)
+```
+*lbc is not affiliated with, endorsed by, or in any way associated with Leboncoin or its services. Use at your own risk.*
+
+## Installation
+Required Python 3.9+
+```bash
+pip install lbc
+```
+
+## Usage
+### Client
+To create client you need to use lbc.Client class
+```python
+import lbc
+
+client = lbc.Client()
+```
+
+#### Proxy
+You can also configure the client to use a proxy by providing a `Proxy` object:
+```python
+proxy = lbc.Proxy(
+    host=...,
+    port=...,
+    username=...,
+    password=...
+)
+client = lbc.Client(proxy=proxy)
+```
+
+
+### Search
+
+To perform a search, use the `client.search` method.
+
+This function accepts keyword arguments (`**kwargs`) to customize your query.
+For example, if you're looking for houses that include both land and parking, you can specify:
+
+```python
+real_estate_type=["3", "4"]
+```
+
+These values correspond to what you’d find in a typical Leboncoin URL, like:
+
+```
+https://www.leboncoin.fr/recherche?category=9&text=maison&...&real_estate_type=3,4
+```
+
+Here's a complete example of a search query:
+
+```python
+client.search(
+    text="maison",
+    locations=[location],
+    page=1,
+    limit=35,
+    limit_alu=0,
+    sort=lbc.Sort.NEWEST,
+    ad_type=lbc.AdType.OFFER,
+    category=lbc.Category.IMMOBILIER,
+    owner_type=lbc.OwnerType.ALL,
+    search_in_title_only=True,
+    square=[200, 400],
+    price=[300_000, 700_000],
+)
+```
+
+### Location
+
+The `locations` parameter accepts a list of one or more location objects. You can use one of the following:
+
+* `lbc.Region(...)`
+* `lbc.Department(...)`
+* `lbc.City(...)`
+
+Each one corresponds to a different level of geographic granularity.
+
+#### City example
+
+```python
+location = lbc.City(
+    lat=48.85994982004764,
+    lng=2.33801967847424,
+    radius=10_000,  # in meters
+    city="Paris"
+)
+```
+
+#### Region / Department example
+
+```python
+from lbc import Region, Department
+
+region = Region.ILE_DE_FRANCE
+department = Department.PARIS
+```
+
+### 403 Error
+
+If you encounter a **403 Forbidden** error, it usually means your requests are being blocked by [Datadome](https://datadome.co).
+To resolve this:
+
+* Try reducing the request frequency (add delays between requests).
+* If you're using a proxy, make sure it is **clean** and preferably located in **France**.
+
+Using residential or mobile proxies can also help avoid detection.
+
+## License
+
+This project is licensed under the MIT License.
+
+## Support
+
+<a href="https://www.buymeacoffee.com/etienneh" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+You can contact me via [Telegram](https://t.me/etienne_hd) or [Discord](https://discord.com/users/1153975318990827552) if you need help with scraping services or want to write a library.

lbc-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "lbc"
+version = "1.0.0"
+description = "Unofficial client for Leboncoin API"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+
+authors = [
+  {name = "Etienne HODE", email = "hode.etienne@gmail.com"}
+]
+maintainers = [
+  {name = "Etienne HODE", email = "hode.etienne@gmail.com"}
+]
+
+dependencies = [
+  "curl_cffi==0.11.3"
+]
+
+keywords = ["lbc", "leboncoin", "wrapper", "api"]
+
+[project.urls]
+Homepage = "https://github.com/etienne-hd/lbc-py"
+Repository = "https://github.com/etienne-hd/lbc-py"
+Changelog = "https://github.com/etienne-hd/lbc-py/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

lbc-1.0.0/requirements.txt

@@ -0,0 +1 @@
+curl_cffi==0.11.3

lbc-1.0.0/src/lbc/__init__.py

@@ -0,0 +1,2 @@
+from .client import Client
+from .models import *

lbc-1.0.0/src/lbc/client.py

@@ -0,0 +1,85 @@
+from .session import Session
+from .models import Proxy, Search, Category, AdType, OwnerType, Sort, Region, Department, City
+from .exceptions import DatadomeError, RequestError
+from .utils import build_search_payload_with_args
+
+from typing import Optional, List, Union
+
+class Client(Session):
+    def __init__(self, proxy: Optional[Proxy] = None):
+        super().__init__(proxy=proxy)
+
+    def _fetch(self, method: str, url: str, payload: Optional[dict] = None, timeout: int = 30) -> dict:
+        """
+        Internal method to send an HTTP request using the configured session.
+
+        Args:
+            method (staticmethod): HTTP method to use (e.g., `GET`, `POST`).
+            url (str): Full URL of the API endpoint.
+            payload (Optional[dict], optional): JSON payload to send with the request. Used for POST/PUT methods. Defaults to None.
+            timeout (int, optional): Timeout for the request, in seconds. Defaults to 30.
+
+        Raises:
+            DatadomeError: Raised when the request is blocked by Datadome protection (HTTP 403).
+            RequestError: Raised for any other non-successful HTTP response.
+
+        Returns:
+            dict: Parsed JSON response from the server.
+        """
+        response = self.session.request(
+            method=method,
+            url=url, 
+            json=payload,
+            timeout=timeout
+        )
+        if response.ok:
+            return response.json()
+        elif response.status_code == 403:
+            if self.proxy:
+                raise DatadomeError(f"Access blocked by Datadome: your proxy appears to have a poor reputation, try to change it.")
+            else:
+                raise DatadomeError(f"Access blocked by Datadome: your activity was flagged as suspicious. Please avoid sending excessive requests.")
+        else:
+            raise RequestError(f"Request failed with status code {response.status_code}.")
+
+    def search(
+        self,
+        text: Optional[str] = None,
+        category: Category = Category.TOUTES_CATEGORIES,
+        sort: Sort = Sort.RELEVANCE,
+        locations: Optional[Union[List[Union[Region, Department, City]], Union[Region, Department, City]]] = None, 
+        limit: int = 35, 
+        limit_alu: int = 3, 
+        page: int = 1, 
+        ad_type: AdType = AdType.OFFER,
+        owner_type: Optional[OwnerType] = None,
+        search_in_title_only: bool = False,
+        **kwargs
+    ) -> Search:
+        """
+        Perform a classified ads search on Leboncoin with the specified criteria.
+
+        Args:
+            text (Optional[str], optional): Search keywords. If None, returns all matching ads without filtering by keyword. Defaults to None.
+            category (Category, optional): Category to search in. Defaults to Category.TOUTES_CATEGORIES.
+            sort (Sort, optional): Sorting method for results (e.g., relevance, date, price). Defaults to Sort.RELEVANCE.
+            locations (Optional[Union[List[Union[Region, Department, City]], Union[Region, Department, City]]], optional): One or multiple locations (region, department, or city) to filter results. Defaults to None.
+            limit (int, optional): Maximum number of results to return. Defaults to 35.
+            limit_alu (int, optional): Number of ALU (Annonces Lu / similar ads) suggestions to include. Defaults to 3.
+            page (int, optional): Page number to retrieve for paginated results. Defaults to 1.
+            ad_type (AdType, optional): Type of ad (offer or request). Defaults to AdType.OFFER.
+            owner_type (Optional[OwnerType], optional): Filter by seller type (individual, professional, or all). Defaults to None.
+            search_in_title_only (bool, optional): If True, search will only be performed on ad titles. Defaults to False.
+            **kwargs: Additional advanced filters such as price range (`price=(min, max)`), surface area (`square=(min, max)`), property type, and more.
+
+        Returns:
+            Search: A `Search` object containing the parsed search results.
+        """
+        payload = build_search_payload_with_args(
+            text=text, category=category, sort=sort, locations=locations, 
+            limit=limit, limit_alu=limit_alu, page=page, ad_type=ad_type,
+            owner_type=owner_type, search_in_title_only=search_in_title_only, **kwargs
+        )
+
+        body = self._fetch(method="POST", url="https://api.leboncoin.fr/finder/search", payload=payload)
+        return Search.build(raw=body)

lbc-1.0.0/src/lbc/exceptions.py

@@ -0,0 +1,14 @@
+class LBCError(Exception):
+    """Base exception for all errors raised by the LBC client."""
+
+
+class InvalidValue(LBCError):
+    """Raised when a provided value is invalid or improperly formatted."""
+
+
+class RequestError(LBCError):
+    """Raised when an HTTP request fails with a non-success status code."""
+
+
+class DatadomeError(RequestError):
+    """Raised when access is blocked by Datadome anti-bot protection."""

lbc-1.0.0/src/lbc/models/__init__.py

@@ -0,0 +1,4 @@
+from .proxy import Proxy
+from .search import Search
+from .enums import *
+from .city import City