Logo, Titelbild und Fotos hochladen

Fügen Sie Logo, Titelbild und Galeriefotos per URL zum Standort hinzu. Listen Sie Bilder auf, markieren das Hauptbild mit Stern und entfernen veraltete.

Fotos werden einem Standort über eine öffentliche URL zugeordnet: Sie hosten das Bild, die API ruft es ab und speichert es, und die Plattformen rufen es von dort ab. Ein Standort enthält ein Logo, ein Titelbild und beliebig viele zusätzliche Fotos, von denen bis zu vier für eine bevorzugte Platzierung mit einem Stern markiert werden können.

1. Per URL hochladen

POST /locations/photos nimmt input.locationId und ein input.photos-Array entgegen. Die URL jedes Elements gehört in ein Feld namens photo, nicht url. Setzen Sie type ausdrücklich auf LOGO, COVER oder ADDITIONAL; ein Element ohne type wird 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/cover.jpg", "type": "COVER" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'

{  "data": {    "addLocationPhotos": {      "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 }      ],      "errors": null    }  }}

Bewahren Sie die id jedes Fotos auf: Die Endpunkte zum Markieren mit einem Stern und zum Entfernen nehmen sie entgegen. Das erneute Hochladen eines LOGO oder COVER ersetzt das vorhandene Bild. Ein kleiner Stapel wird wie hier gezeigt direkt gespeichert. Ein großer Stapel wird stattdessen in eine Warteschlange gestellt: photos wird leer zurückgegeben und request.requestId wird gesetzt. Verzweigen Sie danach, ob requestId vorhanden ist, und fragen Sie anschließend GET /locations/photos/requests/{requestId} regelmäßig ab.

curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"

2. Zugeordnete Dateien auflisten

GET /locations/{locationId}/photos gibt alle Mediendateien des Standorts als einfaches Array zurück. Prüfen Sie damit vor dem Hochladen, ob ein Logo oder Titelbild fehlt, und sammeln Sie die IDs für die nächsten beiden Schritte. Der Pfad akzeptiert die base64-codierte ID oder die unkodierte Zahl.

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "starred": false, "viewsCount": 0 },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "starred": true, "viewsCount": 143 }    ]  }}

categoryName ist Logo, Cover oder Additional. Bei einem Standort ohne Medien wird ein leeres Array zurückgegeben, kein Fehler.

3. Zusätzliche Fotos 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; ein fünftes lässt den gesamten Aufruf mit SY15012 fehlschlagen. Sie können auch beim Hochladen starred: true für ein Element übergeben.

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

{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

Der Antwortschlüssel lautet starUnstarLocationPhotos und enthält ein einzelnes error, kein errors-Array. Das Flag starred im Body steuert die Aktion: Senden Sie false, um die Sternmarkierung zu entfernen. Die SDK-Methoden nehmen denselben booleschen Wert entgegen.

4. Ein Foto entfernen

POST /locations/photos/remove hebt die Zuordnung zusätzlicher Fotos anhand ihrer ID auf. removedCount gibt an, wie viele Zuordnungen aufgehoben wurden; 0 mit errors: null bedeutet daher, dass keine dieser IDs diesem Standort zugeordnet war.

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

{  "data": {    "removeLocationPhotos": {      "removedCount": 1,      "errors": null    }  }}

Hier können nur Fotos vom Typ ADDITIONAL entfernt werden. Um das Logo oder Titelbild zu ändern, laden Sie ein neues Bild mit dem entsprechenden type hoch; es ersetzt das alte Bild. Durch das Entfernen wird die Zuordnung der Datei zum Standort aufgehoben; die Datei wird dadurch nicht unbedingt aus Ihrer Medienbibliothek gelöscht.

5. Wie Plattformen die einzelnen Bildplätze verwenden

Nächste Schritte

• Einen Standort aktualisieren: Öffnungszeiten, Schließungen und Google-Kategorien im selben Datensatz.
• Eintragsstatus und Live-Links prüfen: Sehen Sie, wann die Plattformen die neuen Bilder veröffentlicht haben.
• Fotos hochladen, Fotos abrufen, Fotos mit einem Stern markieren, Fotos entfernen und Status des Massenuploads: die Referenzseiten.
• SDK-Referenzen: Fotos mit Python und Fotos mit Node.