Carica un logo, una copertina e delle foto

Aggiungi logo, copertina e foto della galleria a una sede via URL, elenca gli allegati, segna con una stella la foto principale e rimuovi quelli obsoleti.

Le foto vengono associate a una sede tramite URL pubblico: tu ospiti l'immagine, l'API la recupera e la memorizza e le piattaforme di pubblicazione la recuperano da lì. Una sede conserva un logo, una copertina e un numero qualsiasi di foto aggiuntive, di cui fino a quattro possono essere contrassegnate con una stella per ottenere un posizionamento prioritario.

1. Carica tramite URL

POST /locations/photos accetta input.locationId e un array input.photos. L'URL di ciascun elemento va inserito in un campo chiamato photo, non url. Imposta esplicitamente type su LOGO, COVER o ADDITIONAL; un elemento senza type viene memorizzato come foto aggiuntiva.

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

Conserva il valore id di ciascuna foto: è quello accettato dagli endpoint per contrassegnare con una stella e rimuovere le foto. Caricare nuovamente un elemento LOGO o COVER sostituisce quello esistente. Un piccolo gruppo di foto viene memorizzato direttamente, come in questo esempio. Un gruppo numeroso viene invece messo in coda: photos viene restituito vuoto e request.requestId viene impostato. Scegli il ramo di esecuzione in base alla presenza di requestId, quindi interroga periodicamente GET /locations/photos/requests/{requestId}.

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

2. Elenca i contenuti associati

GET /locations/{locationId}/photos restituisce tutti i file multimediali della sede sotto forma di un semplice array. Usalo per verificare se manca un logo o una copertina prima di caricare le immagini e per raccogliere gli id necessari per i due passaggi successivi. Il percorso accetta l'id in base64 oppure il numero non codificato.

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 è Logo, Cover o Additional. Per una sede senza contenuti multimediali viene restituito un array vuoto, non un errore.

3. Contrassegna con una stella le foto aggiuntive

POST /locations/photos/star contrassegna le foto aggiuntive affinché abbiano un posizionamento prioritario sulle piattaforme di pubblicazione che supportano le immagini in evidenza. Solo le foto ADDITIONAL possono essere contrassegnate con una stella, fino a un massimo di 4 per sede; una quinta fa fallire l'intera chiamata con SY15012. Puoi anche passare starred: true su un elemento al momento del caricamento.

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

La chiave della risposta è starUnstarLocationPhotos e contiene un singolo error, non un array errors. Il flag starred nel corpo controlla l'azione: invia false per rimuovere la stella. I metodi dell'SDK accettano lo stesso valore booleano.

4. Rimuovi una foto

POST /locations/photos/remove scollega le foto aggiuntive tramite id. removedCount indica quante ne sono state scollegate, quindi 0 con errors: null significa che nessuno di quegli id era associato a questa sede.

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

Qui puoi rimuovere solo le foto ADDITIONAL. Per cambiare il logo o la copertina, carica una nuova immagine con quel valore di type e sostituirà quella precedente. La rimozione scollega il file dalla sede; non lo elimina necessariamente dalla tua libreria multimediale.

5. Come le piattaforme di pubblicazione usano ciascuno slot

Passaggi successivi

• Aggiorna una sede: orari, chiusure e categorie di Google nello stesso record.
• Controlla lo stato delle schede e i link attivi: verifica quando le piattaforme di pubblicazione hanno pubblicato le nuove immagini.
• Carica foto, Recupera foto, Contrassegna le foto con una stella, Rimuovi foto e Stato del caricamento in blocco: le pagine di riferimento.
• Riferimenti degli SDK: Foto in Python e Foto in Node.