Listings APIListings API
Accedi
POST/api/v4/locations/photos/star

Contrassegnare le foto di una sede come preferite

Contrassegna una o più foto aggiuntive di una sede come preferite per un posizionamento prioritario sulle piattaforme di pubblicazione supportate.

Richiede una chiave API. Consulta Autenticazione per il formato dell’header e la rotazione delle chiavi.

Parametri

Corpo

NomeTipoObbligatorioDescrizione
input.locationIdstringobbligatorioThe location's Base64-encoded Relay ID the photos belong to.
input.photoIdsarray of stringsobbligatorioMedia file IDs to star (as returned by the get-photos or upload endpoints).
input.starredbooleanobbligatorio`true` to star the given photos, `false` to unstar them. This flag, not the path, decides what happens: `/star` and `/unstar` behave the same way.

Richiesta di esempio

Corpo pronto da incollare. Sostituisci gli ID e i valori segnaposto con i tuoi.

Request body
{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": [      "TWVkaWFGaWxlOjU4Nzg5MzI="    ],    "starred": true  }}

Risposte

200Photos starred. Returns each affected photo with `starred` set to true; `error` is null on success.
Response
{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        {          "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": true        }      ],      "error": null    }  }}
401Unauthenticated, missing or invalid API key.

Contrassegna le foto specificate di una sede come preferite. Le foto preferite ricevono un posizionamento prioritario nelle directory delle piattaforme di pubblicazione che supportano le immagini in evidenza, consentendoti così di portare i tuoi scatti migliori in cima a una scheda.

Caso d'uso: mettere in evidenza un'immagine principale stagionale. Dopo aver caricato una nuova foto della facciata del negozio, contrassegnala come preferita affinché compaia per prima nella galleria su Google e sugli altri siti supportati. Passa l'ID del contenuto multimediale restituito nella risposta al caricamento in photoIds.

Caso d'uso: curare una raccolta coerente con il brand. Quando gestisci molte sedi, contrassegna come preferita la stessa categoria di foto aggiuntiva (ad esempio, la foto degli esterni) in ogni sede per mantenere coerente la galleria visibile al pubblico.

Aspetti da tenere presenti.

  • La risposta usa la chiave starUnstarLocationPhotos, che non prende il nome dalla route, e la chiave è la stessa sia per /locations/photos/star sia per /locations/photos/unstar.
  • Il suo payload contiene un singolo oggetto error, non un array errors, e non contiene clientMutationId. Non è presente neppure un campo caption nelle foto.
  • Solo le foto della categoria ADDITIONAL possono essere contrassegnate come preferite. Le immagini LOGO e COVER sono già principali e non possono essere contrassegnate come preferite.
  • Una sede può avere al massimo 4 foto preferite; se superi questo limite, l'operazione fallisce con SY15012. Il controllo conta le foto già contrassegnate come preferite più quelle incluse in questa richiesta e si applica solo quando starred è true.
  • Per annullare l'azione, usa POST /api/v4/locations/photos/unstar con starred: false. È il valore di starred a determinare cosa succede, non il percorso: l'invio tramite POST di starred: true a /unstar contrassegna le foto come preferite.
Request
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    }  }'
Run in playground