Listings APIListings API
Se connecter

Démarrage rapide

Connectez-vous à Listings API, consultez vos établissements, créez-en un en un seul appel et répondez à un avis.

1. Configurez votre clé API

Obtenez votre clé dans Clés API → Nouvelle clé dans le tableau de bord développeur de Listings API. Le SDK la lit automatiquement dans la variable d'environnement LISTINGSAPI_KEY.

bash
export LISTINGSAPI_KEY="your-api-key"

2. Répertoriez vos établissements

quickstart.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, "--", loc.city, loc.stateIso) print(f"\nShowing {len(page)} locations, has_more={page.has_more}")
bash
python quickstart.py

Résultat attendu :

bash
Acme Dental Downtown -- New York NYAcme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NY Showing 3 locations, has_more=False

Pour récupérer automatiquement toutes les pages, utilisez client.locations.list(first=100).auto_paging_iter() ; cette méthode suit la pagination par curseur pour que vous n'ayez jamais à gérer les curseurs manuellement.

3. Créez un établissement en un seul appel

locations.add() accepte chaque champ obligatoire sous forme d'argument nommé et valide ces champs côté client (longueur du nom, description d'au moins 200 caractères, catégorie, pays, ville) avant tout appel réseau, de sorte qu'un contenu de requête invalide provoque immédiatement une erreur ValidationError explicite.

Python
import listingsapi client = listingsapi.ListingsAPI() result = client.locations.add(  name="Acme Dental Uptown",  description=(      "Acme Dental Uptown is a family-owned dental practice on the Upper "      "West Side of New York offering preventive care, cosmetic dentistry, "      "orthodontics, and emergency appointments. Our board-certified team "      "combines modern equipment with a gentle, patient-first approach."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="482 Columbus Ave",  state_iso="NY",  postal_code="10024",  phone="6443859313",) print(result.location.id)print(result.location.name)

Les plateformes de publication utilisent la description comme texte principal de la fiche, c'est pourquoi l'API exige au moins 200 caractères. Obtenez les valeurs valides de sub_category_id à partir de client.subcategories().

Le nouvel identifiant est renvoyé sous forme de chaîne base64, comme TG9jYXRpb246MTY4MDg=. Les identifiants numériques et base64 sont interchangeables partout où le SDK accepte un identifiant d'établissement ; client.locations.retrieve(16808) et client.locations.retrieve("TG9jYXRpb246MTY4MDg=") récupèrent donc le même établissement.

4. Répondez à un avis

Répertoriez les avis d'un établissement, puis répondez en utilisant le champ interactionId de l'avis :

Python
import listingsapi client = listingsapi.ListingsAPI() reviews = client.reviews.list(16808, first=10, rating_filters=[4, 5])for review in reviews:  print(review.rating, "-", review.get("content")) # A page can come back empty, and not every review is repliable: some sites# allow one owner reply per review, and some are read-only for the account.repliable = [r for r in reviews if r.get("canRespond")]if not repliable:  print("nothing to reply to")else:  client.reviews.respond(      interaction_id=repliable[0].interactionId,      content="Thank you for the kind review! We look forward to seeing you again soon.",  )

Vérifiez canRespond avant de répondre et n'accédez jamais à un élément d'une page par son indice sans vérifier au préalable que la page n'est pas vide : reviews[0] sur une page vide lève IndexError, et une réponse à un avis que la plateforme source a clôturé échoue au niveau de la plateforme de publication plutôt qu'au niveau de l'API.

Si la plateforme rejette la réponse, le SDK lève ValidationError même lorsque le statut HTTP est 200 ; vous n'avez jamais à vérifier vous-même les indicateurs success.

5. Gérez les erreurs

Python
import listingsapi try:  client = listingsapi.ListingsAPI(api_key="bad-key")  client.locations.list()except listingsapi.AuthenticationError as e:  print("Invalid key:", e.code)

Les clés invalides entraînent le renvoi de HTTP 401 avec le code de plateforme SY90005 ; le SDK lève AuthenticationError. Par précaution, il traite également ce même code d'erreur s'il apparaît dans le corps d'une réponse 200. Consultez Gestion des erreurs pour connaître la hiérarchie complète des exceptions et la référence des codes d'erreur pour consulter la matrice des statuts HTTP.

Étapes suivantes