ロゴ、カバー画像、写真をアップロードする

URLを指定してロゴ、カバー画像、ギャラリー写真を拠点に添付し、添付済みの画像を一覧表示し、メイン画像にスターを付け、古くなった画像を削除します。

写真は公開URLを使って拠点に添付します。画像は自社でホストし、APIがその画像を取得して保存します。掲載先はそこから画像を取得します。拠点にはロゴ1枚、カバー画像1枚、任意の枚数の追加写真を保持でき、追加写真のうち最大4枚にスターを付けて優先的に表示できます。

1. URLを指定してアップロードする

POST /locations/photosはinput.locationIdとinput.photos配列を受け取ります。各項目のURLは、urlではなくphotoという名前のフィールドに指定します。typeにはLOGO、COVER、ADDITIONALのいずれかを明示的に設定し、typeのない項目は追加写真として保存されます。

Upload

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" }    ]  }}'

JSON

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

各写真のidを保持してください。スターの付与と削除のエンドポイントはこの値を受け取ります。LOGOまたはCOVERを再アップロードすると、既存の画像が置き換わります。小規模なバッチは、このようにその場で保存されます。大規模なバッチは代わりにキューに入り、photosが空で返され、request.requestIdが設定されます。requestIdの有無で処理を分岐し、その後GET /locations/photos/requests/{requestId}をポーリングします。

Poll a queued batch

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

ジョブの`status`	意味
`PROCESSING`	まだ処理中です。数秒後に再度ポーリングしてください。
`SUCCESS`	処理が完了しました。個々の写真の処理は失敗している可能性があるため、`photos[].status`と`photos[].errorMessage`を確認してください。
`ERROR`	ジョブ自体が失敗しました。`photos[].errorMessage`を確認してください。

2. 添付済みの画像を一覧表示する

GET /locations/{locationId}/photosは、拠点にあるすべてのメディアファイルを単純な配列として返します。アップロード前にロゴやカバー画像がないかを確認し、続く2つの手順で使用するidを収集するために使います。パスにはbase64形式のidまたは数値のidを指定できます。

List photos

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "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、Additionalのいずれかです。メディアのない拠点では、エラーではなく空の配列が返されます。

3. 追加写真にスターを付ける

POST /locations/photos/starは、注目画像に対応している掲載先で優先的に表示されるよう、追加写真に印を付けます。スターを付けられるのはADDITIONALの写真のみで、拠点ごとに最大4枚までです。5枚目にスターを付けようとすると、呼び出し全体がSY15012で失敗します。アップロード時に項目にstarred: trueを指定することもできます。

Star

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

JSON

{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

レスポンスのキーはstarUnstarLocationPhotosで、errors配列ではなく単一のerrorが含まれます。リクエストボディのstarredフラグで操作を制御し、スターを外すにはfalseを送信します。SDKメソッドも同じ真偽値を受け取ります。

4. 写真を削除する

POST /locations/photos/removeは、idを指定して追加写真の添付を解除します。removedCountは添付が解除された枚数を示すため、0でerrors: nullの場合、それらのidの写真はどれもこの拠点に添付されていなかったことを意味します。

Remove

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="]  }}'

JSON

{  "data": {    "removeLocationPhotos": {      "removedCount": 1,      "errors": null    }  }}

ここで削除できるのはADDITIONALの写真のみです。ロゴやカバー画像を変更するには、該当するtypeを指定して新しい画像をアップロードしてください。古い画像が置き換わります。削除すると拠点からファイルの添付が解除されますが、メディアライブラリから完全に削除されるとは限りません。

5. 掲載先での各スロットの扱い

スロット	枚数	掲載先での扱い
`LOGO`	拠点ごとに1枚	プロフィール画像またはブランド画像として表示されます。再アップロードすると置き換わります。API経由ではスターの付与や削除はできません。
`COVER`	拠点ごとに1枚	ヘッダー画像のある掲載情報で、ヘッダー画像として表示されます。ロゴと同様に、置き換えのみが可能です。
`ADDITIONAL`	任意の枚数	ギャラリーです。`type`が指定されていない場合のデフォルトです。削除できます。
スター付きの`ADDITIONAL`	最大4枚	注目画像に対応している掲載先では優先的に表示されるため、外観や内観の最も良い写真を優先して選んでください。

次の手順

拠点を更新する: 同じレコードで営業時間、休業情報、Google カテゴリを更新します。
掲載情報のステータスと公開リンクを確認する: 掲載先が新しい画像を公開したタイミングを確認します。
写真をアップロードする、写真を取得する、写真にスターを付ける、写真を削除する、一括アップロードのステータス: これらのリファレンスページを参照してください。
SDK リファレンス: Python の写真機能とNode の写真機能。