Listings APIListings API
Anmelden

Einen Standort hinzufügen

Erstellen Sie einen Standort mit nötigen Feldern der Plattformen, behandeln Sie Validierungsfehler und bestätigen Sie die Einreihung zur Übermittlung.

Einträge, Bewertungen, Beiträge und Analysedaten sind alle einer Standort-ID zugeordnet. POST /api/v4/locations erstellt den Standort und stellt für jede Plattform in Ihrem Tarif einen Eintrag in die Warteschlange.

1. Die erforderlichen Felder zusammenstellen

Zehn Felder sind erforderlich. Ein Unternehmen mit Einzugsgebiet übermittelt ebenfalls die vollständige Adresse: Mit hideAddress: true speichert ListingsAPI die Adresse, übermittelt sie jedoch nicht an die Plattformen. Plattformen zeigen ausgelassene optionale Felder als leer an. Übermitteln Sie daher alle verfügbaren Angaben.

FeldErforderlichHinweise
nameJa2 bis 150 Zeichen.
descriptionJaMindestens 200 Zeichen (SY10005).
countryIsoJaZweistelliger Buchstabencode eines unterstützten Landes (SY10036).
cityJaErforderlich, wenn hasCity des Landes den Wert true hat (SY10126). Bei einem Wert von false wird eine von Ihnen übermittelte Stadt verworfen.
subCategoryIdJaNumerischer Wert für databaseId aus der Liste der Unterkategorien.
streetJa5 bis 100 Zeichen (SY10011).
stateIsoJaErforderlich, wenn stateRequired des Landes den Wert true hat; der Wert muss einem der states dieses Landes entsprechen (SY10010). Lassen Sie das Feld weg, wenn stateRequired den Wert false hat.
postalCodeNeinOptional, aber übermitteln Sie das Feld immer, wenn hasPostalCode des Landes den Wert true hat. Ein übermittelter Wert muss dem Format des Landes entsprechen (SY10014).
phoneJaWird anhand des Landes validiert (SY10015).
bizUrlJaWird als Website veröffentlicht. Einige Plattformen lehnen einen Eintrag ohne Website ab.
storeIdNeinIhr eigener Filialcode, der innerhalb des Kontos eindeutig ist. Verwenden Sie ihn, um den Standort wiederzufinden, ohne unsere IDs zu speichern.
businessHoursNeinEin Eintrag pro Wochentag. Das Format finden Sie unter Einen Standort aktualisieren.

2. Den Standort erstellen

POST /api/v4/locations nimmt die Felder in einem input-Objekt im JSON-Anfragetext entgegen. Die Python SDK-Methode locations.add() nimmt dieselben Felder als Schlüsselwortargumente entgegen und validiert die erforderlichen Felder, bevor sie die Anfrage sendet. Die Node SDK-Methode createLocation() nimmt das camelCase-Objekt direkt entgegen.

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "storeId": "ACME-NYC-001",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

3. Die Antwort auswerten

Ein erfolgreicher Erstellungsvorgang gibt success: true und den neuen Standort in data.createLocation.location zurück. Bewahren Sie beide Kennungen auf: id ist der Base64-Wert, den jeder spätere Schreibvorgang entgegennimmt, und databaseId ist der numerische Wert, der in Dashboards und Webhook-Payloads angezeigt wird.

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

status hat den Wert PENDING, während der Standort validiert und in die Warteschlange aufgenommen wird. Der Status ändert sich ohne weiteren API-Aufruf.

4. Validierungsfehler behandeln

Ein Erstellungsvorgang kann an zwei Stellen fehlschlagen. Bei einer fehlerhaft formatierten Anfrage oder einem ungültigen Schlüssel wird 4xx mit einem errors-Array auf oberster Ebene zurückgegeben. Bei einer korrekt formatierten Anfrage mit einem Feld, das die API ablehnt, wird 200 mit success: false und dem Problem innerhalb von data.createLocation.errors zurückgegeben. Prüfen Sie daher bei jedem Schreibvorgang den Antworttext und nicht nur den Statuscode.

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

Beide SDKs lösen bei einem Fehler eine Ausnahme aus. Die Python-Methode locations.add() prüft die erforderlichen Felder lokal und löst vor dem Senden der Anfrage ValidationError aus. Die Node-Methode createLocation() löst ValidationError aus, wenn die API die Eingabe ablehnt. Deshalb prüft das obige Beispiel kein Erfolgsflag.

Die Codes, denen Sie am häufigsten begegnen werden:

CodeUrsacheBehebung
SY10005Die Beschreibung fehlt oder umfasst weniger als 200 Zeichen.Verfassen Sie eine ausführlichere Beschreibung.
SY10011street fehlt oder ist kürzer als 5 Zeichen.Übermitteln Sie street.
SY10010stateIso fehlt oder ist für das Land ungültig.Übermitteln Sie einen Bundesstaatencode aus dem Länder-Endpunkt.
SY10036countryIso ist kein unterstütztes Land.Verwenden Sie einen Code aus dem Länder-Endpunkt.
SY10126city fehlt für ein Land, in dem dieses Feld erforderlich ist.Übermitteln Sie city.
SY90016Der Schlüssel hat nur Lesezugriff.Verwenden Sie einen Schlüssel mit Schreibzugriff.

5. Bestätigen Sie, dass die Übermittlung begonnen hat

Beim Erstellen des Standorts wird für jede Plattform in Ihrem Tarif ein Eintrag in die Warteschlange gestellt. Jeder Eintrag beginnt mit AVAILABLE oder IN_PROGRESS und wechselt zu SYNCED mit listingUrl, sobald die Plattform ihn akzeptiert.

Listing status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

Wenn Webhooks konfiguriert sind, ist kein Polling erforderlich. Ein profile.created-Ereignis wird ausgelöst, sobald der Datensatz existiert, und ein listing.submission-Ereignis wird für jede Plattform ausgelöst, wenn sich ihr Status ändert.

Nächste Schritte