Listings APIListings API
Accedi

Configurazione

Configura il client Python di Listings API: chiave API, URL di base, timeout, tentativi e logging.

Firma del costruttore

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

Tutti gli argomenti sono facoltativi. Se api_key viene omesso, il client legge LISTINGSAPI_KEY dall'ambiente e solleva AuthenticationError al momento della costruzione se nessuno dei due è impostato.

Opzioni

OpzioneTipoValore predefinitoDescrizione
api_keystr | NoneNoneChiave API. Se non specificata, viene usata la variabile d'ambiente LISTINGSAPI_KEY.
base_urlstr | Nonehttps://listingsapi.comOrigine dell'API. La barra finale viene rimossa automaticamente.
timeoutfloat240.0Timeout per richiesta in secondi (si applica a ogni singola richiesta HTTP).
max_retriesint2Tentativi automatici in caso di risposte 429 e 5xx. Imposta il valore su 0 per disabilitarli.

Chiave 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")

Timeout

Il valore predefinito è 240.0 secondi. Per script di breve durata o per l'uso interattivo, puoi impostare un valore più basso:

Python
client = listingsapi.ListingsAPI(timeout=30.0)

Il timeout si applica a ogni singola richiesta HTTP. Nelle chiamate di paginazione in blocco (auto_paging_iter), il timeout viene applicato separatamente a ogni richiesta.

Tentativi

L'SDK monta un adattatore urllib3 Retry sulla propria sessione requests che ripete automaticamente le richieste in caso di risposte 429, 500, 502, 503 e 504, ma solo per i metodi sicuri: GET, HEAD e OPTIONS. Le richieste di scrittura (POST, DELETE) vengono inviate esattamente una volta e sollevano immediatamente l'errore in caso di fallimento. Il valore predefinito è di 2 tentativi con un fattore di backoff esponenziale di 0.5 secondi. Gli header Retry-After vengono rispettati, quindi una richiesta che riceve una risposta 429 con un tempo di attesa viene ripetuta esattamente dopo tale intervallo.

L'API v4 non supporta Idempotency-Key e non rileva le scritture ripetute, quindi una scrittura che supera il timeout o restituisce 5xx potrebbe essere già stata applicata. Ripeterla senza verificare creerebbe una seconda sede, un secondo post o una seconda risposta a una recensione. Prima di ripetere una scrittura, rileggi il record usando una chiave sotto il tuo controllo.

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)

Se 429 persiste dopo tutti i tentativi, viene sollevato come RateLimitError; consulta Gestione degli errori per un esempio di backoff manuale.

Sostituzione dell'URL di base

Utile per ambienti di staging o proxy interni:

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

La barra finale viene rimossa automaticamente. Tutte le richieste vengono effettuate sotto il percorso /api/v4/ su questa origine.

Logging

L'SDK registra i log tramite il modulo standard logging usando il logger listingsapi. Al livello DEBUG registra il metodo e l'URL di ogni richiesta (e i parametri di query per GET); i corpi delle richieste e la tua chiave API non vengono mai registrati.

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

Passaggi successivi