Listings APIListings API
Anmelden

Führen Sie Ihren ersten API-Aufruf aus

Authentifizieren Sie sich, listen Sie Ihre Standorte auf, lesen Sie das Antwortformat, blättern Sie durch Ergebnisse und lernen Sie, wie IDs funktionieren.

Diese Anleitung setzt voraus, dass Sie ein Konto und einen API-Schlüssel aus Erste Schritte haben. Jede Anfrage wird an die Live-API unter https://listingsapi.com gesendet, sodass ein Schreibaufruf mit einem regulären API-Schlüssel echte Daten ändert. Um die API ohne Auswirkungen auf echte Plattformen auszuprobieren, verwenden Sie den kostenlosen Sandbox-Tagespass.

1. API-Schlüssel festlegen

Kopieren Sie den Schlüssel aus API-Schlüssel im Dashboard und exportieren Sie ihn einmal in Ihrer Shell:

bash
export LISTINGSAPI_KEY="your-api-key"

Schlüssel haben eine Zugriffsstufe. Ein Schlüssel mit Read (Lesezugriff) deckt alle Abfragen und Berichte in diesen Anleitungen ab. Zum Erstellen oder Aktualisieren von Daten, zum Antworten auf eine Bewertung oder zum Veröffentlichen eines Beitrags benötigen Sie einen Schlüssel mit Write (Schreibzugriff). Wenn Sie einen Read-Schlüssel an einen Schreibendpunkt senden, gibt dieser HTTP 400 mit dem Fehlercode SY90016 zurück.

2. Ihre Standorte auflisten

Andere Endpunkte referenzieren einen Standort anhand seiner ID. Listen Sie daher zunächst Ihre vorhandenen Standorte auf. Der REST-Header Authorization verwendet das Schema API, gefolgt von einem Leerzeichen und Ihrem API-Schlüssel: Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. Antwort lesen

Die REST API gibt eine verschachtelte Antwort statt eines einfachen Arrays zurück. Der Name der Operation steht unter data, Listenergebnisse werden als Connection aus edges zurückgegeben, und jede Edge enthält ein node:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

Das Python SDK gibt eine iterierbare Seite mit Objekten zurück. Das Node SDK gibt locations und pageInfo zurück. Wenn Sie die REST API direkt aufrufen, lesen Sie data.allLocations.edges[].node aus.

4. Ergebnisse seitenweise abrufen

Listenendpunkte für Standorte und Bewertungen verwenden eine cursorbasierte Paginierung. Fordern Sie eine Seite mit first an und übergeben Sie dann pageInfo.endCursor als after, um die nächste Seite abzurufen. Die SDKs können alle Seiten für Sie abrufen.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

Nicht jeder Endpunkt verwendet diese Art der Paginierung. Verbundene Konten, Duplikatzusammenfassungen und Beiträge verwenden page und perPage mit einem records-Array. Jede Anleitung gibt an, welches Paginierungsformat ihre Endpunkte verwenden.

5. Zwei Arten von IDs

Jeder Datensatz hat zwei Kennungen. id ist eine base64-Zeichenfolge wie TG9jYXRpb246MTgwMDI4OQ==, die dekodiert Location:1800289 ergibt. databaseId ist die reine Zahl, 1800289.

Speichern Sie die base64-kodierte id. Jeder Schreibendpunkt erfordert base64-kodierte IDs, und diese Werte werden auch in Webhook-Payloads zurückgegeben. Viele Leseendpunkte, die einen Standort im Pfad erwarten, akzeptieren auch die reine Zahl, und beide SDKs akzeptieren beide Formen und übernehmen die Kodierung für Sie.

6. Fehler und Anfragelimits

Antworten auf fehlgeschlagene Anfragen enthalten den entsprechenden HTTP-Status und ein errors-Array. Der Nachricht ist ein SY-Fehlercode vorangestellt, der unter Fehlercodes aufgeführt ist:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

Die Anfragelimits hängen vom Tarif ab und werden pro Minute, Stunde und Tag gezählt. Launch erlaubt 10 Anfragen pro Minute. Wenn Sie ein Limit überschreiten, gibt die API 429 mit einem Retry-After-Header zurück; warten Sie die darin angegebene Anzahl an Sekunden, bevor Sie es erneut versuchen. Die SDKs lösen RateLimitError aus und stellen denselben Wert bereit. Alle Einzelheiten finden Sie unter Anfragelimits.

Nächste Schritte