Listings APIListings API
Se connecter

Établissements

Listez, créez, modifiez, archivez, recherchez et récupérez des établissements via client.locations.

Toutes les méthodes relatives aux établissements se trouvent sous client.locations. Installez le SDK et configurez votre clé avant de les utiliser ; consultez Installation et Démarrage rapide.

Identifiants des établissements

Les méthodes qui prennent un location_id acceptent un identifiant numérique (16808) ou son équivalent encodé en base64 ("TG9jYXRpb246MTY4MDg="). Le SDK encode automatiquement les identifiants numériques ; les deux formes sont donc interchangeables :

Python
# These are equivalentclient.locations.retrieve(16808)client.locations.retrieve("TG9jYXRpb246MTY4MDg=")

locations.add

Créez un établissement en un seul appel en passant chaque champ obligatoire sous forme d’argument nommé. C’est la méthode recommandée pour créer des établissements. Le SDK vérifie côté client les exigences de création de l’API et lève ValidationError avant tout appel réseau ; des données non valides provoquent donc un échec immédiat accompagné d’un message clair.

Python
client.locations.add(    *,    name: str,    description: str,    sub_category_id: int,    country_iso: str,    city: str | None = None,    street: str | None = None,    state_iso: str | None = None,    postal_code: str | None = None,    phone: str | None = None,    website: str | None = None,    store_id: str | None = None,    hide_address: bool | None = None,    business_hours: list[dict] | None = None,    service_area: dict | None = None,    place_action_links: list[dict] | None = None,    enabled_site_ids: list[int] | None = None,    additional_fields: dict | None = None,) -> APIObject
ArgumentTypeDescription
namestrNom de l’établissement, de 2 à 150 caractères. Obligatoire.
descriptionstrDescription de l’établissement, au moins 200 caractères. Les plateformes de publication l’utilisent comme texte principal de la fiche. Obligatoire.
sub_category_idintIdentifiant de la sous-catégorie principale. Utilisez client.subcategories() pour obtenir les identifiants valides. Obligatoire.
country_isostrCode ISO du pays à deux lettres. Utilisez client.countries() pour obtenir les pays pris en charge. Obligatoire.
citystrVille. Obligatoire pour les pays où l’adressage inclut la ville ; à omettre uniquement pour les établissements desservant une zone géographique avec hide_address=True.
streetstrAdresse postale.
state_isostrCode ISO de l’État ou de la région.
postal_codestrCode postal ou code ZIP.
phonestrNuméro de téléphone principal, dont la validité est vérifiée pour le pays.
websitestrURL du site web de l’établissement.
store_idstrVotre code de magasin unique ; doit être unique dans l’ensemble du compte.
hide_addressboolMasquer l’adresse postale (établissements desservant une zone géographique).
business_hourslist[dict]Horaires hebdomadaires, e.g. [{"day": "MONDAY", "slots": [...]}].
service_areadictConfiguration de la zone desservie : {businessType, regionCode, placeInfos}.
place_action_linkslist[dict]Liens d’action Google, e.g. [{"placeActionType": "APPOINTMENT", "uri": "https://...", "isPreferred": True}].
enabled_site_idslist[int]Identifiants des sites sur lesquels publier cet établissement, si vous souhaitez utiliser seulement une partie des sites inclus dans votre forfait. Utilisez client.plan_sites() pour obtenir les identifiants.
additional_fieldsdictChamps camelCase supplémentaires intégrés tels quels aux données envoyées.

Vérifications côté client : name contient de 2 à 150 caractères, description contient au moins 200 caractères, sub_category_id et country_iso sont présents, et city est présent sauf si hide_address=True.

La valeur renvoyée correspond aux données de création : .location contient le nouvel établissement. Vous n’avez jamais besoin de vérifier les indicateurs de réussite ; le SDK lève ValidationError lorsque l’API rejette les données envoyées.

Python
result = client.locations.add(  name="Acme Dental",  description=(      "Acme Dental is a family-owned dental practice offering general, "      "cosmetic, and pediatric dentistry in the heart of New York. Our "      "team provides cleanings, fillings, crowns, whitening, and same-day "      "emergency care in a modern, comfortable office with weekend hours "      "and easy online booking for new and returning patients."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="123 Jump Street",  state_iso="NY",  postal_code="10013",  phone="6443859313",  website="https://acmedental.example.com",  store_id="NYC-001",  place_action_links=[      {"placeActionType": "APPOINTMENT", "uri": "https://acmedental.example.com/book", "isPreferred": True},  ],  enabled_site_ids=[1, 24, 87],)print("Created:", result.location.id, result.location.name)

locations.list

Liste les établissements avec une pagination par curseur. Renvoie un SyncPage.

Python
client.locations.list(    *,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage
Python
# First page of 25page = client.locations.list(first=25)for loc in page:  print(loc.name, loc.city) # Next page manuallyif page.has_more:  page2 = page.next_page() # Auto-paginate all locationsfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

locations.retrieve

Récupère un seul établissement par son identifiant. Lève NotFoundError si l’identifiant n’existe pas.

Python
client.locations.retrieve(location_id: str | int) -> APIObject
Python
loc = client.locations.retrieve(16808)print(loc.name, loc.street, loc.city)

locations.list_by_ids

Récupère plusieurs établissements à partir d’une liste d’identifiants (numériques ou en base64) en un seul appel.

Python
client.locations.list_by_ids(location_ids: list[str | int]) -> list[APIObject]
Python
locs = client.locations.list_by_ids([16808, 16809, "TG9jYXRpb246MTQwMjQ="])for loc in locs:  print(loc.id, loc.name)

locations.list_by_store_codes

Récupère les établissements correspondant aux codes de magasin fournis.

Python
client.locations.list_by_store_codes(store_codes: list[str]) -> list[APIObject]
Python
locs = client.locations.list_by_store_codes(["SF-001", "NYC-042"])for loc in locs:  print(loc.storeId, loc.name)

locations.search

Recherche des établissements par mot-clé dans le nom, l’adresse ou l’identifiant du magasin. Renvoie un SyncPage.

Python
client.locations.search(    query: str,    *,    fields: list[str] | None = None,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage
Python
# Search all fieldspage = client.locations.search("downtown dental", first=10) # Restrict to name onlypage = client.locations.search("Acme Dental", fields=["name"], first=10) for loc in page:  print(loc.name, loc.city)

locations.create

Crée un établissement à partir d’un dictionnaire d’entrée brut avec des noms de champs camelCase. Privilégiez locations.add pour utiliser des arguments nommés et bénéficier de la validation côté client ; utilisez create lorsque vous disposez déjà de données camelCase.

Python
client.locations.create(input: dict) -> APIObject

Champs exigés par l’API : name, description (au moins 200 caractères), subCategoryId, countryIso et city (pour les pays où l’adressage inclut la ville).

Python
result = client.locations.create({  "name": "Acme Dental Brooklyn",  "description": (      "Acme Dental Brooklyn is a family-owned dental practice offering "      "general, cosmetic, and pediatric dentistry. Our team provides "      "cleanings, fillings, crowns, whitening, and same-day emergency "      "care in a modern, comfortable office with weekend hours and easy "      "online booking for new and returning patients across Brooklyn."  ),  "subCategoryId": 1432,  "countryIso": "US",  "city": "Brooklyn",  "street": "88 Court St",  "stateIso": "NY",  "postalCode": "11201",  "phone": "6443859314",  "storeId": "NYC-002",})print("Created:", result.location.id)

locations.update

Met à jour un établissement. Passez id ainsi que les champs à modifier (camelCase). id peut être numérique ou en base64 ; le SDK l’encode automatiquement.

Python
client.locations.update(input: dict) -> APIObject
Python
result = client.locations.update({  "id": 16808,  "phone": "6443859399",  "street": "125 Jump Street",})print("Updated:", result.location.id)

locations.archive

Archive un ou plusieurs établissements.

Python
client.locations.archive(location_ids: list[str | int]) -> APIObject
Python
result = client.locations.archive([16808, 16809])print(result.to_dict())

locations.cancel_archive

Annule un archivage planifié.

Python
client.locations.cancel_archive(    location_ids: list[str | int],    selection_type: str,    changed_by: str,) -> APIObject
Python
client.locations.cancel_archive(  [16808],  selection_type="manual",  changed_by="admin@example.com",)

Voir aussi

  • Publications : publier des annonces, des événements et des offres
  • Fiches : vérifier l’état de synchronisation par établissement
  • Avis : lister les avis et y répondre
  • Statistiques : statistiques des profils Google, Bing et Facebook