lbc 1.0.0__py3-none-any.whl

lbc/__init__.py

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

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/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/models/__init__.py

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

lbc/models/ad.py

@@ -0,0 +1,32 @@
+from .attribute import Attribute
+from .location import Location
+from .owner import Owner
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List
+
+@dataclass
+class Ad:
+    id: int
+    first_publication_date: datetime
+    expiration_date: datetime
+    index_date: datetime
+    status: str
+    category_id: str
+    category_name: str
+    subject: str
+    body: str
+    brand: str
+    ad_type: str
+    url: str
+    price: float
+    images: List[str]
+    attributes: List[Attribute]
+    location: Location
+    owner: Owner
+    has_phone: bool
+
+    @property
+    def title(self) -> str:
+        return self.subject

lbc/models/attribute.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from typing import Optional, List
+
+@dataclass
+class Attribute:
+    key: str
+    key_label: Optional[str]
+    value: str
+    value_label: str
+    values: List[str]
+    values_label: Optional[List[str]]
+    value_label_reader: Optional[str]
+    generic: bool

lbc/models/city.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class City:
+    lat: float
+    lng: float
+    radius: int = 10_000
+    city: Optional[str] = None

lbc/models/enums.py

@@ -0,0 +1,267 @@
+from enum import Enum
+from typing import Union, Tuple
+
+class OwnerType(Enum):
+    PRO = "pro"
+    PRIVATE = "private"
+    ALL = "all"
+
+class AdType(Enum):
+    OFFER = "offer"
+    DEMAND = "demand"
+
+class Sort(Enum):
+    RELEVANCE = ("relevance", None)
+    NEWEST = ("time", "desc")
+    OLDEST = ("time", "asc")
+    EXPENSIVE = ("price", "asc")
+    CHEAPEST = ("price", "desc")
+
+class Department(Enum):
+    BAS_RHIN = ("1", "ALSACE", "67", "BAS_RHIN")
+    HAUT_RHIN = ("1", "ALSACE", "68", "HAUT_RHIN")
+    DORDOGNE = ("2", "AQUITAINE", "24", "DORDOGNE")
+    GIRONDE = ("2", "AQUITAINE", "33", "GIRONDE")
+    LANDES = ("2", "AQUITAINE", "40", "LANDES")
+    LOT_ET_GARONNE = ("2", "AQUITAINE", "47", "LOT_ET_GARONNE")
+    PYRENEES_ATLANTIQUES = ("2", "AQUITAINE", "64", "PYRENEES_ATLANTIQUES")
+    ALLIER = ("3", "AUVERGNE", "3", "ALLIER")
+    CANTAL = ("3", "AUVERGNE", "15", "CANTAL")
+    HAUTE_LOIRE = ("3", "AUVERGNE", "43", "HAUTE_LOIRE")
+    PUY_DE_DOME = ("3", "AUVERGNE", "63", "PUY_DE_DOME")
+    CALVADOS = ("4", "BASSE_NORMANDIE", "14", "CALVADOS")
+    MANCHE = ("4", "BASSE_NORMANDIE", "50", "MANCHE")
+    ORNE = ("4", "BASSE_NORMANDIE", "61", "ORNE")
+    COTE_DOR = ("5", "BOURGOGNE", "21", "COTE_DOR")
+    NIEVRE = ("5", "BOURGOGNE", "58", "NIEVRE")
+    SAONE_ET_LOIRE = ("5", "BOURGOGNE", "71", "SAONE_ET_LOIRE")
+    YONNE = ("5", "BOURGOGNE", "89", "YONNE")
+    COTES_DARMOR = ("6", "BRETAGNE", "22", "COTES_DARMOR")
+    FINISTERE = ("6", "BRETAGNE", "29", "FINISTERE")
+    ILLE_ET_VILAINE = ("6", "BRETAGNE", "35", "ILLE_ET_VILAINE")
+    MORBIHAN = ("6", "BRETAGNE", "56", "MORBIHAN")
+    CHER = ("7", "CENTRE", "18", "CHER")
+    EURE_ET_LOIR = ("7", "CENTRE", "28", "EURE_ET_LOIR")
+    INDRE = ("7", "CENTRE", "36", "INDRE")
+    INDRE_ET_LOIRE = ("7", "CENTRE", "37", "INDRE_ET_LOIRE")
+    LOIR_ET_CHER = ("7", "CENTRE", "41", "LOIR_ET_CHER")
+    LOIRET = ("7", "CENTRE", "45", "LOIRET")
+    ARDENNES = ("8", "CHAMPAGNE_ARDENNE", "8", "ARDENNES")
+    AUBE = ("8", "CHAMPAGNE_ARDENNE", "10", "AUBE")
+    MARNE = ("8", "CHAMPAGNE_ARDENNE", "51", "MARNE")
+    HAUTE_MARNE = ("8", "CHAMPAGNE_ARDENNE", "52", "HAUTE_MARNE")
+    DOUBS = ("10", "FRANCHE_COMTE", "25", "DOUBS")
+    JURA = ("10", "FRANCHE_COMTE", "39", "JURA")
+    HAUTE_SAONE = ("10", "FRANCHE_COMTE", "70", "HAUTE_SAONE")
+    TERRITOIRE_DE_BELFORT = ("10", "FRANCHE_COMTE", "90", "TERRITOIRE_DE_BELFORT")
+    EURE = ("11", "HAUTE_NORMANDIE", "27", "EURE")
+    SEINE_MARITIME = ("11", "HAUTE_NORMANDIE", "76", "SEINE_MARITIME")
+    PARIS = ("12", "ILE_DE_FRANCE", "75", "PARIS")
+    SEINE_ET_MARNE = ("12", "ILE_DE_FRANCE", "77", "SEINE_ET_MARNE")
+    YVELINES = ("12", "ILE_DE_FRANCE", "78", "YVELINES")
+    ESSONNE = ("12", "ILE_DE_FRANCE", "91", "ESSONNE")
+    HAUTS_DE_SEINE = ("12", "ILE_DE_FRANCE", "92", "HAUTS_DE_SEINE")
+    SEINE_SAINT_DENIS = ("12", "ILE_DE_FRANCE", "93", "SEINE_SAINT_DENIS")
+    VAL_DE_MARNE = ("12", "ILE_DE_FRANCE", "94", "VAL_DE_MARNE")
+    VAL_DOISE = ("12", "ILE_DE_FRANCE", "95", "VAL_DOISE")
+    AUDE = ("13", "LANGUEDOC_ROUSSILLON", "11", "AUDE")
+    GARD = ("13", "LANGUEDOC_ROUSSILLON", "30", "GARD")
+    HERAULT = ("13", "LANGUEDOC_ROUSSILLON", "34", "HERAULT")
+    LOZERE = ("13", "LANGUEDOC_ROUSSILLON", "48", "LOZERE")
+    PYRENEES_ORIENTALES = ("13", "LANGUEDOC_ROUSSILLON", "66", "PYRENEES_ORIENTALES")
+    CORREZE = ("14", "LIMOUSIN", "19", "CORREZE")
+    CREUSE = ("14", "LIMOUSIN", "23", "CREUSE")
+    HAUTE_VIENNE = ("14", "LIMOUSIN", "87", "HAUTE_VIENNE")
+    MEURTHE_ET_MOSELLE = ("15", "LORRAINE", "54", "MEURTHE_ET_MOSELLE")
+    MEUSE = ("15", "LORRAINE", "55", "MEUSE")
+    MOSELLE = ("15", "LORRAINE", "57", "MOSELLE")
+    VOSGES = ("15", "LORRAINE", "88", "VOSGES")
+    ARIEGE = ("16", "MIDI_PYRENEES", "9", "ARIEGE")
+    AVEYRON = ("16", "MIDI_PYRENEES", "12", "AVEYRON")
+    HAUTE_GARONNE = ("16", "MIDI_PYRENEES", "31", "HAUTE_GARONNE")
+    GERS = ("16", "MIDI_PYRENEES", "32", "GERS")
+    LOT = ("16", "MIDI_PYRENEES", "46", "LOT")
+    HAUTES_PYRENEES = ("16", "MIDI_PYRENEES", "65", "HAUTES_PYRENEES")
+    TARN = ("16", "MIDI_PYRENEES", "81", "TARN")
+    TARN_ET_GARONNE = ("16", "MIDI_PYRENEES", "82", "TARN_ET_GARONNE")
+    NORD = ("17", "NORD_PAS_DE_CALAIS", "59", "NORD")
+    PAS_DE_CALAIS = ("17", "NORD_PAS_DE_CALAIS", "62", "PAS_DE_CALAIS")
+    LOIRE_ATLANTIQUE = ("18", "PAYS_DE_LA_LOIRE", "44", "LOIRE_ATLANTIQUE")
+    MAINE_ET_LOIRE = ("18", "PAYS_DE_LA_LOIRE", "49", "MAINE_ET_LOIRE")
+    MAYENNE = ("18", "PAYS_DE_LA_LOIRE", "53", "MAYENNE")
+    SARTHE = ("18", "PAYS_DE_LA_LOIRE", "72", "SARTHE")
+    VENDEE = ("18", "PAYS_DE_LA_LOIRE", "85", "VENDEE")
+    AISNE = ("19", "PICARDIE", "2", "AISNE")
+    OISE = ("19", "PICARDIE", "60", "OISE")
+    SOMME = ("19", "PICARDIE", "80", "SOMME")
+    CHARENTE = ("20", "POITOU_CHARENTES", "16", "CHARENTE")
+    CHARENTE_MARITIME = ("20", "POITOU_CHARENTES", "17", "CHARENTE_MARITIME")
+    DEUX_SEVRES = ("20", "POITOU_CHARENTES", "79", "DEUX_SEVRES")
+    VIENNE = ("20", "POITOU_CHARENTES", "86", "VIENNE")
+    ALPES_DE_HAUTE_PROVENCE = ("21", "PROVENCE_ALPES_COTE_DAZUR", "4", "ALPES_DE_HAUTE_PROVENCE")
+    HAUTES_ALPES = ("21", "PROVENCE_ALPES_COTE_DAZUR", "5", "HAUTES_ALPES")
+    ALPES_MARITIMES = ("21", "PROVENCE_ALPES_COTE_DAZUR", "6", "ALPES_MARITIMES")
+    BOUCHES_DU_RHONE = ("21", "PROVENCE_ALPES_COTE_DAZUR", "13", "BOUCHES_DU_RHONE")
+    VAR = ("21", "PROVENCE_ALPES_COTE_DAZUR", "83", "VAR")
+    VAUCLUSE = ("21", "PROVENCE_ALPES_COTE_DAZUR", "84", "VAUCLUSE")
+    AIN = ("22", "RHONE_ALPES", "1", "AIN")
+    ARDECHE = ("22", "RHONE_ALPES", "7", "ARDECHE")
+    DROME = ("22", "RHONE_ALPES", "26", "DROME")
+    ISERE = ("22", "RHONE_ALPES", "38", "ISERE")
+    LOIRE = ("22", "RHONE_ALPES", "42", "LOIRE")
+    RHONE = ("22", "RHONE_ALPES", "69", "RHONE")
+    SAVOIE = ("22", "RHONE_ALPES", "73", "SAVOIE")
+    HAUTE_SAVOIE = ("22", "RHONE_ALPES", "74", "HAUTE_SAVOIE")
+
+class Region(Enum):
+    ALSACE = ("1", "ALSACE")
+    AQUITAINE = ("2", "AQUITAINE")
+    AUVERGNE = ("3", "AUVERGNE")
+    AUVERGNE_RHONE_ALPES = ("30", "AUVERGNE_RHONE_ALPES")
+    BASSE_NORMANDIE = ("4", "BASSE_NORMANDIE")
+    BOURGOGNE = ("5", "BOURGOGNE")
+    BOURGOGNE_FRANCHE_COMTE = ("31", "BOURGOGNE_FRANCHE_COMTE")
+    BRETAGNE = ("6", "BRETAGNE")
+    CENTRE = ("7", "CENTRE")
+    CENTRE_VAL_DE_LOIRE = ("37", "CENTRE_VAL_DE_LOIRE")
+    CHAMPAGNE_ARDENNE = ("8", "CHAMPAGNE_ARDENNE")
+    CORSE = ("9", "CORSE")
+    FRANCHE_COMTE = ("10", "FRANCHE_COMTE")
+    GRAND_EST = ("33", "GRAND_EST")
+    GUADELOUPE = ("23", "GUADELOUPE")
+    GUYANE = ("25", "GUYANE")
+    HAUTE_NORMANDIE = ("11", "HAUTE_NORMANDIE")
+    HAUTS_DE_FRANCE = ("32", "HAUTS_DE_FRANCE")
+    ILE_DE_FRANCE = ("12", "ILE_DE_FRANCE")
+    LANGUEDOC_ROUSSILLON = ("13", "LANGUEDOC_ROUSSILLON")
+    LIMOUSIN = ("14", "LIMOUSIN")
+    LORRAINE = ("15", "LORRAINE")
+    MARTINIQUE = ("24", "MARTINIQUE")
+    MIDI_PYRENEES = ("16", "MIDI_PYRENEES")
+    NORD_PAS_DE_CALAIS = ("17", "NORD_PAS_DE_CALAIS")
+    NORMANDIE = ("34", "NORMANDIE")
+    NOUVELLE_AQUITAINE = ("35", "NOUVELLE_AQUITAINE")
+    OCCITANIE = ("36", "OCCITANIE")
+    PAYS_DE_LA_LOIRE = ("18", "PAYS_DE_LA_LOIRE")
+    PICARDIE = ("19", "PICARDIE")
+    POITOU_CHARENTES = ("20", "POITOU_CHARENTES")
+    PROVENCE_ALPES_COTE_DAZUR = ("21", "PROVENCE_ALPES_COTE_DAZUR")
+    RHONE_ALPES = ("22", "RHONE_ALPES")
+    REUNION = ("26", "REUNION")
+
+class Category(Enum):
+    TOUTES_CATEGORIES = "0"
+    EMPLOI = "71"
+    EMPLOI_OFFRES_DEMPLOI = "33"
+    EMPLOI_FORMATIONS_PROFESSIONNELLES = "74"
+    VEHICULES = "1"
+    VEHICULES_VOITURES = "2"
+    VEHICULES_MOTOS = "3"
+    VEHICULES_CARAVANING = "4"
+    VEHICULES_UTILITAIRES = "5"
+    VEHICULES_CAMIONS = "300"
+    VEHICULES_NAUTISME = "7"
+    VEHICULES_VELOS = "1002"
+    VEHICULES_EQUIPEMENT_AUTO = "6"
+    VEHICULES_EQUIPEMENT_MOTO = "44"
+    VEHICULES_EQUIPEMENT_CARAVANING = "50"
+    VEHICULES_EQUIPEMENT_NAUTISME = "51"
+    VEHICULES_EQUIPEMENTS_VELOS = "1003"
+    VEHICULES_SERVICES_DE_REPARATIONS_MECANIQUES = "1004"
+    IMMOBILIER = "8"
+    IMMOBILIER_VENTES_IMMOBILIERES = "9"
+    IMMOBILIER_LOCATIONS = "10"
+    IMMOBILIER_COLOCATIONS = "11"
+    IMMOBILIER_BUREAUX_ET_COMMERCES = "13"
+    IMMOBILIER_IMMOBILIER_NEUF = "304"
+    IMMOBILIER_SERVICES_DE_DEMENAGEMENT = "1001"
+    LOCATIONS_DE_VACANCES = "66"
+    LOCATIONS_DE_VACANCES_LOCATIONS_SAISONNIERES = "12"
+    ELECTRONIQUE = "14"
+    ELECTRONIQUE_ORDINATEURS = "15"
+    ELECTRONIQUE_ACCESSOIRES_INFORMATIQUE = "83"
+    ELECTRONIQUE_TABLETTES_ET_LISEUSES = "82"
+    ELECTRONIQUE_PHOTO_AUDIO_ET_VIDEO = "16"
+    ELECTRONIQUE_TELEPHONES_ET_OBJETS_CONNECTES = "17"
+    ELECTRONIQUE_ACCESSOIRES_TELEPHONE_ET_OBJETS_CONNECTES = "81"
+    ELECTRONIQUE_CONSOLES = "43"
+    ELECTRONIQUE_JEUX_VIDEO = "84"
+    ELECTRONIQUE_ELECTROMENAGER = "1006"
+    ELECTRONIQUE_SERVICES_DE_REPARATIONS_ELECTRONIQUES = "1007"
+    MAISON_ET_JARDIN = "18"
+    MAISON_ET_JARDIN_AMEUBLEMENT = "19"
+    MAISON_ET_JARDIN_PAPETERIE_ET_FOURNITURES_SCOLAIRES = "96"
+    MAISON_ET_JARDIN_ELECTROMENAGER = "20"
+    MAISON_ET_JARDIN_ARTS_DE_LA_TABLE = "45"
+    MAISON_ET_JARDIN_DECORATION = "39"
+    MAISON_ET_JARDIN_LINGE_DE_MAISON = "46"
+    MAISON_ET_JARDIN_BRICOLAGE = "21"
+    MAISON_ET_JARDIN_JARDIN_ET_PLANTES = "52"
+    MAISON_ET_JARDIN_SERVICES_DE_JARDINERIE_ET_BRICOLAGE = "1005"
+    FAMILLE = "79"
+    FAMILLE_EQUIPEMENT_BEBE = "23"
+    FAMILLE_MOBILIER_ENFANT = "80"
+    FAMILLE_VETEMENTS_BEBE = "54"
+    FAMILLE_VETEMENTS_ENFANTS = "1011"
+    FAMILLE_VETEMENTS_MATERNITE = "1012"
+    FAMILLE_CHAUSSURES_ENFANTS = "1013"
+    FAMILLE_MONTRES_ET_BIJOUX_ENFANTS = "1014"
+    FAMILLE_ACCESSOIRES_ET_BAGAGERIE_ENFANTS = "1015"
+    FAMILLE_JEUX_ET_JOUETS = "1016"
+    FAMILLE_BABY_SITTING = "1017"
+    MODE = "72"
+    MODE_VETEMENTS = "22"
+    MODE_CHAUSSURES = "53"
+    MODE_ACCESSOIRES_ET_BAGAGERIE = "47"
+    MODE_MONTRES_ET_BIJOUX = "42"
+    LOISIRS = "24"
+    LOISIRS_ANTIQUITES = "89"
+    LOISIRS_ARTISTES_ET_MUSICIENS = "1008"
+    LOISIRS_BILLETTERIE = "1009"
+    LOISIRS_COLLECTION = "40"
+    LOISIRS_CD_MUSIQUE = "26"
+    LOISIRS_DVD_FILMS = "25"
+    LOISIRS_INSTRUMENTS_DE_MUSIQUE = "30"
+    LOISIRS_LIVRES = "27"
+    LOISIRS_MODELISME = "86"
+    LOISIRS_VINS_ET_GASTRONOMIE = "48"
+    LOISIRS_JEUX_ET_JOUETS = "41"
+    LOISIRS_LOISIRS_CREATIFS = "88"
+    LOISIRS_SPORT_ET_PLEIN_AIR = "29"
+    LOISIRS_VELOS = "55"
+    LOISIRS_EQUIPEMENTS_VELOS = "85"
+    ANIMAUX = "75"
+    ANIMAUX_ANIMAUX = "28"
+    ANIMAUX_ACCESSOIRES_ANIMAUX = "76"
+    ANIMAUX_ANIMAUX_PERDUS = "77"
+    ANIMAUX_SERVICES_AUX_ANIMAUX = "1010"
+    MATERIEL_PROFESSIONNEL = "56"
+    MATERIEL_PROFESSIONNEL_TRACTEURS = "105"
+    MATERIEL_PROFESSIONNEL_MATERIEL_AGRICOLE = "57"
+    MATERIEL_PROFESSIONNEL_BTP_CHANTIER_GROS_OEUVRE = "59"
+    MATERIEL_PROFESSIONNEL_POIDS_LOURDS = "106"
+    MATERIEL_PROFESSIONNEL_MANUTENTION_LEVAGE = "58"
+    MATERIEL_PROFESSIONNEL_EQUIPEMENTS_INDUSTRIELS = "32"
+    MATERIEL_PROFESSIONNEL_EQUIPEMENTS_POUR_RESTAURANTS_ET_HOTELS = "61"
+    MATERIEL_PROFESSIONNEL_EQUIPEMENTS_ET_FOURNITURES_DE_BUREAU = "62"
+    MATERIEL_PROFESSIONNEL_EQUIPEMENTS_POUR_COMMERCES_ET_MARCHES = "63"
+    MATERIEL_PROFESSIONNEL_MATERIEL_MEDICAL = "64"
+    SERVICES = "31"
+    SERVICES_ARTISTES_ET_MUSICIENS = "101"
+    SERVICES_BABY_SITTING = "100"
+    SERVICES_BILLETTERIE = "35"
+    SERVICES_COVOITURAGE = "65"
+    SERVICES_COURS_PARTICULIERS = "36"
+    SERVICES_ENTRAIDE_ENTRE_VOISINS = "103"
+    SERVICES_EVENEMENTS = "49"
+    SERVICES_SERVICES_A_LA_PERSONNE = "99"
+    SERVICES_SERVICES_AUX_ANIMAUX = "102"
+    SERVICES_SERVICES_DE_DEMENAGEMENT = "92"
+    SERVICES_SERVICES_DE_REPARATIONS_ELECTRONIQUES = "95"
+    SERVICES_SERVICES_DE_REPARATIONS_MECANIQUES = "93"
+    SERVICES_SERVICES_DE_JARDINERIE_ET_BRICOLAGE = "97"
+    SERVICES_SERVICES_EVENEMENTIELS = "98"
+    SERVICES_AUTRES_SERVICES = "34"
+    DONS = "1000"
+    DIVERS = "37"
+    DIVERS_AUTRES = "38"

lbc/models/location.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+@dataclass
+class Location:
+    country_id: str
+    region_id: str
+    region_name: str
+    department_id: str
+    department_name: str
+    city_label: str
+    city: str
+    zipcode: str
+    lat: float
+    lng: float
+    source: str
+    provider: str
+    is_shape: bool

lbc/models/owner.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+@dataclass
+class Owner:
+    store_id: str
+    user_id: str
+    type: str
+    name: str
+    no_salesmen: bool

lbc/models/proxy.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from typing import Union, Optional
+
+@dataclass
+class Proxy:
+    host: str
+    port: Union[str, int]
+    username: Optional[str] = None
+    password: Optional[str] = None
+
+    @property
+    def url(self):
+        if self.username and self.password:
+            return f"http://{self.username}:{self.password}@{self.host}:{self.port}"
+        else:
+            return f"http://{self.host}:{self.port}"

lbc/models/search.py

@@ -0,0 +1,101 @@
+from .ad import Ad
+from .attribute import Attribute
+from .location import Location
+from .owner import Owner
+
+from dataclasses import dataclass
+from typing import List
+from datetime import datetime
+
+@dataclass
+class Search:
+    total: int
+    total_all: int
+    total_pro: int
+    total_private: int
+    total_active: int
+    total_inactive: int
+    total_shippable: int
+    max_pages: int
+    ads: List[Ad]
+
+    @staticmethod
+    def build(raw: dict) -> "Search":
+        ads: List[Ad] = []
+
+        for raw_ad in raw.get("ads", []):
+            attributes: List[Attribute] = []
+            for raw_attribute in raw_ad.get("attributes", []):
+                attributes.append(
+                    Attribute(
+                        key=raw_attribute.get("key"),
+                        key_label=raw_attribute.get("key_label"),
+                        value=raw_attribute.get("value"),
+                        value_label=raw_attribute.get("value_label"),
+                        values=raw_attribute.get("values"),
+                        values_label=raw_attribute.get("values_label"),
+                        value_label_reader=raw_attribute.get("value_label_reader"),
+                        generic=raw_attribute.get("generic")
+                    )
+                )
+
+            raw_location: dict = raw.get("location", {})
+            location = Location(
+                country_id=raw_location.get("country_id"),
+                region_id=raw_location.get("region_id"),
+                region_name=raw_location.get("region_name"),
+                department_id=raw_location.get("department_id"),
+                department_name=raw_location.get("department_name"),
+                city_label=raw_location.get("city_label"),
+                city=raw_location.get("city"),
+                zipcode=raw_location.get("zipcode"),
+                lat=raw_location.get("lat"),
+                lng=raw_location.get("lng"),
+                source=raw_location.get("source"),
+                provider=raw_location.get("provider"),
+                is_shape=raw_location.get("is_shape")
+            )
+
+            raw_owner: dict = raw.get("owner", {})
+            owner = Owner(
+                store_id=raw_owner.get("store_id"),
+                user_id=raw_owner.get("user_id"),
+                type=raw_owner.get("type"),
+                name=raw_owner.get("name"),
+                no_salesmen=raw_owner.get("no_salesmen")
+            )
+
+            ads.append(
+                Ad(
+                    id=raw_ad.get("list_id"),
+                    first_publication_date=datetime.strptime(raw_ad.get("first_publication_date"), "%Y-%m-%d %H:%M:%S") if raw_ad.get("first_publication_date") else None,
+                    expiration_date=datetime.strptime(raw_ad.get("expiration_date"), "%Y-%m-%d %H:%M:%S") if raw_ad.get("expiration_date") else None,
+                    index_date=datetime.strptime(raw_ad.get("index_date"), "%Y-%m-%d %H:%M:%S") if raw_ad.get("index_date") else None,
+                    status=raw_ad.get("status"),
+                    category_id=raw_ad.get("category_id"),
+                    category_name=raw_ad.get("category_name"),
+                    subject=raw_ad.get("subject"),
+                    body=raw_ad.get("body"),
+                    brand=raw_ad.get("brand"),
+                    ad_type=raw_ad.get("ad_type"),
+                    url=raw_ad.get("url"),
+                    price=raw_ad.get("price_cents") / 100 if raw_ad.get("price_cents") else None,
+                    images=raw_ad.get("images", {}).get("urls_large"),
+                    attributes=attributes,
+                    location=location,
+                    owner=owner,
+                    has_phone=raw_ad.get("has_phone")
+                )
+            )
+
+        return Search(
+            total=raw.get("total"),
+            total_all=raw.get("total_all"),
+            total_pro=raw.get("total_pro"),
+            total_private=raw.get("total_private"),
+            total_active=raw.get("total_active"),
+            total_inactive=raw.get("total_inactive"),
+            total_shippable=raw.get("total_shippable"),
+            max_pages=raw.get("max_pages"),
+            ads=ads
+        )

lbc/session.py

@@ -0,0 +1,39 @@
+from .models import Proxy
+
+from curl_cffi import requests
+from typing import Optional
+
+class Session:
+    def __init__(self, proxy: Optional[Proxy] = None):
+        self._session = self._init_session(proxy=proxy)
+        self._proxy = proxy
+
+    def _init_session(self, proxy: Optional[Proxy] = None) -> requests.Session:
+        """
+        Initializes an HTTP session with optional proxy and browser impersonation.
+
+        Args:
+            proxy (Optional[Proxy], optional): Proxy configuration to use for the session. If provided, it will be applied to both HTTP and HTTPS traffic.
+
+        Returns:
+            requests.Session: A configured session instance ready to send requests.
+        """
+        session = requests.Session(
+            impersonate="firefox",
+        )
+
+        if proxy:
+            session.proxies = {
+                "http": proxy.url,
+                "https": proxy.url
+            }
+
+        return session
+
+    @property
+    def session(self):
+        return self._session
+    
+    @property
+    def proxy(self):
+        return self._proxy

lbc/utils.py

@@ -0,0 +1,126 @@
+from .models import Category, AdType, OwnerType, Sort, Region, Department, City
+from .exceptions import InvalidValue
+
+from typing import Optional, Union, List
+
+def build_search_payload_with_args(
+    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
+) -> dict:
+    payload = {
+        "filters": {
+            "category": {
+                "id": category.value
+            },
+            "enums": {
+                "ad_type": [
+                    ad_type.value
+                ]
+            },
+            "keywords": {
+                "text": text
+            },
+            "location": {}
+        },
+        "limit": limit,
+        "limit_alu": limit_alu,
+        "offset": limit * (page - 1),
+        "disable_total": True,
+        "extend": True,
+        "listing_source": "direct-search" if page == 1 else "pagination"
+    }   
+
+    # Text
+    if text:
+        payload["filters"]["keywords"] = {
+            "text": text
+        }  
+
+    # Owner Type
+    if owner_type:
+        payload["owner_type"] = owner_type.value
+
+    # Sort
+    sort_by, sort_order = sort.value
+    payload["sort_by"] = sort_by
+    if sort_order:
+        payload["sort_order"] = sort_order
+        
+    # Location
+    if locations and not isinstance(locations, list):
+        locations = [locations]
+        
+    if locations:
+        payload["filters"]["location"] = {
+            "locations": []
+        }
+        for location in locations:
+            match location:
+                case Region():
+                    payload["filters"]["location"]["locations"].append(
+                        {
+                            "locationType": "region",
+                            "region_id": location.value[0]
+                        }
+                    )
+                case Department():
+                    payload["filters"]["location"]["locations"].append(
+                        {
+                            "locationType": "department",
+                            "region_id": location.value[0],
+                            "department_id": location.value[2]
+                        }
+                    )
+                case City():
+                    payload["filters"]["location"]["locations"].append(
+                        {
+                            "area": {
+                                "lat": location.lat,
+                                "lng": location.lng,
+                                "radius": location.radius
+                            },
+                            "city": location.city,
+                            "label": f"{location.city} (toute la ville)" if location.city else None,
+                            "locationType": "city"
+                        }
+                    )
+                case _:
+                    raise InvalidValue("The provided location is invalid. It must be an instance of Region, Department, or City.")
+
+    # Search in title only
+    if text:
+        if search_in_title_only:
+            payload["filters"]["keywords"]["type"] = "subject"  
+
+    if kwargs:
+        for key, value in kwargs.items():
+            if not isinstance(value, (list, tuple)):
+                raise InvalidValue(f"The value of '{key}' must be a list or a tuple.")  
+            # Range
+            if all(isinstance(x, int) for x in value):
+                if len(value) == 1:
+                    raise InvalidValue(f"The value of '{key}' must be a list or tuple with at least two elements.")
+
+                if not "ranges" in payload["filters"]:
+                    payload["filters"]["ranges"] = {}
+
+                payload["filters"]["ranges"][key] = {
+                    "min": value[0],
+                    "max": value[1]
+                }   
+            # Enum
+            elif all(isinstance(x, str) for x in value):
+                payload["filters"]["enums"]["key"] = value
+            else:
+                raise InvalidValue(f"The value of '{key}' must be a list or tuple containing only integers or only strings.")
+
+    return payload

lbc-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+lbc/__init__.py,sha256=eX6byBwXr1WwoIUziH6rXJtjvbU6niBqQtYZRJyTsnk,48
+lbc/client.py,sha256=oiay3h_4pRD4To5u5qsBko4XdsxrlueP6LMuI8-qQbk,4484
+lbc/exceptions.py,sha256=CL0WSsVhyzSuwa6GEoPSZ2dMERGp-QaqBKth28kXbXQ,418
+lbc/session.py,sha256=9r4-e1G5kRzg3rSp5bzrPT8rfWWNvwy4ZmgNdRigSFs,1074
+lbc/utils.py,sha256=kITzURYaWHSjisINybRAPYsivwzNW6rLGAMweoC4Wwg,4367
+lbc/models/__init__.py,sha256=yoHpH997lhFBFXI7-_E_Vh1-RZ9QqSot_VkSXw39jQk,95
+lbc/models/ad.py,sha256=IPPbpgKtH_HNvlQhsVQg6zSTQqvMunM7-l4TsHyl9-E,641
+lbc/models/attribute.py,sha256=wfWUKKQpkXOrOKklOx5rGuvG2gjtyxTncmRzvtTFlGw,290
+lbc/models/city.py,sha256=N9xdmYiI1tLfB4xTHfuilY9x9NzmIhzRho-GpUxm194,171
+lbc/models/enums.py,sha256=mKVC-l-l9sUW1uEnaOAQPQtXLVb0qwfCiTTbKGbbvAw,11831
+lbc/models/location.py,sha256=xvBmU2cwA5AHV7SBiRYNOL-ooGdomjv9VD98aZTNkk4,303
+lbc/models/owner.py,sha256=KEV8ID8O94DzTHd3MIzFHI8vetJfo8waQ-ETNBbCy8c,143
+lbc/models/proxy.py,sha256=Ar4hAk9sdZm1gDZOaPoyXu5pNIMaY2Ezq6hWoLb1-1Y,433
+lbc/models/search.py,sha256=i8wiVaQQB0i8fNuGSlB6fnozvhoVNBcle3Ee6i96zcQ,4196
+lbc-1.0.0.dist-info/METADATA,sha256=0fSl97cbalmOe6FnlVUhA6yJhXi3VgSlKYe6HIkaGB8,4223
+lbc-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lbc-1.0.0.dist-info/licenses/LICENSE,sha256=TOjGtMeKbX_qhoSU7ROWSF0GueuzHLzU_W8tleC6jfU,1070
+lbc-1.0.0.dist-info/RECORD,,

lbc-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lbc-1.0.0.dist-info/licenses/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.