Listings APIListings API
Get API keySign in
POST/api/v4/locations/photos/star

Star location photos

Marks one or more of a location's additional photos as favourites for priority placement on supported publishers.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Body

NameTypeRequiredDescription
input.locationIdstringrequiredThe location's Base64-encoded Relay ID the photos belong to.
input.photoIdsarray of stringsrequiredMedia file IDs to star (as returned by the get-photos or upload endpoints).
input.starredbooleanrequired`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.

Sample request

Ready-to-paste body. Replace placeholder IDs and values with yours.

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

Responses

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.

Stars the specified photos for a location. Starred photos are given priority placement on publisher directories that support featured imagery, so this is how you promote your best shots to the top of a listing.

Use case: feature a seasonal hero image. After uploading a new storefront photo, star it so it leads the gallery on Google and other supported sites. Pass the media ID from the upload response in photoIds.

Use case: curate a consistent brand set. When managing many locations, star the same category of additional photo (for example, the exterior shot) at each location to keep the public-facing gallery consistent.

Gotchas.

  • The response is keyed starUnstarLocationPhotos, not after the route, and the key is the same on both /locations/photos/star and /locations/photos/unstar.
  • Its payload carries a singular error object, not an errors array, and there is no clientMutationId. There is no caption field on a photo either.
  • Only ADDITIONAL category photos can be starred. LOGO and COVER images are already primary and cannot be starred.
  • A location can have at most 4 starred photos; going past it fails with SY15012. The check counts the photos already starred plus the ones in this request, and it only applies when starred is true.
  • To reverse the action, POST /api/v4/locations/photos/unstar with starred: false. The starred value decides what happens, not the path: posting starred: true to /unstar stars the photos.
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