Listings APIListings API
Anmelden

Python SDK

Offizieller Python-Client für Listings API mit typisierten Ressourcen, Cursor-Paginierung, automatischen Wiederholungen und benannten Fehlern.

Das Paket listingsapi ist der offizielle Python-Client für Listings API. Es kapselt die REST-Schicht mit typisierten Ressourcenklassen, cursorbasierter Paginierung, automatischen Wiederholungsversuchen bei vorübergehenden Fehlern und einer benannten Ausnahme für jede Fehlerart, einschließlich Fehlerdaten, die die Plattform mit HTTP 200 zurückgibt.

Installation

bash
pip install listingsapi

Erfordert Python 3.9 oder höher. Die einzige Laufzeitabhängigkeit ist requests.

Authentifizierung

Python
import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Rufen Sie Ihren API-Schlüssel unter API-Schlüssel → Neuer Schlüssel im Entwickler-Dashboard von Listings API ab.

Der Client akzeptiert drei optionale Schlüsselwortargumente:

OptionStandardwertBeschreibung
base_urlhttps://listingsapi.comAPI-Host, an den Anfragen gesendet werden
timeout240.0Zeitlimit pro Anfrage in Sekunden
max_retries2Automatische Wiederholungsversuche bei Antworten mit 429 und 5xx unter Berücksichtigung von Retry-After

Weitere Informationen finden Sie unter Konfiguration.

Kurzes Beispiel

list_locations.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, loc.city) print(f"has_more: {page.has_more}")

Ressourcen

Jede Ressource ist eine Eigenschaft des Clients:

EigenschaftVerwaltete Inhalte und Funktionen
client.locationsUnternehmensstandorte: auflisten, suchen, mit einem einzigen Aufruf erstellen, aktualisieren, archivieren
client.reviewsBewertungen und Antworten sowie Analysen unter client.reviews.analytics
client.postsAnkündigungs-, Veranstaltungs- und Angebotsbeiträge auf Google und Facebook
client.socialMarken für soziale Medien, verbundene Social-Media-Konten und Beiträge auf Facebook, Instagram, X, LinkedIn und Pinterest
client.listingsPremium-Einträge und Einträge für Sprachassistenten, Duplikate, Verbindungen herstellen und trennen
client.analyticsProfilstatistiken für Google, Bing und Facebook
client.photosStandortfotos: hochladen, entfernen, mit einem Stern markieren
client.connected_accountsOAuth-Verbindungen zu Google und Facebook
client.workflowsVordefinierte Automatisierungen: automatische Antworten auf Bewertungen, Reputationsbericht, Zustandsprüfung von Einträgen

Vier Hilfsmethoden stehen direkt am Client zur Verfügung:

Python
client.plan_sites()       # directories included in your planclient.subcategories()    # business categories (IDs for locations.add)client.countries()        # supported countries and states (ISO codes)client.subscriptions()    # active subscriptions for the account

Paginierung

Methoden, die Listen zurückgeben, verwenden cursorbasierte Paginierung. Jede Methode mit Paginierung gibt ein SyncPage zurück: iterierbar, mit .has_more, .next_page(), .auto_paging_iter() und .total.

Python
# Fetch one pagepage = client.locations.list(first=25)for loc in page:  print(loc.name) # Check if more pages existif page.has_more:  next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

Antwortobjekte

Alle Methoden geben APIObject (Zugriff über Attribute und als dict) oder SyncPage (iterierbar, paginiert) zurück. APIObject unterstützt auch .get() und .to_dict().

Python
loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()

Fehlerbehandlung

Jeder SDK-Fehler ist von listingsapi.ListingsAPIError abgeleitet. API-Fehler lösen APIError oder eine der folgenden Unterklassen aus: AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (mit .retry_after) und InternalServerError. Netzwerkfehler lösen APIConnectionError aus.

APIError enthält status_code, code (den ersten Plattformfehlercode, e.g. SY10005), errors (jeder Eintrag wird zu {"code", "message", "context"}-dicts normalisiert) und response_body.

Die Plattform meldet einige Fehler im Antwortkörper einer HTTP-200-Antwort: errors[]-Nutzdaten auf oberster Ebene (ungültige Tokens werden als SY90005 zurückgegeben) und Antworten auf Schreibvorgänge mit success=false. Das SDK löst auch dafür Ausnahmen aus, sodass Sie success-Flags nie selbst prüfen müssen.

Python
import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.retrieve(999999)except listingsapi.NotFoundError:  print("No such location")except listingsapi.RateLimitError as e:  print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e:  print(e.status_code, e.code)  for err in e.errors:      print(err["code"], err["message"])

Die vollständige Ausnahmehierarchie finden Sie unter Fehlerbehandlung.

Nächste Schritte