Listings APIListings API
Anmelden

Schnellstart

Verbinden Sie sich mit der Listings API, listen Sie Ihre Standorte auf, erstellen Sie einen mit einem Aufruf und antworten Sie auf eine Bewertung.

1. Legen Sie Ihren API-Schlüssel fest

Erstellen Sie Ihren Schlüssel unter API Keys → New key im Entwickler-Dashboard der Listings API. Das SDK liest ihn automatisch aus der Umgebungsvariable LISTINGSAPI_KEY.

bash
export LISTINGSAPI_KEY="your-api-key"

2. Listen Sie Ihre Standorte auf

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

Erwartete Ausgabe:

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

Um alle Seiten automatisch abzurufen, verwenden Sie client.locations.list(first=100).auto_paging_iter(); die Funktion ruft die Folgeseiten anhand der Cursor ab, sodass Sie Cursor nie manuell verwalten müssen.

3. Erstellen Sie einen Standort mit einem einzigen Aufruf

locations.add() nimmt jedes Pflichtfeld als Schlüsselwortargument entgegen und validiert die Felder vor jedem Netzwerkaufruf auf der Clientseite (Namenslänge, Mindestlänge der Beschreibung von 200 Zeichen, Kategorie, Land, Stadt), sodass eine ungültige Payload sofort einen eindeutigen Fehler vom Typ ValidationError auslöst.

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)

Plattformen verwenden die Beschreibung als Haupttext des Eintrags, weshalb die API mindestens 200 Zeichen verlangt. Gültige Werte für sub_category_id erhalten Sie über client.subcategories().

Die neue ID wird als Base64-Zeichenfolge wie TG9jYXRpb246MTY4MDg= zurückgegeben. Numerische IDs und Base64-IDs sind überall dort austauschbar, wo das SDK eine Standort-ID akzeptiert, sodass client.locations.retrieve(16808) und client.locations.retrieve("TG9jYXRpb246MTY4MDg=") denselben Standort abrufen.

4. Antworten Sie auf eine Bewertung

Listen Sie die Bewertungen für einen Standort auf und antworten Sie anschließend mithilfe von interactionId der jeweiligen Bewertung:

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

Prüfen Sie canRespond, bevor Sie antworten, und greifen Sie niemals per Index auf eine Seite zu, ohne zuvor zu prüfen, ob sie nicht leer ist: reviews[0] löst bei einer leeren Seite IndexError aus, und eine Antwort auf eine Bewertung, die von der ursprünglichen Plattform geschlossen wurde, schlägt bei der Plattform statt bei der API fehl.

Wenn die Plattform die Antwort ablehnt, löst das SDK auch bei einem HTTP-Status von 200 eine Ausnahme vom Typ ValidationError aus; Sie müssen die success-Flags nie selbst prüfen.

5. Behandeln Sie Fehler

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

Bei ungültigen Schlüsseln wird HTTP 401 mit dem Plattformcode SY90005 zurückgegeben; das SDK löst eine Ausnahme vom Typ AuthenticationError aus. Es behandelt vorsorglich auch denselben Fehlercode, wenn dieser im Antworttext von 200 enthalten ist. Die vollständige Ausnahmehierarchie finden Sie unter Fehlerbehandlung und die HTTP-Statusmatrix in der Fehlercode-Referenz.

Nächste Schritte