Cibler une recherche Kleinanzeigen par code postal (PLZ)

Pour cibler une recherche Kleinanzeigen par code postal (PLZ) via l’API LeBonDeal, vous devez utiliser la fonctionnalité de filtrage géolocalisé directement dans l'interface web du site source et copier l'URL générée. L'endpoint `/api/v1/kleinanzeigen/search` accepte cette URL comme paramètre `url`, garantissant que les filtres sont respectés sans nécessiter de construction manuelle complexe.

Le principe : copier l'URL filtrée plutôt que la construire

L’API Kleinanzeigen ne construit pas la requête à partir de critères isolés comme le code postal ou la ville. Elle repose exclusivement sur un paramètre unique et obligatoire : l'URL complète de recherche extraite du navigateur. Cette contrainte architecturale signifie que vous ne pouvez pas transmettre des filtres décomposés (géographie, prix, catégorie) via des arguments distincts dans votre appel HTTP. Vous devez d’abord configurer vos critères directement sur le site web kleinanzeigen.de, puis récupérer l'URL résultante qui intègre déjà tous les filtres appliqués par la plateforme source.

Ce mécanisme garantit que vous interagissez avec la structure exacte des résultats fournis par Kleinanzeigen, sans risque de désynchronisation entre les paramètres envoyés et ceux interprétés par le moteur de recherche distant. Pour cibler une zone géographique précise via un code postal (PLZ), il est nécessaire d'utiliser l'interface graphique du site :

• Accédez à la page de recherche principale sur kleinanzeigen.de.
• Saisissez votre code postal dans le champ dédié ou utilisez la carte interactive pour définir les limites.
• Appliquez vos autres filtres (catégorie, rayon) si nécessaire.
• Copiez l'URL générée dans la barre d'adresse du navigateur une fois les résultats affichés.

Vous transmettez ensuite cette chaîne exacte via le paramètre url lors de votre requête à l’API Kleinanzeigen. Toute tentative de construction manuelle d'une URL simplifiée ou l'ajout de paramètres non supportés entraînera une erreur 400.

Générer l'URL cible avec le filtre PLZ

Pour extraire des données pertinentes de Kleinanzeigen, la précision géographique est souvent le facteur décisif. L'API ne permet pas de définir directement un rayon ou un code postal dans ses paramètres. Elle repose sur l'extraction du contenu d'une URL existante. Vous devez donc configurer votre recherche manuellement sur le site avant toute intégration technique.

Commencez par accéder à la page principale des annonces et saisissez votre critère principal, comme une catégorie ou un mot-clé. Dans les filtres avancés, localisez la section dédiée à l'emplacement. C'est ici que vous définissez vos zones d'intérêt. Vous pouvez entrer plusieurs codes postaux (PLZ) séparés par des virgules pour couvrir une zone plus large qu'une seule ville. Le moteur de recherche agrégera les résultats de ces différentes zones dans une même page de résultats unifiée.

Une fois votre filtre PLZ configuré et vos autres critères validés, observez l'URL générée dans la barre d'adresse de votre navigateur. Elle contient désormais toute la logique de filtrage géographique que vous avez définie. Cette URL est le seul paramètre obligatoire pour notre endpoint Kleinanzeigen. Ne tentez pas de reconstruire cette chaîne à partir de zéro via du code, car la structure interne peut évoluer sans préavis et casserait votre requête.

Extraction des données géolocalisées via l'API

L'appel à l'endpoint /api/v1/kleinanzeigen/search permet d'extraire les données structurées correspondant aux résultats affichés pour une recherche Kleinanzeigen filtrée par code postal. Contrairement à une lecture manuelle, vous recevez un objet JSON standardisé contenant la liste des annonces (items) et les métadonnées de facturation.

import os
import requests

BASE_URL = os.environ.get("LEBONDEAL_BASE_URL", "https://bot.lebondeal-bot.fr")
API_KEY = os.environ["LEBONDEAL_API_KEY"]

# URL Kleinanzeigen filtrée par PLZ (ex: 75013)
kleinanzeigen_url = "https://www.kleinanzeigen.de/s-immobilien/wohnungen/75013"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

params = {
    "url": kleinanzeigen_url
}

try:
    response = requests.get(
        f"{BASE_URL}/api/v1/kleinanzeigen/search",
        headers=headers,
        params=params,
        timeout=45
    )

    if response.status_code == 200:
        data = response.json()
        print(f"Annonces trouvées : {data.get('count')}")
        
        for item in data.get("items", []):
            # Les champs peuvent être vides selon le type d'annonce
            location = item.get("location", "N/A")
            price_str = item.get("price", "") or ""
            print(f"[{location}] {item['title']} - {price_str}")

    elif response.status_code == 429:
        # Limite de débit atteinte : attendre et réessayer avec backoff exponentiel simple
        import time
        wait_time = 10
        while True:
            print(f"Rate limited. Attente de {wait_time}s...")
            time.sleep(wait_time)
            response_retry = requests.get(
                f"{BASE_URL}/api/v1/kleinanzeigen/search",
                headers=headers,
                params=params,
                timeout=45
            )
            if response_retry.status_code != 429:
                break
            wait_time *= 2

    elif response.status_code == 503:
        # Erreur serveur ou recherche vide/échouée (non facturée)
        print("Erreur 503 : incident temporaire ou résultat vide.")

    else:
        error_data = response.json() if response.headers.get('Content-Type', '').startswith('application/json') else {}
        print(f"Erreur API ({response.status_code}) : {error_data.get('message')}")

except requests.exceptions.Timeout:
    print("Timeout client dépassé (45s). Le serveur traite encore la requête.")

Ce script effectue une requête GET authentifiée vers l'API Kleinanzeigen en transmettant l'URL de recherche comme paramètre. Il gère les codes d'erreur critiques : le 429 impose une attente avec backoff, tandis que le 503 indique un incident serveur ou une absence de résultats légitime sans facturation de crédits. Les champs location et price sont extraits directement depuis la réponse JSON ; notez qu'ils peuvent être vides si Kleinanzeigen ne les fournit pas pour certaines annonces spécifiques. Pour plus de détails sur les endpoints disponibles, consultez la documentation API Kleinanzeigen.

Gestion des champs de localisation et formats

Les champs géolocalisés renvoyés par l’API Kleinanzeigen ne suivent pas de format standardisé garantissant une structure fixe. Le champ location correspond à la ville, mais sa présence n’est pas systématique ; selon le type d’annonce ou les données disponibles pour celle-ci, ce champ peut être vide dans la réponse JSON. Il est donc impératif de tester l’existence du champ avant tout traitement afin d’éviter des erreurs de parsing côté client.

De même, le champ published retourne une chaîne en allemand (ex. : "Heute, 09:14") qui n’est pas directement parsable comme une date ISO standardisée. Pour intégrer ces données dans vos outils métier ou bases de données relationnelles, vous devrez implémenter votre propre logique de conversion temporelle adaptée à ce format spécifique.

Enfin, le champ price inclut systématiquement la devise (ex. : "120 €"). Si votre application nécessite un traitement numérique pur, une étape de nettoyage est nécessaire pour extraire uniquement la valeur monétaire et ignorer le symbole de l’euro. Ces variations structurelles obligent à prévoir des mécanismes de fallback robustes dans votre code d’intégration.

Pour plus de détails sur la structure exacte des réponses, consultez la documentation officielle de l’API Kleinanzeigen.

Limites techniques et gestion des erreurs

Lors de l'intégration de la recherche Kleinanzeigen via code postal, vous devez anticiper plusieurs scénarios d'échec qui ne se résolvent pas par un simple parsing JSON. La robustesse de votre script dépend de la gestion correcte des statuts HTTP retournés par le serveur.

Une erreur 400 invalid_url survient si l'URL fournie ne correspond pas à une page de résultats valide pour Kleinanzeigen, par exemple si vous passez accidentellement un lien vers une fiche annonce individuelle (/s-anzeige/...) au lieu d'une liste filtrée. Vérifiez que le paramètre url pointe bien vers la vue des résultats.

Si la recherche est techniquement impossible ou échoue après les tentatives internes du serveur, vous recevrez une erreur 503 unexpected_error. Il est crucial de noter qu'avec Kleinanzeigen, cette même réponse 503 est également renvoyée si la recherche est légitimement vide (aucune annonce ne correspond aux critères PLZ). Votre code doit donc traiter ces deux cas indistinctement comme un échec technique ou une absence de données, sans facturation de crédits.

Enfin, respectez les limites de débit. Un statut 429 rate_limited indique que vous avez dépassé le plafond autorisé par clé ou par IP. Aucune en-tête HTTP spécifique ne précise la durée d'attente ; appliquez une stratégie de backoff exponentiel simple avant de réessayer. Pour des cas plus critiques comme un solde insuffisant (402) ou une clé invalide (401), l'exécution s'arrête immédiatement et nécessite une intervention manuelle dans votre tableau de bord.

FAQ

Articles liés