lbc-finder/README.md

lbc-finder

Stay notified when new ads appear on Leboncoin

from model import Search, Parameters
import lbc

def handle(ad: lbc.Ad, search_name: str):
    print(f"[{search_name}] New ads!")
    print(f"Title : {ad.subject}")
    print(f"Price : {ad.price} €")
    print(f"URL : {ad.url}")
    print("-" * 40)

location = lbc.City( 
    lat=48.85994982004764,
    lng=2.33801967847424,
    radius=10_000, # 10 km
    city="Paris"
)

CONFIG = [
    Search(
        name="Location Paris",
        parameters=Parameters(
            text="maison",
            locations=[location],
            category=lbc.Category.IMMOBILIER,
            square=[200, 400],
            price=[300_000, 700_000]
        ),
        delay=60 * 5, # Check every 5 minutes 
        handler=handle
    ),
    ... # More
]

lbc-finder is not affiliated with, endorsed by, or in any way associated with Leboncoin or its services. Use at your own risk.

This project uses lbc, an unofficial library to interact with Leboncoin API.

Features

• Advanced Search (text, category, price, location, square, etc.)
• Proxy Support for anonymity and bypassing rate limits
• Custom Logger with log file
• Configurable search interval (delay)
• Handler function triggered on new ads for full customization
• Multiple simultaneous searches with threading
• Easy integration with notifications (Discord, Telegram, email…) via handler

Installation

Required Python 3.9+

1. Clone the repository

   git clone https://github.com/etienne-hd/lbc-finder.git
   cd lbc-finder
   

2. Install dependencies

   pip install -r requirements.txt
   

Docker

You can run lbc-finder using Docker without installing Python locally.

Pull the image

The easiest way is to use the prebuilt image from Docker Hub:

docker pull etiennehode/lbc-finder:latest

Build locally

If you prefer to build the image yourself:

docker build -t lbc-finder .

Run the container

docker run -d \
  --name lbc-finder \
  -v lbc_data:/app/data \
  -v $(pwd)/config.py:/app/config.py \
  etiennehode/lbc-finder:latest

Volumes

Two volumes are used:

Volume	Description
/app/config.py	Your search configuration file
/app/data	Persistent storage for detected ads

Example:

-v $(pwd)/config.py:/app/config.py

This mounts your local config.py file into the container so you can easily edit your searches without rebuilding the image.

Configuration

A config.py file is provided by default in the project, it contains a basic configuration.

Inside this file, you must define a CONFIG variable, which is an list of Search objects.

Each Search object should be configured with the rules for the ads you want to track.

For example, if you want to track ads for a Porsche 944 priced between 0€ and 25,000€ anywhere in France:

from model import Search, Parameters

Search(
    name="Porsche 944",
    parameters=Parameters(
        text="Porsche 944",
        category=lbc.Category.VEHICULES_VOITURES,
        price=[0, 25_000]
    ),
    delay=60 * 5, # Every 5 minutes
    handler=handle,
    proxy=None
)

Name

A descriptive label for the Search.

It has no impact on the actual query, it’s only used to identify the search.

Parameters

All available parameters are documented in the lbc repository.

Delay

The time interval between each search.

Handler

This function is called whenever a new ad appears. It must accept two parameters:

• the Ad object
• the name (label) of the search (e.g. "Porsche 944")

def handle(ad: lbc.Ad, search_name: str) -> None:
    ...

You can find example handlers in the examples folder.

Proxy

You can configure a proxy, here is an example:

from lbc import Proxy
from model import Search

proxy = Proxy(
    host="127.0.0.1",
    port=9444,
    username="etienne",
    password="123456"
)

Search(
    name=...,
    parameters=...,
    delay=...,
    handler=...,
    proxy=proxy
)

Usage

To run lbc-finder, simply start the main.py file:

python main.py

License

This project is licensed under the MIT License.

Support

You can reach out to me on Telegram or Discord if you're looking for custom scraping services.