Listings APIListings API
Accedi

Sedi

Elenca, crea, aggiorna, archivia, cerca e recupera sedi tramite client.locations.

Tutti i metodi per le sedi si trovano in client.locations. Installa l'SDK e configura la tua chiave prima di usarli; consulta Installazione e Guida rapida.

ID delle sedi

I metodi che richiedono un location_id accettano sia un ID numerico (16808) sia il suo equivalente codificato in base64 ("TG9jYXRpb246MTY4MDg="). L'SDK codifica automaticamente gli ID numerici, quindi le due forme sono intercambiabili:

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

locations.add

Crea una sede con una sola chiamata, passando ogni campo obbligatorio come argomento con nome. Questo è il modo consigliato per creare le sedi. L'SDK verifica lato client i requisiti di creazione dell'API e solleva ValidationError prima di qualsiasi chiamata di rete, quindi un payload non valido causa subito un errore con un messaggio chiaro.

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
ArgomentoTipoDescrizione
namestrNome dell'attività, 2-150 caratteri. Obbligatorio.
descriptionstrDescrizione dell'attività, almeno 200 caratteri. Le piattaforme di pubblicazione la usano come testo principale della scheda. Obbligatoria.
sub_category_idintID della sottocategoria principale. Usa client.subcategories() per ottenere gli ID validi. Obbligatorio.
country_isostrCodice ISO del paese a due lettere. Usa client.countries() per ottenere i paesi supportati. Obbligatorio.
citystrCittà. Obbligatoria per i paesi in cui gli indirizzi includono la città; omettila solo per le attività con area di servizio con hide_address=True.
streetstrIndirizzo.
state_isostrCodice ISO dello stato o della regione.
postal_codestrCodice postale o ZIP.
phonestrNumero di telefono principale, convalidato in base al paese.
websitestrURL del sito web dell'attività.
store_idstrIl tuo codice univoco del punto vendita; deve essere univoco all'interno dell'account.
hide_addressboolNascondi l'indirizzo (attività con area di servizio).
business_hourslist[dict]Orari settimanali, e.g. [{"day": "MONDAY", "slots": [...]}].
service_areadictConfigurazione dell'area di servizio: {businessType, regionCode, placeInfos}.
place_action_linkslist[dict]Link alle azioni di Google, e.g. [{"placeActionType": "APPOINTMENT", "uri": "https://...", "isPreferred": True}].
enabled_site_idslist[int]ID dei siti su cui pubblicare questa sede, se vuoi usare solo alcuni dei siti inclusi nel tuo piano. Usa client.plan_sites() per ottenere gli ID.
additional_fieldsdictCampi camelCase aggiuntivi inseriti nel payload senza modifiche.

La convalida lato client verifica che: name contenga 2-150 caratteri, description contenga almeno 200 caratteri, sub_category_id e country_iso siano presenti e city sia presente, a meno che hide_address=True.

Il valore restituito è il payload di creazione: .location contiene la nuova sede. Non devi mai controllare i flag di successo; l'SDK solleva ValidationError quando l'API rifiuta il payload.

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

Elenca le sedi con paginazione basata su cursore. Restituisce 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

Recupera una singola sede tramite ID. Solleva NotFoundError se l'ID non esiste.

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

Recupera più sedi da un elenco di ID (numerici o base64) con una sola chiamata.

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

Recupera le sedi corrispondenti ai codici dei punti vendita specificati.

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

Cerca le sedi per parola chiave nel nome, nell'indirizzo o nell'ID del punto vendita. Restituisce 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

Crea una sede da un dict di input non elaborato con nomi di campo camelCase. Preferisci locations.add per usare argomenti con nome e la convalida lato client; usa create quando hai già un payload camelCase.

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

Campi obbligatori per l'API: name, description (almeno 200 caratteri), subCategoryId, countryIso e city (per i paesi in cui gli indirizzi includono la città).

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

Aggiorna una sede. Passa id insieme ai campi da modificare (camelCase). Il valore di id può essere numerico o base64; l'SDK lo codifica automaticamente.

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

Archivia una o più sedi.

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

locations.cancel_archive

Annulla un'archiviazione programmata.

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

Vedi anche

  • Post: pubblica annunci, eventi e offerte
  • Schede: controlla lo stato di sincronizzazione per ciascuna sede
  • Recensioni: elenca le recensioni e rispondi
  • Analisi: analisi dei profili Google, Bing e Facebook