Standorte

Standort-Endpunkte in Nutzungsreihenfolge mit cURL, Python und Node: Liste, Suche, ID-/Filialcode-Abruf, Erstellen, Aktualisieren, Archivieren, Fotos.

Einträge, Bewertungen, Beiträge und Analysedaten sind jeweils einer Standort-ID zugeordnet. Die Standort-Ressource umfasst dreizehn Endpunkte: vier Lese-Endpunkte zum Finden von Standorten, vier Schreib-Endpunkte zum Erstellen, Ändern und Archivieren von Standorten und fünf zur Verwaltung von Fotos. Ein Schlüssel mit Read (Lesezugriff) deckt die Leseoperationen ab. Jeder POST benötigt einen Schlüssel mit Write (Schreibzugriff); bei einer Schreiboperation mit einem Read-Schlüssel gibt der Endpunkt HTTP 400 mit SY90016 zurück.

Jede ID in dieser Anleitung ist eine Base64-Relay-ID, zum Beispiel TG9jYXRpb246MTgwMDI4OQ== (dekodiert: Location:1800289). Beide SDKs akzeptieren auch den numerischen Wert databaseId und kodieren ihn für Sie.

Endpunkte auf einen Blick

MethodePfadFunktionReferenz
GET/locationsAlle Standorte seitenweise abrufen, die neuesten zuerst.Alle Standorte auflisten
GET/locations/searchStandorte anhand eines Suchbegriffs in Name, Adresse und Filial-ID finden.Standorte suchen
GET/locations-by-idsVollständige Datensätze für mehrere Base64-IDs abrufen.Standorte anhand von IDs abrufen
GET/locations-by-store-codesVollständige Datensätze anhand Ihrer eigenen Filialcodes abrufen.Standorte anhand von Filialcodes abrufen
POST/locationsEinen Standort erstellen und zur Übermittlung in die Warteschlange stellen.Einen Standort erstellen
POST/locations/updateBeliebige beschreibbare Felder eines einzelnen Standorts ändern.Einen Standort aktualisieren
POST/locations/archiveStandorte zur Archivierung am Ende des Abrechnungszeitraums vormerken.Standorte archivieren
POST/locations/cancel_archiveZur Archivierung vorgemerkte Standorte wieder auf aktiv setzen.Geplante Archivierung abbrechen
POST/locations/photosEin Logo, ein Titelbild oder Galeriefotos per URL hinzufügen.Fotos hochladen
GET/locations/photos/requests/{requestId}Den Status eines Massen-Uploads in der Warteschlange wiederholt abfragen.Status eines Massen-Uploads prüfen
GET/locations/{locationId}/photosAlle Mediendateien eines Standorts auflisten.Fotos abrufen
POST/locations/photos/starZusätzliche Fotos mit einem Stern markieren oder die Markierung entfernen.Fotos mit einem Stern markieren
POST/locations/photos/removeDie Zuordnung zusätzlicher Fotos aufheben.Fotos entfernen

Alle Standorte auflisten

GET /locations ruft alle Standorte im Konto seitenweise ab, die neuesten zuerst. Die Antwort ist eine Cursor-Connection: edges[].node enthält die einzelnen Datensätze, und pageInfo.endCursor liefert den Wert für den Parameter after für die nächste Seite. Verwenden Sie diesen Endpunkt, um das gesamte Konto mit Ihrem eigenen System zu synchronisieren.

Parameter

NameInErforderlichHinweise
firstqueryNeinSeitengröße beim Vorwärtsblättern. Standard: 50. Kombinieren Sie diesen Parameter mit after.
afterqueryNeinDer Wert von pageInfo.endCursor auf der vorherigen Seite.
lastqueryNeinSeitengröße beim Rückwärtsblättern. Kombinieren Sie diesen Parameter mit before.
beforequeryNeinDer Wert von cursor der ersten Edge auf der Seite, von der aus Sie zurückblättern. pageInfo enthält kein startCursor.
filterqueryNeinJSON-kodiertes Objekt zum serverseitigen Eingrenzen der Ergebnismenge, zum Beispiel nach Genehmigungsstatus. Keine der beiden SDK-Listenmethoden akzeptiert es; verwenden Sie REST, um eine gefilterte Teilmenge abzurufen.
List
curl "https://listingsapi.com/api/v4/locations?first=50" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "storeId": null,            "approved": "APPROVED",            "archived": false,            "archivalScheduledAt": null,            "city": "Austin",            "stateIso": "TX",            "countryIso": "US",            "subCategoryId": 1432,            "planName": "Launch",            "placeActionLinks": [],            "discoveredPlaceActionLinks": []          }        }      ],      "pageInfo": {        "hasNextPage": false,        "hasPreviousPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "total": 1      }    }  }}

Lesen Sie pageInfo.hasNextPage aus und beenden Sie den Abruf, wenn der Wert false ist. Die Anzahl auf Seitenebene steht in pageInfo.total. Das Feld id des Knotens enthält die Kennung, die alle anderen Endpunkte erwarten.

Standorte suchen

GET /locations/search gleicht einen Suchbegriff mit dem Standortnamen, der Straßenadresse, der Stadt und der Filial-ID ab. Die Antwort ist eine Cursor-Connection mit derselben Struktur für edges[].node und pageInfo.endCursor wie beim Auflisten. Verwenden Sie diesen Endpunkt für ein Auswahlfeld mit Suchvorschlägen während der Eingabe oder um vor dem Erstellen einer Filiale zu prüfen, ob sie bereits vorhanden ist.

Parameter

NameInErforderlichHinweise
queryqueryNeinDer Suchbegriff. Lassen Sie ihn weg, um alle Standorte ungefiltert seitenweise abzurufen.
firstqueryNeinSeitengröße. Standard: 50.
afterqueryNeinDer Wert von pageInfo.endCursor auf der vorherigen Seite.
filterqueryNeinJSON-kodiertes Filterobjekt wie beim Endpunkt zum Auflisten.

Beide SDKs akzeptieren außerdem eine Liste für fields, um den Abgleich auf bestimmte Felder zu beschränken, zum Beispiel nur auf name.

Search
curl "https://listingsapi.com/api/v4/locations/search?query=Jenny&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "storeId": null,            "street": "600 Congress Ave, Suite 200",            "city": "Austin",            "approved": "APPROVED",            "archived": false          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "hasPreviousPage": false,        "total": 1      }    }  }}

Ein leeres edges-Array bedeutet, dass keine Treffer gefunden wurden. Der Knoten enthält die vollständige Adresse, die Kategorie und den approved-Status, sodass für eine Ergebniszeile kein zweiter Abruf erforderlich ist.

Standorte anhand von IDs abrufen

GET /locations-by-ids gibt die vollständigen Datensätze für mehrere Base64-IDs in einem einzigen Aufruf zurück und benötigt damit weniger Anfragen als ein Aufruf pro Standort. Sowohl aktive als auch archivierte Standorte werden gefunden. Die Rückgabe ist ein einfaches Array, keine Connection. Verwenden Sie diesen Aufruf, um IDs aus einer Webhook-Payload oder Ihrem eigenen Datenspeicher um die vollständigen Datensätze zu ergänzen.

Parameter

NamePositionErforderlichHinweise
idsqueryJaJSON-kodiertes Array von Base64-IDs. Kodieren Sie den gesamten Wert für die URL; curl -G --data-urlencode übernimmt dies für Sie.
By ids
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationsByIds": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": null,        "name": "Jenny Home",        "archived": false,        "archivedAt": null,        "city": "Austin",        "stateIso": "TX",        "countryIso": "US",        "subCategoryId": 1432,        "businessHours": [],        "locationPhotos": [],        "placeActionLinks": [],        "discoveredPlaceActionLinks": []      }    ]  }}

IDs, die in Ihrem Konto nicht existieren, werden ohne Fehlermeldung weggelassen. Vergleichen Sie die Anzahl der zurückgegebenen Datensätze mit der Anzahl der gesendeten IDs, um veraltete IDs zu erkennen.

Standorte anhand von Filialcodes abrufen

GET /locations-by-store-codes ermöglicht die umgekehrte Suche: Der Aufruf löst Ihre eigenen Filialcodes in vollständige Datensätze auf. Er gibt ein einfaches Array zurück. Verwenden Sie ihn, wenn Ihr Kassensystem oder Ihr Franchise-Verzeichnis Standorte anhand von Filialcodes identifiziert und Sie unsere IDs nie gespeichert haben.

Parameter

NamePositionErforderlichHinweise
storeCodesqueryJaJSON-kodiertes Array von Filialcodes als Zeichenfolgen. Kodieren Sie den gesamten Wert für die URL.
By store codes
curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME01","ACME02"]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationsByStoreCodes": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": "ACME01",        "name": "Jenny Home",        "archived": false,        "city": "Austin",        "countryIso": "US",        "planName": "Launch"      }    ]  }}

Ordnen Sie den Wert von storeId jedes Objekts Ihrem Verzeichnis zu. Codes ohne Treffer fehlen in der Rückgabe. Ein Standort hat nur dann einen Filialcode, wenn storeId beim Erstellen oder Aktualisieren gesetzt wurde.

Einen Standort erstellen

POST /locations erstellt einen Standort und stellt ihn zur Übermittlung an alle Plattformen Ihres Tarifs in die Warteschlange oder nur an enabledSiteIds, wenn Sie dieses Feld übergeben. Alle Felder werden unter input angegeben. 10 Felder sind Pflichtfelder; die übrigen sind optional, und alle weggelassenen Felder werden von den Plattformen leer angezeigt.

Parameter

NamePositionErforderlichHinweise
input.namebodyJaUnternehmensname, 2 bis 150 Zeichen.
input.descriptionbodyJaMindestens 200 Zeichen (SY10005). Plattformen verwenden diesen Wert als Text des Eintrags.
input.countryIsobodyJaEin unterstützter Ländercode (SY10036). Aus Länder.
input.citybodyJaErforderlich, wenn hasCity des Landes gleich true ist (SY10126). Ist der Wert false, wird eine von Ihnen gesendete Stadt verworfen.
input.subCategoryIdbodyJaNumerischer Wert für databaseId aus Unterkategorien.
input.streetbodyJa5 bis 100 Zeichen (SY10011).
input.stateIsobodyJaErforderlich, wenn stateRequired des Landes gleich true ist; der Wert muss zu den states dieses Landes gehören (SY10010). Lassen Sie das Feld weg, wenn stateRequired gleich false ist.
input.phonebodyJaWird anhand des Landes validiert (SY10015).
input.postalCodebodyNeinOptional, sollte aber immer gesendet werden, wenn hasPostalCode des Landes gleich true ist. Ein gesendeter Wert muss dem Format des Landes entsprechen (SY10014).
input.bizUrlbodyJaWird als Website veröffentlicht. Einige Plattformen lehnen einen Eintrag ohne Website ab.
input.storeIdbodyNeinIhr eigener Filialcode, der innerhalb des Kontos eindeutig ist.
input.businessHoursbodyNein7 Einträge mit { day, type, slots }. type ist entweder OPEN oder CLOSED; an einem geschlossenen Tag ist slots leer.
input.placeActionLinksbodyNeinGoogle-Aktionslinks: placeActionType, uri, optional isPreferred. Beim Erstellen ist kein action erforderlich. Siehe Aktionslinks für Orte.
input.enabledSiteIdsbodyNeinAuf einer Teilmenge der Websites Ihres Tarifs veröffentlichen. IDs aus Websites des Tarifs.
input.clientMutationIdbodyNeinWird zur Zuordnung unverändert zurückgegeben. Verhindert keine doppelten Schreibvorgänge.

Hinzu kommen die auf der Referenzseite aufgeführten optionalen Felder: Google-GCID-Kategorien, URLs sozialer Netzwerke, Koordinaten, Kontaktdaten des Inhabers, Zahlungsmethoden, Einzugsgebiet und weitere.

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",    "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 growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",    "storeId": "ACME01",    "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": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY", "type": "CLOSED", "slots": [] }    ],    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true }    ]  }}'
JSON
{  "data": {    "createLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME01",        "name": "Acme Kitchen",        "city": "New York",        "countryIso": "US",        "status": "PENDING",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

Bewahren Sie beide IDs auf: Die Base64-ID id wird für jeden späteren Schreibvorgang benötigt, und databaseId ist die Nummer, die Sie in Dashboards und Webhooks sehen. status beginnt mit dem Wert PENDING und wird ohne weiteren API-Aufruf fortgeschrieben. Die Werte name und submissionStatus eines Aktionslinks für einen Ort bleiben auf null, bis der Link mit Google synchronisiert wurde. In Python validiert locations.add() die Pflichtfelder lokal und löst ValidationError vor jedem Netzwerkaufruf aus; locations.create(input) akzeptiert stattdessen ein unverarbeitetes camelCase-dict.

Einen Standort aktualisieren

POST /locations/update ist eine Teilaktualisierung: input.id ist das einzige Pflichtfeld, und nur die von Ihnen gesendeten Felder werden geändert. Mit demselben Aufruf können Sie eine Telefonnummer korrigieren oder den Wochenplan neu festlegen. locations.update() in Python und updateLocation() in Node nehmen jeweils ein camelCase-Objekt entgegen.

Parameter

NameInErforderlichHinweise
input.idbodyJaDie base64-ID des Standorts. Das Feld heißt id, nicht locationId.
input.phone, input.bizUrl, input.name, AdressfelderbodyNeinJedes beschreibbare Feld aus dem Aufruf zum Erstellen.
input.businessHoursbodyNeinSenden Sie alle sieben Tage; eine unvollständige Woche wird abgelehnt. Fügen Sie für abweichende Feiertagszeiten day: "SPECIAL"-Einträge mit einem specialDate hinzu, zusätzlich zur Woche und niemals an ihrer Stelle.
input.moreHoursbodyNeinZusätzliche Zeitpläne, etwa für Lieferungen, jeweils { hoursTypeId, moreHour }. Hier kein specialDate.
input.temporarilyClosedbodyNeintrue stoppt die Veröffentlichung der Öffnungszeiten, solange der Standort geschlossen ist.
input.primaryGbpSiteCategoryId, input.additionalGbpSiteCategoryIdsbodyNeinGoogle-Kategorien als GCIDs, zum Beispiel gcid:restaurant. Senden Sie countryIso zusammen mit ihnen.
input.placeActionLinksbodyNeinAnhängen oder per Upsert aktualisieren bzw. einfügen: Jedes Element nimmt für action den Wert add (Standard) oder delete entgegen. Links, die Sie nicht angeben, bleiben unverändert.
input.submissionDisabledSiteIdsbodyNeinWebsite-IDs, die von der Übermittlung ausgeschlossen werden sollen.

Hinzu kommen die optionalen Felder, die auf der Referenzseite aufgeführt sind.

Update
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "businessHours": [      { "day": "MONDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY", "type": "CLOSED", "slots": [] }    ]  }}'
JSON
{  "data": {    "updateLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "status": "APPROVED",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

Die Antwort enthält den aktualisierten Standort, damit Sie prüfen können, ob die neuen Werte übernommen wurden. Jede Aktualisierung gibt die vollständige aktuelle placeActionLinks-Menge des Standorts zurück. Um die URL eines Links zu ändern, senden Sie in derselben Anfrage ein delete für den alten Link und ein add für den neuen.

Standorte archivieren

POST /locations/archive plant die Archivierung eines oder mehrerer Standorte. Die Archivierung erfolgt nicht sofort: Jeder Standort wechselt in ARCHIVE_SCHEDULED, bleibt bis zum Ende des aktuellen Abrechnungszeitraums aktiv und kostenpflichtig und wird archiviert, wenn die nächste Rechnung erstellt wird. Verwenden Sie diesen Aufruf, um geschlossene Filialen gesammelt abzumelden.

Parameter

NameInErforderlichHinweise
input.locationIdsbodyJaArray von base64-IDs der zu archivierenden Standorte.
input.clientMutationIdbodyNeinWird unverändert zurückgegeben. Verhindert keine doppelten Schreibvorgänge.
Archive
curl -X POST https://listingsapi.com/api/v4/locations/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA=="]  }}'
JSON
{  "data": {    "archiveLocations": {      "clientMutationId": null,      "bulkEditTaskId": null,      "errors": null,      "success": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null },        { "locationId": "TG9jYXRpb246MTgwMDI5MA==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null }      ]    }  }}

success auf der obersten Ebene ist null; lesen Sie stattdessen den jeweiligen success-Wert jedes result[]-Eintrags aus, damit eine fehlerhafte ID den Rest des Stapels nicht blockiert.

result[].statusBedeutung
ARCHIVE_SCHEDULEDIn die Warteschlange aufgenommen. Der Standort bleibt bis zum Ende des Abrechnungszeitraums aktiv und kostenpflichtig.
ARCHIVEDBereits durch einen früheren Aufruf oder in einem früheren Abrechnungszeitraum archiviert.

Solange die Archivierung geplant ist, ist archivalScheduledAt für den Standort in Listen- und Suchergebnissen gesetzt. Ein archivierter Standort kann erst nach seiner Reaktivierung aktualisiert werden.

Geplante Archivierung abbrechen

POST /locations/cancel_archive versetzt Standorte in ARCHIVE_SCHEDULED zurück in ACTIVE, und die Abrechnung läuft weiter. Dies funktioniert nur, solange der Abrechnungszeitraum noch nicht abgeschlossen ist; sobald ein Standort vollständig archiviert ist, gibt dieser Aufruf für ihn 404 zurück.

Parameter

NameInErforderlichHinweise
input.locationIdsbodyJaArray von base64-IDs der Standorte, die sich derzeit in ARCHIVE_SCHEDULED befinden.
input.clientMutationIdbodyNeinWird unverändert zurückgegeben.
Cancel archive
curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'
JSON
{  "data": {    "cancelLocationsArchive": {      "clientMutationId": null,      "bulkEditTaskId": null,      "errors": null,      "success": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null }      ]    }  }}

Jeder result[]-Eintrag bestätigt, dass sich der Standort wieder in ACTIVE befindet. Beide SDKs erfordern zwei zusätzliche positionale Argumente, einen Auswahltyp und eine changedBy-Kennung, die sie zusammen mit locationIds senden; der REST-Body benötigt nur die IDs.

Fotos zu einem Standort hochladen

POST /locations/photos fügt Bilder über eine öffentliche URL hinzu: Sie hosten das Bild, die API ruft es ab und speichert es. Ein Standort speichert ein LOGO, ein COVER und beliebig viele ADDITIONAL-Fotos. Wenn Sie ein Logo oder Titelbild erneut hochladen, ersetzt es das vorhandene.

Parameter

NameInErforderlichHinweise
input.locationIdbodyJaDie base64-ID des Standorts.
input.photosbodyJaArray von Bildobjekten; darf nicht leer sein.
input.photos[].photobodyJaEine öffentliche URL zu einem JPEG- oder PNG-Bild. Das Feld heißt photo, nicht url.
input.photos[].typebodyNeinLOGO, COVER oder ADDITIONAL. Standardmäßig wird ein zusätzliches Foto hinzugefügt.
input.photos[].starredbodyNeinMarkieren Sie das Foto direkt beim Hochladen mit einem Stern. Nur für zusätzliche Fotos, höchstens 4 pro Standort.
input.photos[].sourcebodyNeinFreitextbezeichnung, die die Herkunft des Bildes festhält.
Upload
curl -X POST https://listingsapi.com/api/v4/locations/photos \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'
JSON
{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {},      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "databaseId": 5878931, "type": "LOGO", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png" },        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg" }      ],      "errors": null    }  }}

Bewahren Sie id für jedes Foto auf; die Endpunkte zum Markieren mit einem Stern und zum Entfernen nehmen diesen Wert entgegen. Dies ist das Inline-Format für einen kleinen Stapel. Ein großer Stapel wird stattdessen in die Warteschlange aufgenommen: photos wird leer zurückgegeben und request.requestId ist gesetzt, und Sie fragen den nächsten Endpunkt mit dieser ID regelmäßig ab. Der Schwellenwert wird serverseitig konfiguriert; verzweigen Sie daher danach, ob request.requestId vorhanden ist.

Status des Foto-Sammeluploads prüfen

GET /locations/photos/requests/{requestId} fragt den Status eines Uploads in der Warteschlange ab, bis er abgeschlossen ist, und meldet dann das Ergebnis für jedes Bild. Verwenden Sie dies, um einen Fortschrittsbalken zu steuern und genau anzuzeigen, welche Dateien abgelehnt wurden und warum.

Parameter

NameInErforderlichHinweise
requestIdpathJaDie UUID aus request.requestId in der Antwort auf einen Upload, der in die Warteschlange gestellt wurde. Fragen Sie nur IDs ab, die von einem kürzlich erfolgten Upload zurückgegeben wurden.
Upload status
curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationPhotosUploadStatus": {      "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",      "status": "SUCCESS",      "photos": [        { "mediaId": "TWVkaWFGaWxlOjkxODI3", "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "SUCCESS", "errorMessage": null },        { "mediaId": null, "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ERROR", "errorMessage": "Image dimensions below the minimum 250x250." }      ]    }  }}
Auftrag statusBedeutung
PROCESSINGDie Verarbeitung läuft noch. Fragen Sie den Status nach einigen Sekunden erneut ab.
SUCCESSDie Verarbeitung ist abgeschlossen. Einzelne Fotos können dennoch fehlgeschlagen sein; lesen Sie daher photos[].status und photos[].errorMessage.
ERRORDer Auftrag selbst ist fehlgeschlagen. Prüfen Sie photos[].errorMessage.

Der Auftragsstatus besagt nur, dass die Verarbeitung abgeschlossen ist, nicht, dass jedes Bild erfolgreich hochgeladen wurde. Warten Sie zwischen den Statusabfragen einige Sekunden; eine Schleife ohne ausreichende Pausen führt hier schnell zu 429.

Fotos für einen Standort abrufen

GET /locations/{locationId}/photos gibt alle Mediendateien eines Standorts als einfaches Array zurück: Logo, Titelbild und zusätzliche Bilder, jeweils mit dem öffentlichen url, thumbnailUrl, der Kategorie, dem Flag starred und viewsCount über die gesamte Laufzeit. Rufen Sie den Endpunkt vor einem Upload auf, um zu sehen, welcher Bildplatz noch nicht belegt ist, und um IDs für die Aufrufe zum Markieren mit einem Stern und zum Entfernen zu sammeln.

Parameter

NameInErforderlichHinweise
locationIdpathJaDie base64-ID. Der unverarbeitete numerische Wert databaseId wird ebenfalls akzeptiert. Bei einem Wert, der keinem der beiden Formate entspricht, gibt der Endpunkt HTTP 200 mit SY90002: Invalid Id in errors zurück.
List photos
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "fileType": "image", "starred": false, "viewsCount": 0,        "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.jpg",        "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_f47d62a6.jpg" },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "fileType": "image", "starred": true, "viewsCount": 143,        "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg",        "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_ef4ffb12.jpg" }    ]  }}

categoryName ist Logo, Cover oder Additional. Verwenden Sie thumbnailUrl für eine Rasteransicht und url für die Ansicht in voller Größe. Bei einem Standort ohne Medien wird ein leeres Array zurückgegeben, kein Fehler.

Standortfotos mit einem Stern markieren

POST /locations/photos/star markiert zusätzliche Fotos für eine bevorzugte Platzierung auf Plattformen, die hervorgehobene Bilder unterstützen. Nur Fotos vom Typ ADDITIONAL können mit einem Stern markiert werden, höchstens 4 pro Standort. Das Entfernen der Sternmarkierung funktioniert genauso: Das Flag starred im Body bestimmt, was geschieht.

Parameter

NameInErforderlichHinweise
input.locationIdbodyJaDie base64-ID des Standorts.
input.photoIdsbodyJaMedien-IDs aus der Antwort auf den Fotoabruf oder den Upload.
input.starredbodyJatrue zum Markieren mit einem Stern, false zum Entfernen der Sternmarkierung. Dieses Flag entscheidet, nicht der Pfad; /star und /unstar verhalten sich gleich.
Star
curl -X POST https://listingsapi.com/api/v4/locations/photos/star \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="],    "starred": true  }}'
JSON
{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

Der Antwortschlüssel lautet bei beiden Pfaden starUnstarLocationPhotos und enthält einen einzelnen Wert error, kein Array errors. Ein fünftes mit einem Stern markiertes Foto lässt den gesamten Aufruf mit SY15012 fehlschlagen; bei der Prüfung werden bereits mit einem Stern markierte Fotos und die Fotos in dieser Anfrage zusammengezählt.

Fotos von einem Standort entfernen

POST /locations/photos/remove hebt anhand der Medien-ID die Zuordnung zusätzlicher Fotos auf. Verwenden Sie dies, um veraltete Bilder der Geschäftsfront zu entfernen oder einen fehlerhaften Sammelimport rückgängig zu machen. Nur Fotos vom Typ ADDITIONAL können entfernt werden; ersetzen Sie ein Logo oder Titelbild, indem Sie ein neues Bild mit diesem type hochladen.

Parameter

NameInErforderlichHinweise
input.locationIdbodyJaDie base64-ID des Standorts.
input.photoIdsbodyJaMedien-IDs, deren Zuordnung aufgehoben werden soll, aus der Antwort auf den Fotoabruf oder den Upload.
Remove
curl -X POST https://listingsapi.com/api/v4/locations/photos/remove \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="]  }}'
JSON
{  "data": {    "removeLocationPhotos": {      "clientMutationId": null,      "removedCount": 1,      "errors": null    }  }}

removedCount gibt an, für wie viele Dateien die Zuordnung tatsächlich aufgehoben wurde; 0 mit errors: null bedeutet daher, dass keine dieser IDs diesem Standort zugeordnet war. Beim Entfernen wird die Zuordnung der Datei aufgehoben; die Datei wird dabei nicht unbedingt aus Ihrer Medienbibliothek gelöscht.

Auftretende Fehler

CodeBedeutungBehebung
SY10005description fehlt beim Erstellen oder umfasst weniger als 200 Zeichen.Schreiben Sie eine ausführlichere Beschreibung.
SY10011street fehlt oder ist kürzer als 5 Zeichen.Senden Sie street.
SY10010stateIso fehlt oder ist für das Land ungültig.Senden Sie einen Bundeslandcode aus countries.
SY10036countryIso ist kein unterstütztes Land.Verwenden Sie einen Code aus countries.
SY10126city fehlt für ein Land, in dem diese Angabe erforderlich ist.Senden Sie city.
SY15012Mehr als 4 mit einem Stern markierte Fotos an einem Standort.Entfernen Sie zuerst die Sternmarkierung eines Fotos oder lassen Sie starred beim Upload weg.
SY90002Ungültige ID im Fotopfad.Übergeben Sie die base64-ID oder die reine Zahl, kein anderes Format.
SY90016Für einen Schreibvorgang wurde ein Read-Schlüssel verwendet.Verwenden Sie einen Write-Schlüssel.
HTTP 404Abbruch der Archivierung eines Standorts, der nicht mehr den Status ARCHIVE_SCHEDULED hat.Der Standort ist vollständig archiviert; verwenden Sie stattdessen den Ablauf zur Reaktivierung.
HTTP 429Anfragelimit überschritten.Warten Sie gemäß Retry-After. Siehe Anfragelimits.

Schreibvorgänge können auch HTTP 200 mit success: false und den Details in data.<operation>.errors zurückgeben. Die vollständige Liste finden Sie unter Fehlercodes.

Nächste Schritte