Listings APIListings API
登录
POST/api/v4/locations/photos/star

为地点照片加星标

将地点的一张或多张附加照片标记为收藏，以便在支持此功能的发布平台上优先展示。

需要 API 密钥。请求头格式和密钥轮换请参阅身份验证。

参数

请求体

名称类型必填描述
input.locationIdstring必填The location's Base64-encoded Relay ID the photos belong to.
input.photoIdsarray of strings必填Media file IDs to star (as returned by the get-photos or upload endpoints).
input.starredboolean必填`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.

请求示例

可直接粘贴的请求体。请将占位 ID 和值替换为您自己的。

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

响应

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.

为地点的指定照片加星标。在支持精选图片的发布平台目录中，加星标的照片会优先展示，因此您可以通过此方式将最佳照片置于商家信息顶部。

使用场景：突出展示季节性主图。上传新的店面照片后，为其加星标，使其在 Google 和其他支持此功能的网站上位于图库首位。在 photoIds 中传入上传响应中的媒体 ID。

使用场景：精选一致的品牌图片集。管理多个地点时，为每个地点的同一类附加照片（例如外观照片）加星标，以保持面向公众的图库一致。

注意事项。

  • 响应以 starUnstarLocationPhotos 为键，而不是以路由命名，并且 /locations/photos/star 和 /locations/photos/unstar 使用相同的键。
  • 其载荷包含单个 error 对象，而不是 errors 数组，并且没有 clientMutationId。照片也没有 caption 字段。
  • 只有 ADDITIONAL 类别的照片可以加星标。LOGO 和 COVER 图片已经是主图，无法加星标。
  • 一个地点最多可以有 4 张加星标的照片；超出此限制会导致操作失败，并返回 SY15012。此检查会合计已加星标的照片和本次请求中的照片数量，并且仅在 starred 为 true 时适用。
  • 要撤销此操作，请使用 starred: false 执行 POST /api/v4/locations/photos/unstar。决定操作结果的是 starred 的值，而不是路径：向 /unstar 提交 starred: true 会为照片加星标。
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