Listings APIListings API
Accedi

Guida rapida

Connettiti a Listings API, elenca le tue sedi, creane una con una sola chiamata e rispondi a una recensione.

1. Imposta la tua chiave API

Ottieni la tua chiave da Chiavi API → Nuova chiave nella dashboard per sviluppatori di Listings API. L'SDK la legge automaticamente dalla variabile d'ambiente LISTINGSAPI_KEY.

bash
export LISTINGSAPI_KEY="your-api-key"

2. Elenca le tue sedi

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

Output previsto:

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

Per richiedere automaticamente tutte le pagine, usa client.locations.list(first=100).auto_paging_iter(); segue la paginazione basata su cursori, così non devi mai gestirli manualmente.

3. Crea una sede con una sola chiamata

locations.add() accetta ogni campo obbligatorio come argomento con nome e li convalida lato client (lunghezza del nome, descrizione di almeno 200 caratteri, categoria, paese, città) prima di qualsiasi chiamata di rete, quindi un payload non valido genera subito un ValidationError chiaro.

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)

Le piattaforme di pubblicazione usano la descrizione come testo principale della scheda, per questo l'API richiede almeno 200 caratteri. Ottieni valori validi per sub_category_id da client.subcategories().

Il nuovo ID viene restituito come stringa base64, ad esempio TG9jYXRpb246MTY4MDg=. Gli ID numerici e quelli base64 sono intercambiabili ovunque l'SDK accetti un ID di sede, quindi client.locations.retrieve(16808) e client.locations.retrieve("TG9jYXRpb246MTY4MDg=") recuperano la stessa sede.

4. Rispondi a una recensione

Elenca le recensioni di una sede, poi rispondi usando il valore interactionId della recensione:

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

Controlla canRespond prima di rispondere e non accedere mai agli elementi di una pagina tramite indice senza aver prima verificato che non sia vuota: reviews[0] su una pagina vuota genera IndexError, e la risposta a una recensione che la piattaforma di origine ha chiuso viene rifiutata dalla piattaforma di pubblicazione anziché dall'API.

Se la piattaforma rifiuta la risposta, l'SDK genera ValidationError anche quando lo stato HTTP è 200; non devi mai controllare direttamente i flag success.

5. Gestisci gli errori

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

Le chiavi non valide producono una risposta HTTP 401 con il codice della piattaforma SY90005; l'SDK genera AuthenticationError. Per precauzione, gestisce lo stesso codice di errore anche se arriva nel corpo di una risposta 200. Consulta Gestione degli errori per la gerarchia completa delle eccezioni e il riferimento dei codici di errore per la matrice degli stati HTTP.

Passaggi successivi