Listings APIListings API
Accedi

Python SDK

Client Python ufficiale per Listings API con risorse tipizzate, paginazione a cursore, tentativi automatici ed errori con nomi specifici.

Il pacchetto listingsapi è il client Python ufficiale per Listings API. Incapsula il livello REST con classi di risorse tipizzate, paginazione basata su cursori, tentativi automatici in caso di errori temporanei e un'eccezione specifica per ogni tipo di errore, inclusi i payload di errore che la piattaforma restituisce con HTTP 200.

Installazione

bash
pip install listingsapi

Richiede Python 3.9 o versioni successive. L'unica dipendenza in fase di esecuzione è requests.

Autenticazione

Python
import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Ottieni la tua chiave API da Chiavi API → Nuova chiave nella dashboard per sviluppatori di Listings API.

Il client accetta tre argomenti opzionali per parola chiave:

OpzioneValore predefinitoDescrizione
base_urlhttps://listingsapi.comHost API a cui inviare le richieste
timeout240.0Timeout per ciascuna richiesta, in secondi
max_retries2Tentativi automatici in caso di risposte 429 e 5xx, rispettando Retry-After

Consulta Configurazione per i dettagli.

Esempio rapido

list_locations.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, loc.city) print(f"has_more: {page.has_more}")

Risorse

Ogni risorsa è una proprietà del client:

ProprietàCosa gestisce
client.locationsSedi aziendali: elenco, ricerca, creazione con una sola chiamata, aggiornamento, archiviazione
client.reviewsRecensioni e risposte, oltre alle analisi disponibili in client.reviews.analytics
client.postsPost di annunci, eventi e offerte su Google e Facebook
client.socialBrand in Social, account social collegati e post su Facebook, Instagram, X, LinkedIn e Pinterest
client.listingsSchede premium e per assistenti vocali, duplicati, collegamento e scollegamento
client.analyticsStatistiche dei profili Google, Bing e Facebook
client.photosFoto delle sedi: caricamento, rimozione, aggiunta ai preferiti
client.connected_accountsConnessioni OAuth a Google e Facebook
client.workflowsAutomazioni predefinite: risposta automatica alle recensioni, report sulla reputazione, verifica dello stato delle schede

Quattro metodi di supporto sono disponibili direttamente sul client:

Python
client.plan_sites()       # directories included in your planclient.subcategories()    # business categories (IDs for locations.add)client.countries()        # supported countries and states (ISO codes)client.subscriptions()    # active subscriptions for the account

Paginazione

I metodi che restituiscono elenchi usano la paginazione basata su cursori. Ogni metodo con paginazione restituisce un oggetto SyncPage: iterabile, con .has_more, .next_page(), .auto_paging_iter() e .total.

Python
# Fetch one pagepage = client.locations.list(first=25)for loc in page:  print(loc.name) # Check if more pages existif page.has_more:  next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

Oggetti di risposta

Tutti i metodi restituiscono APIObject (accesso tramite attributi e dizionario) o SyncPage (iterabile, con paginazione). APIObject supporta anche .get() e .to_dict().

Python
loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()

Gestione degli errori

Ogni errore dell'SDK deriva da listingsapi.ListingsAPIError. Gli errori dell'API sollevano APIError o una delle sue sottoclassi: AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (con .retry_after) e InternalServerError. Gli errori di rete sollevano APIConnectionError.

APIError contiene status_code, code (il primo codice di errore della piattaforma, e.g. SY10005), errors (ogni voce normalizzata in dizionari {"code", "message", "context"}) e response_body.

La piattaforma segnala alcuni errori nel corpo di una risposta HTTP 200: payload errors[] al livello principale (i token non validi vengono restituiti come SY90005) e risposte alle operazioni di scrittura con success=false. L'SDK solleva eccezioni anche in questi casi, quindi non devi mai controllare personalmente i flag success.

Python
import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.retrieve(999999)except listingsapi.NotFoundError:  print("No such location")except listingsapi.RateLimitError as e:  print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e:  print(e.status_code, e.code)  for err in e.errors:      print(err["code"], err["message"])

Consulta Gestione degli errori per la gerarchia completa delle eccezioni.

Passaggi successivi