Listings APIListings API
Anmelden

Konfiguration

Konfigurieren Sie den Python-Client der Listings API: API-Schlüssel, Basis-URL, Zeitlimit, Wiederholungsversuche und Protokollierung.

Konstruktorsignatur

Python
listingsapi.ListingsAPI(    api_key: str | None = None,    *,    base_url: str | None = None,    timeout: float = 240.0,    max_retries: int = 2,)

Alle Argumente sind optional. Wenn api_key nicht angegeben wird, liest der Client LISTINGSAPI_KEY aus der Umgebung und löst beim Erstellen der Instanz AuthenticationError aus, wenn keiner der beiden Werte gesetzt ist.

Optionen

OptionTypStandardwertBeschreibung
api_keystr | NoneNoneAPI-Schlüssel. Verwendet ersatzweise die Umgebungsvariable LISTINGSAPI_KEY.
base_urlstr | Nonehttps://listingsapi.comAPI-Ursprung. Ein abschließender Schrägstrich wird automatisch entfernt.
timeoutfloat240.0Zeitlimit pro Anfrage in Sekunden (gilt für jede HTTP-Anfrage einzeln).
max_retriesint2Automatische Wiederholungsversuche bei Antworten mit 429 und 5xx. Setzen Sie den Wert auf 0, um sie zu deaktivieren.

API-Schlüssel

bash
export LISTINGSAPI_KEY="your-api-key"
Python
import listingsapi # From environment (recommended)client = listingsapi.ListingsAPI() # Explicit keyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Zeitlimit

Der Standardwert beträgt 240.0 Sekunden. Für kurz laufende Skripte oder die interaktive Nutzung kann ein kürzeres Zeitlimit sinnvoll sein:

Python
client = listingsapi.ListingsAPI(timeout=30.0)

Das Zeitlimit gilt für jede einzelne HTTP-Anfrage. Bei Aufrufen, die mehrere Seiten abrufen (auto_paging_iter), wird das Zeitlimit für jede Anfrage unabhängig angewendet.

Wiederholungsversuche

Das SDK bindet einen urllib3-Retry-Adapter in seine requests-Sitzung ein, der Anfragen bei Antworten mit 429, 500, 502, 503 und 504 automatisch wiederholt, jedoch nur für die sicheren Methoden: GET, HEAD und OPTIONS. Schreibanfragen (POST, DELETE) werden genau einmal gesendet und lösen bei einem Fehler sofort eine Ausnahme aus. Standardmäßig erfolgen 2 Wiederholungsversuche mit exponentiell zunehmender Wartezeit und einem Backoff-Faktor von 0,5 Sekunden. Retry-After-Header werden berücksichtigt, sodass bei einem 429, der eine Wartezeit angibt, die Anfrage nach genau dieser Zeit wiederholt wird.

Die v4-API unterstützt Idempotency-Key nicht und erkennt keine wiederholten Schreibvorgänge. Daher kann ein Schreibvorgang, der das Zeitlimit überschreitet oder 5xx zurückgibt, bereits dauerhaft gespeichert worden sein. Eine ungeprüfte Wiederholung würde einen zweiten Standort, Beitrag oder eine zweite Antwort auf eine Bewertung erstellen. Lesen Sie den Datensatz anhand eines von Ihnen kontrollierten Schlüssels erneut aus, bevor Sie einen Schreibvorgang wiederholen.

Python
# More aggressive retry for long-running batch jobsclient = listingsapi.ListingsAPI(max_retries=5) # Disable retries entirely (e.g. when you want fast failures)client = listingsapi.ListingsAPI(max_retries=0)

Ein 429, der auch nach allen Wiederholungsversuchen weiterhin auftritt, wird als RateLimitError ausgelöst; unter Fehlerbehandlung finden Sie eine Anleitung zur manuellen Umsetzung von Backoff.

Basis-URL überschreiben

Nützlich für Staging-Umgebungen oder interne Proxys:

Python
client = listingsapi.ListingsAPI(base_url="https://staging.example.com")

Der abschließende Schrägstrich wird automatisch entfernt. Alle Anfragen werden unter dem Pfad /api/v4/ an diesen Ursprung gesendet.

Protokollierung

Das SDK protokolliert über das Standardmodul logging mit dem Logger listingsapi. Auf der Stufe DEBUG erfasst es die Methode und die URL jeder Anfrage (sowie die Abfrageparameter für GET); Anfrageinhalte und Ihr API-Schlüssel werden niemals protokolliert.

Python
import logginglogging.basicConfig()logging.getLogger("listingsapi").setLevel(logging.DEBUG) import listingsapiclient = listingsapi.ListingsAPI()client.locations.list(first=1)

Nächste Schritte