Listings APIListings API
Iniciar sesión
POST/api/v4/locations/photos/star

Marcar fotos de una ubicación como favoritas

Marca una o más fotos adicionales de una ubicación como favoritas para darles prioridad de aparición en las plataformas de publicación compatibles.

Requiere una clave de API. Consulta Autenticación para conocer el formato del encabezado y la rotación de claves.

Parámetros

Cuerpo

NombreTipoObligatorioDescripción
input.locationIdstringobligatorioThe location's Base64-encoded Relay ID the photos belong to.
input.photoIdsarray of stringsobligatorioMedia file IDs to star (as returned by the get-photos or upload endpoints).
input.starredbooleanobligatorio`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.

Solicitud de ejemplo

Cuerpo listo para pegar. Sustituye los ID y valores de ejemplo por los tuyos.

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

Respuestas

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.

Marca las fotos especificadas de una ubicación como favoritas. Las fotos favoritas tienen prioridad de aparición en los directorios de las plataformas de publicación que admiten imágenes destacadas, por lo que esta es la forma de situar tus mejores fotos en la parte superior de una ficha.

Caso de uso: destacar una imagen principal de temporada. Después de subir una nueva foto de la fachada, márcala como favorita para que aparezca al principio de la galería en Google y otros sitios compatibles. Pasa el ID del archivo multimedia de la respuesta de subida en photoIds.

Caso de uso: seleccionar un conjunto coherente de imágenes de marca. Cuando gestiones muchas ubicaciones, marca como favorita la misma categoría de foto adicional (por ejemplo, la foto del exterior) en cada ubicación para mantener la coherencia de la galería que se muestra al público.

Aspectos que debes tener en cuenta.

  • La respuesta usa la clave starUnstarLocationPhotos, que no toma su nombre de la ruta, y la clave es la misma tanto en /locations/photos/star como en /locations/photos/unstar.
  • Su contenido incluye un único objeto error, no un array errors, y no hay clientMutationId. Tampoco hay un campo caption en una foto.
  • Solo se pueden marcar como favoritas las fotos de la categoría ADDITIONAL. Las imágenes LOGO y COVER ya son principales y no se pueden marcar como favoritas.
  • Una ubicación puede tener como máximo 4 fotos favoritas; si se supera ese límite, la operación falla con SY15012. La comprobación cuenta las fotos ya marcadas como favoritas más las de esta solicitud, y solo se aplica cuando starred es true.
  • Para revertir la acción, usa POST /api/v4/locations/photos/unstar con starred: false. El valor de starred determina lo que ocurre, no la ruta: enviar starred: true mediante POST a /unstar marca las fotos como favoritas.
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