Listings APIListings API
Se connecter

Python SDK

Client Python officiel pour Listings API avec ressources typées, pagination par curseur, nouvelles tentatives automatiques et erreurs nommées.

Le paquet listingsapi est le client Python officiel de Listings API. Il encapsule la couche REST avec des classes de ressources typées, une pagination par curseur, des tentatives automatiques en cas d’erreurs temporaires et une exception nommée pour chaque type d’échec, y compris les erreurs renvoyées par la plateforme dans le corps d’une réponse HTTP 200.

Installation

bash
pip install listingsapi

Nécessite Python 3.9 ou une version ultérieure. La seule dépendance à l’exécution est requests.

Authentification

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

Obtenez votre clé API dans API Keys → New key dans le tableau de bord développeur de Listings API.

Le client accepte trois arguments nommés facultatifs :

OptionValeur par défautDescription
base_urlhttps://listingsapi.comHôte de l’API auquel envoyer les requêtes
timeout240.0Délai d’expiration par requête, en secondes
max_retries2Tentatives automatiques en cas de réponses 429 et 5xx, en respectant Retry-After

Consultez Configuration pour plus de détails.

Exemple rapide

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

Ressources

Chaque ressource est une propriété du client :

PropriétéÉléments gérés
client.locationsÉtablissements : affichage de la liste, recherche, création en un seul appel, mise à jour, archivage
client.reviewsAvis et réponses, ainsi que les analyses accessibles via client.reviews.analytics
client.postsPublications d’annonces, d’événements et d’offres sur Google et Facebook
client.socialMarques Social, comptes sociaux connectés et publications sur Facebook, Instagram, X, LinkedIn et Pinterest
client.listingsFiches premium et fiches pour les assistants vocaux, doublons, connexion et déconnexion
client.analyticsStatistiques des profils Google, Bing et Facebook
client.photosPhotos des établissements : envoi, suppression, ajout d’une étoile
client.connected_accountsConnexions OAuth à Google et Facebook
client.workflowsAutomatisations prédéfinies : réponse automatique aux avis, rapport de réputation, audit de l’état des fiches

Quatre méthodes complémentaires sont disponibles directement sur le 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

Pagination

Les méthodes qui renvoient des listes utilisent une pagination par curseur. Chaque méthode paginée renvoie un objet SyncPage : itérable, avec .has_more, .next_page(), .auto_paging_iter() et .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)

Objets de réponse

Toutes les méthodes renvoient APIObject (accès par attribut et par dictionnaire) ou SyncPage (itérable, paginé). APIObject prend également en charge .get() et .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()

Gestion des erreurs

Toutes les erreurs du SDK dérivent de listingsapi.ListingsAPIError. Les échecs de l’API lèvent APIError ou l’une de ses sous-classes : AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (avec .retry_after) et InternalServerError. Les échecs réseau lèvent APIConnectionError.

APIError contient status_code, code (le premier code d’erreur de la plateforme, e.g. SY10005), errors (chaque entrée étant normalisée sous forme de dictionnaire {"code", "message", "context"}) et response_body.

La plateforme signale certains échecs dans le corps d’une réponse HTTP 200 : des données errors[] au niveau racine (les jetons non valides sont signalés par SY90005) et des réponses aux opérations d’écriture contenant success=false. Le SDK lève également des exceptions dans ces cas, vous n’avez donc jamais à examiner vous-même les indicateurs 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"])

Consultez Gestion des erreurs pour connaître la hiérarchie complète des exceptions.

Étapes suivantes