Fotos zu einem Standort hochladen

Parameter

Body

Ein als erforderlich markiertes verschachteltes Feld gilt nur, wenn Sie das übergeordnete Feld senden. Ist das übergeordnete Feld optional und lassen Sie es weg, gelten seine erforderlichen Unterfelder nicht.

Name	Typ	Erforderlich	Beschreibung
input.locationId	string	erforderlich	The location's Base64-encoded Relay ID to attach media to.
input.photos	array of objects	erforderlich	Images to attach. `photo` is the only required key on each item.
input.photos[].photo	string	erforderlich	A publicly accessible JPEG or PNG URL that Listings API fetches and stores. The field is named `photo`, not `url`.
input.photos[].type	string	optional	Which slot the image fills: `LOGO`, `COVER`, or `ADDITIONAL`. Defaults to an additional photo.
input.photos[].starred	boolean	optional	Star the photo as it is attached, instead of a follow-up call to the star endpoint. Only additional photos can be starred, at most 4 per location.
input.photos[].source	string	optional	Free-text label recording where the image came from.

Beispielanfrage

Body zum direkten Einfügen. Ersetzen Sie Platzhalter-IDs und -Werte durch Ihre eigenen.

Request body

{  "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" }    ]  }}

Antworten

200Photos attached inline. Returns the created photo records; `errors` is null on success and `request` is empty because nothing was queued.

Response

{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {},      "photos": [        {          "id": "TWVkaWFGaWxlOjU4Nzg5MzE=",          "databaseId": 5878931,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png",          "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_f47d62a6.png",          "type": "LOGO",          "starred": false        },        {          "id": "TWVkaWFGaWxlOjU4Nzg5MzI=",          "databaseId": 5878932,          "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",          "type": "ADDITIONAL",          "starred": false        }      ],      "errors": null    }  }}

401Unauthenticated, missing or invalid API key.

Fügt einem Standort ein oder mehrere Bilder hinzu. Geben Sie ein photos-Array an, in dem jedes Element mindestens photo enthält, eine öffentliche Bild-URL, über die die Listings API das Bild abruft und speichert. locationId und ein nicht leeres photos-Array sind immer erforderlich.

Zwei Formen einer erfolgreichen Antwort

Ein kleiner Batch wird direkt hochgeladen: photos enthält die fertig verarbeiteten Medien und request ist ein leeres Objekt, wie im obigen Beispiel. Ein großer Batch wird stattdessen in die Warteschlange gestellt, und dasselbe 200 sieht dann so aus:

JSON

{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {        "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",        "status": "PROCCESSING"      },      "photos": [],      "errors": null    }  }}

Beide Antworten sind erfolgreich. Prüfen Sie daher bei der Verarbeitung, ob request.requestId vorhanden ist, anstatt davon auszugehen, dass photos befüllt ist.

Das URL-Feld heißt photo. Nicht url und nicht image. Daneben akzeptiert jedes Element optional type (LOGO, COVER oder ADDITIONAL), starred und source; für Partnerintegrationen werden auch publisherOverride und partnerMediaId akzeptiert. Ein zurückgegebenes Foto hat kein caption-Feld.

Anwendungsfall: einen neuen Standort mit Bildern ausstatten. Laden Sie direkt nach dem Erstellen eines Standorts wie "Jenny Home" dessen Logo und Fotos der Ladenfront per POST über URLs in einem einzigen Aufruf hoch. Die Antwort liefert für jedes neue Foto dessen id zurück, die Sie später an die Endpunkte zum Markieren mit einem Stern und zum Entfernen übergeben.

Anwendungsfall: ein freigegebenes Bild an mehreren Standorten wiederverwenden. Verweisen Sie in den photos-Arrays mehrerer Standorte auf dieselbe gehostete Bild-URL, damit jeder Standort dasselbe Quellbild verwendet.

Fallstricke.

Bilder müssen im JPEG- oder PNG-Format vorliegen. Die Größenvorgaben der Plattform gelten je Kategorie (eine typische Untergrenze liegt bei etwa 10 KB, die Obergrenze bei einigen MB).
Große Batches werden asynchron verarbeitet. Oberhalb einer serverseitig festgelegten Batchgröße stellt der Aufruf die Verarbeitung in die Warteschlange, anstatt die Bilder direkt hochzuladen: photos wird leer zurückgegeben und request.requestId ist gesetzt. Fragen Sie GET /locations/photos/requests/{requestId} mit dieser ID regelmäßig ab, um den Abschluss zu verfolgen. Der Schwellenwert wird serverseitig konfiguriert. Gehen Sie daher davon aus, dass "große Batches in die Warteschlange gestellt werden können", statt eine feste Zahl anzunehmen, und verzweigen Sie abhängig davon, ob request.requestId vorhanden ist.
Verzweigen Sie nicht anhand von request.status. In der Antwort bei Aufnahme in die Warteschlange ist der Wert die literale Zeichenfolge PROCCESSING, deren Schreibweise von PROCESSING abweicht, das der Abfrage-Endpunkt für denselben Auftrag meldet. Das Vorhandensein von request.requestId ist das zuverlässige Signal.
Wenn durch die Übergabe von starred: true die zulässige Anzahl von 4 mit einem Stern markierten Fotos überschritten wird, schlägt der gesamte Aufruf mit SY15012 fehl. Die Prüfung zählt die bereits mit einem Stern markierten Fotos des Standorts und die mit einem Stern markierten Elemente in dieser Anfrage zusammen.
Ein Standort hat genau ein Logo und ein Titelbild; ein erneuter Upload in einer dieser Kategorien ersetzt das vorhandene Bild.
Setzen Sie type explizit, wenn ein Bild als Logo oder Titelbild dienen soll. Ohne diese Angabe wird das Bild als zusätzliches Foto gespeichert.

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" } ] } }'