Listings APIListings API
Se connecter

Configuration

Configurez le client Python de Listings API : clé API, URL de base, délai d’attente, nouvelles tentatives et journalisation.

Signature du constructeur

Python
listingsapi.ListingsAPI(    api_key: str | None = None,    *,    base_url: str | None = None,    timeout: float = 240.0,    max_retries: int = 2,)

Tous les arguments sont facultatifs. Si api_key est omis, le client lit LISTINGSAPI_KEY dans l’environnement et lève AuthenticationError lors de sa création si aucun des deux n’est défini.

Options

OptionTypeValeur par défautDescription
api_keystr | NoneNoneClé API. Utilise la variable d’environnement LISTINGSAPI_KEY si aucune valeur n’est fournie.
base_urlstr | Nonehttps://listingsapi.comOrigine de l’API. La barre oblique finale est supprimée automatiquement.
timeoutfloat240.0Délai d’expiration par requête, en secondes (s’applique à chaque requête HTTP individuellement).
max_retriesint2Nouvelles tentatives automatiques en cas de réponses 429 et 5xx. Définissez cette option sur 0 pour les désactiver.

Clé API

bash
export LISTINGSAPI_KEY="your-api-key"
Python
import listingsapi # From environment (recommended)client = listingsapi.ListingsAPI() # Explicit keyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Délai d’expiration

La valeur par défaut est de 240.0 secondes. Pour les scripts de courte durée ou une utilisation interactive, vous pouvez choisir une valeur plus courte :

Python
client = listingsapi.ListingsAPI(timeout=30.0)

Le délai d’expiration s’applique à chaque requête HTTP individuellement. Les appels de pagination en masse (auto_paging_iter) respectent ce délai indépendamment pour chaque requête.

Nouvelles tentatives

Le SDK monte un adaptateur urllib3 Retry sur sa session requests, qui relance automatiquement les requêtes ayant reçu les réponses 429, 500, 502, 503 et 504, mais uniquement pour les méthodes sûres : GET, HEAD et OPTIONS. Les requêtes d’écriture (POST, DELETE) sont envoyées exactement une fois et lèvent immédiatement une exception en cas d’échec. Par défaut, 2 nouvelles tentatives sont effectuées avec un facteur de temporisation exponentielle de 0.5 seconde. Les en-têtes Retry-After sont respectés : lorsqu’une réponse 429 indique un temps d’attente, la requête est relancée après exactement ce délai.

L’API v4 ne prend pas en charge Idempotency-Key et ne détecte pas les écritures répétées ; une écriture dont le délai expire ou qui renvoie 5xx peut donc déjà avoir été validée. La relancer sans vérification créerait un deuxième établissement, une deuxième publication ou une deuxième réponse à un avis. Récupérez l’enregistrement à l’aide d’une clé que vous contrôlez avant de répéter une écriture.

Python
# More aggressive retry for long-running batch jobsclient = listingsapi.ListingsAPI(max_retries=5) # Disable retries entirely (e.g. when you want fast failures)client = listingsapi.ListingsAPI(max_retries=0)

Une réponse 429 qui persiste après toutes les nouvelles tentatives entraîne la levée de RateLimitError ; consultez Gestion des erreurs pour savoir comment mettre en place une temporisation manuelle.

Remplacement de l’URL de base

Utile pour les environnements de préproduction ou les proxys internes :

Python
client = listingsapi.ListingsAPI(base_url="https://staging.example.com")

La barre oblique finale est supprimée automatiquement. Toutes les requêtes utilisent le chemin /api/v4/ sur cette origine.

Journalisation

Le SDK utilise le module standard logging et le journaliseur listingsapi pour la journalisation. Au niveau DEBUG, il enregistre la méthode et l’URL de chaque requête (ainsi que les paramètres de requête pour GET) ; le corps des requêtes et votre clé API ne sont jamais journalisés.

Python
import logginglogging.basicConfig()logging.getLogger("listingsapi").setLevel(logging.DEBUG) import listingsapiclient = listingsapi.ListingsAPI()client.locations.list(first=1)

Étapes suivantes