Créer une alerte Leboncoin personnalisée via l’API

Vous pouvez créer une alerte Leboncoin personnalisée en interrogeant l'endpoint `/api/v1/leboncoin/search` depuis un script Python. Ce code récupère les nouvelles annonces selon vos filtres et déclenche une notification immédiate via le webhook de votre choix (Slack, Discord). Cette approche offre un contrôle total sur la logique de filtrage sans dépendre d'outils tiers.

Prérequis et configuration de l'environnement

Pour implémenter un système d'alerte technique fiable sur Leboncoin, vous devez d'abord structurer votre environnement de développement. Cette approche repose sur des bibliothèques HTTP robustes capables de gérer les en-têtes et le corps JSON retourné par l'API LeBonDeal API.

Les prérequis essentiels incluent :

• Un interpréteur Python (version 3.8+) ou Node.js (v14+).
• La bibliothèque requests pour Python, qui gère automatiquement les redirections et l'analyse JSON. Pour JavaScript/Node.js, utilisez l'agent natif fetch ou une librairie comme axios.
• Un gestionnaire de variables d'environnement (python-dotenv ou fichier .env) pour stocker votre clé API sans la versionner dans Git.

La configuration initiale consiste à isoler les secrets. Ne hardcodez jamais vos identifiants dans le script principal. Utilisez un fichier .env local contenant LEBONDEAL_API_KEY=YOUR_API_KEY. Cette méthode garantit que la sécurité de votre accès reste indépendante du code source partagé ou déployé sur des serveurs distants.

Authentification et appel de l'API Leboncoin

L’authentification repose sur un en-tête Authorization de type Bearer. Transmettez votre clé API unique, générée dans le tableau de bord, via cet en-tête. L’appel s’effectue par HTTP GET vers l’endpoint /api/v1/leboncoin/search. Le paramètre obligatoire est url, correspondant à la recherche complète copiée depuis un navigateur.

Voici l’implémentation Python avec gestion des timeouts et des erreurs courantes :

import os
import requests
from time import sleep

BASE_URL = os.environ.get("LEBONDEAL_BASE_URL", "https://bot.lebondeal-bot.fr")
API_KEY = os.environ["LEBONDEAL_API_KEY"]
SEARCH_URL = "https://www.leboncoin.fr/recherche?category=3&text=vélo"

headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"url": SEARCH_URL, "page": 1}

try:
    response = requests.get(
        f"{BASE_URL}/api/v1/leboncoin/search", 
        headers=headers, 
        params=params, 
        timeout=45
    )
    
    if response.status_code == 429:
        print("Rate limited. Réessayez plus tard.")
    elif response.status_code == 503:
        print("Erreur serveur ou recherche vide après tentatives internes.")
    elif response.status_code != 200:
        print(f"Erreur {response.status_code}: {response.json().get('message')}")
    else:
        data = response.json()
        print(f"{data['count']} annonces trouvées. Crédits restants : {data['credits_remaining']}")

except requests.exceptions.Timeout:
    print("Timeout dépassé (45s). Vérifiez votre connexion.")

Ce script configure l’en-tête d’authentification et envoie la requête avec un timeout de 45 secondes. Il distingue le rate limiting (429) des erreurs techniques ou vides (503), puis affiche le nombre d’annonces et les crédits restants si la réponse est valide. Pour plus de détails sur les endpoints, consultez la documentation Leboncoin.

Traitement des champs d'annonce

Pour filtrer efficacement les opportunités, concentrez-vous sur un sous-ensemble restreint des champs retournés par l’endpoint Leboncoin. La liste des annonces dans la réponse JSON contient pour chaque élément les informations suivantes : id, title, price, location, url, images (liste complète), owner et published.

Votre logique d’alerte doit impérativement vérifier l’existence du champ price. Contrairement à certains services, ce champ est de type nombre. Son absence peut indiquer une annonce hors catégorie standard ou un format spécifique que votre scraper ne parse pas correctement dans la liste initiale. Pour valider le statut du vendeur, inspectez l’objet owner : il contient obligatoirement les clés user_id, name et type. Ce dernier permet de distinguer un particulier ("private") d’un professionnel sans nécessiter d’appel supplémentaire.

La localisation est disponible dans la clé location sous forme de chaîne (ville). Elle suffit pour des filtres géographiques simples, mais ne fournit pas les coordonnées GPS précises ni le code postal détaillé. Pour obtenir ces informations ou accéder à la description complète non tronquée, vous devrez effectuer un second appel sur l’URL fournie dans le champ url du résultat de recherche.

Envoi de la notification vers Slack ou Discord

Une fois les annonces récupérées, le formatage du payload JSON doit respecter la structure attendue par l'API de notification. Pour Slack ou Discord, il s'agit généralement d'un objet contenant un champ text (Slack) ou content (Discord). Mappez les champs retournés (title, price, location) pour assurer une lecture rapide dans le canal concerné.

Voici un script Python complet utilisant la bibliothèque standard requests et des variables d'environnement pour sécuriser la clé API :

import os, json, requests
from datetime import datetime

BASE_URL = os.environ.get("LEBONDEAL_BASE_URL", "https://bot.lebondeal-bot.fr")
API_KEY = os.environ["LEBONDEAL_API_KEY"]
WEBHOOK_URL = os.getenv("DISCORD_WEBHOOK") # Remplacer par l'URL du webhook Slack/Discord

def send_alert(ad):
    payload = {
        "embeds": [{
            "title": f"{ad['title']} - {ad['price']}€",
            "description": f"📍 {ad.get('location', 'N/A')}\n[Voir l'annonce]({ad['url']})",
            "color": 3066993,
            "footer": {"text": f"ID: {ad['id']} | Publié le : {ad.get('published')}"}
        }]
    }

    try:
        response = requests.post(
            WEBHOOK_URL, 
            json=payload, 
            timeout=10
        )
        if not response.ok:
            print(f"Erreur webhook ({response.status_code}): {response.text}")
    except Exception as e:
        print(f"Échec envoi alerte : {str(e)}")

# Exemple d'appel avec une annonce brute reçue de l'API LeBonDeal
if __name__ == "__main__":
    # Simulation d'une réponse /search
    fake_ad = {
        "id": "1234567890",
        "title": "iPhone 13 Pro Max neuf",
        "price": 850,
        "location": "Paris (75)",
        "url": "https://www.leboncoin.fr/iphone_13_pro_max.htm",
        "published": "2024-05-20 10:00:00"
    }
    send_alert(fake_ad)

Ce code illustre la séparation entre l'extraction des données via l'API LeBonDeal et leur diffusion. La fonction send_alert prend un dictionnaire standardisé issu de votre traitement local. Elle utilise un timeout court pour le webhook afin de ne pas bloquer la boucle principale si l'hôte distant est lent, tout en capturant les exceptions réseau immédiates.

Gestion des erreurs et limites techniques

La gestion robuste des erreurs repose sur le respect strict des limites techniques imposées par l'API. Le timeout client doit être défini au minimum à 45 secondes pour absorber les délais liés aux tentatives silencieuses côté serveur en cas d’incident temporaire. Au-delà de ce délai, la connexion échoue sans retour utile.

Pour les codes HTTP, chaque erreur renvoie un JSON contenant error et message. Une réponse 401 (unauthorized) ou 429 (rate_limited) nécessite une action immédiate : révocation de la clé ou back-off exponentiel. Attention à la réponse 503 (unexpected_error) : elle indique soit un incident technique persistant, soit une recherche légitimement vide sur les marketplaces internationales (Vinted, Kleinanzeigen). Ces deux cas sont indistinguables pour le client et ne facturent aucun crédit.

Concernant la pagination, le paramètre optionnel page écrase toute valeur présente dans l'URL source. L'API ne fournit pas de compteur final explicite pour détecter automatiquement la fin des résultats ; vous devez itérer jusqu'à ce que la structure de réponse indique qu'il n'y a plus d'annonces ou utiliser le champ count. Pour les détails sur les champs retournés par /search, consultez la documentation spécifique Leboncoin.

FAQ

Articles liés