拠点

拠点の全エンドポイントを、cURL、Python、Nodeのサンプルとともに、利用順に紹介します。一覧取得、検索、idと店舗コードによる取得、作成、更新、アーカイブ、写真管理を扱います。

掲載情報、レビュー、投稿、分析データは、すべて拠点IDに紐づいています。拠点リソースには13のエンドポイントがあり、拠点を検索・取得する4つの読み取りエンドポイント、拠点を作成・変更・アーカイブする4つの書き込みエンドポイント、写真を管理する5つのエンドポイントで構成されています。読み取りにはRead（読み取り）キーを使用できます。すべてのPOSTにはWrite（書き込み）キーが必要で、書き込みにReadキーを使用すると、HTTP 400とSY90016が返されます。

このガイドに登場するidはすべてbase64形式のRelay idです。たとえば、TG9jYXRpb246MTgwMDI4OQ==はLocation:1800289にデコードされます。両方のSDKは数値のdatabaseIdも受け付け、自動的にエンコードします。

エンドポイント一覧

メソッド	パス	機能	リファレンス
`GET`	`/locations`	すべての拠点を新しい順にページ単位で取得します。	すべての拠点を一覧取得
`GET`	`/locations/search`	名前、住所、店舗idを対象に、キーワードで拠点を検索します。	拠点を検索
`GET`	`/locations-by-ids`	複数のbase64形式のidに対応する完全なレコードを一括取得します。	IDで拠点を取得
`GET`	`/locations-by-store-codes`	独自の店舗コードに対応する完全なレコードを取得します。	店舗コードで拠点を取得
`POST`	`/locations`	拠点を作成し、送信待ちキューに追加します。	拠点を作成
`POST`	`/locations/update`	1つの拠点の書き込み可能な任意のフィールドを変更します。	拠点を更新
`POST`	`/locations/archive`	請求サイクルの終了時に拠点がアーカイブされるように予約します。	拠点をアーカイブ
`POST`	`/locations/cancel_archive`	アーカイブを予約した拠点を有効な状態に戻します。	アーカイブの予約をキャンセル
`POST`	`/locations/photos`	URLを指定してロゴ、カバー写真、またはギャラリー写真を添付します。	写真をアップロード
`GET`	`/locations/photos/requests/{requestId}`	キューに追加された一括アップロードの状態をポーリングします。	一括アップロードの状態を確認
`GET`	`/locations/{locationId}/photos`	拠点のすべてのメディアファイルを一覧取得します。	写真を取得
`POST`	`/locations/photos/star`	追加写真にスターを付けるか、スターを外します。	写真にスターを付ける
`POST`	`/locations/photos/remove`	追加写真の関連付けを解除します。	写真を削除

すべての拠点の一覧を取得する

GET /locationsは、アカウント内のすべての拠点を新しい順にページ単位で取得します。カーソル形式のコネクションで、edges[].nodeに各レコードが格納され、pageInfo.endCursorの値を次のページのafterパラメーターに渡します。アカウント全体を独自のシステムに同期する際に使用します。

パラメーター

名前	指定先	必須	備考
`first`	query	いいえ	順方向に取得する際のページサイズです。デフォルトは50です。`after`と組み合わせて使用します。
`after`	query	いいえ	前のページの`pageInfo.endCursor`です。
`last`	query	いいえ	逆方向に取得する際のページサイズです。`before`と組み合わせて使用します。
`before`	query	いいえ	戻る前に表示しているページの最初のエッジの`cursor`です。`pageInfo`には`startCursor`がありません。
`filter`	query	いいえ	承認状態などを条件として、サーバー側で対象を絞り込むためのJSONエンコードされたオブジェクトです。どちらのSDKの一覧取得メソッドもこのパラメーターを受け付けないため、絞り込んだデータを取得するにはRESTを呼び出します。

List

curl "https://listingsapi.com/api/v4/locations?first=50" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "storeId": null,            "approved": "APPROVED",            "archived": false,            "archivalScheduledAt": null,            "city": "Austin",            "stateIso": "TX",            "countryIso": "US",            "subCategoryId": 1432,            "planName": "Launch",            "placeActionLinks": [],            "discoveredPlaceActionLinks": []          }        }      ],      "pageInfo": {        "hasNextPage": false,        "hasPreviousPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "total": 1      }    }  }}

pageInfo.hasNextPageを読み取り、falseになったら停止します。ページ単位の件数はpageInfo.totalです。ノードのidは、他のすべてのエンドポイントが受け付ける識別子です。

拠点を検索する

GET /locations/searchは、拠点名、番地・通り名、市区町村、店舗idを対象にキーワードを照合します。一覧取得と同じedges[].nodeおよびpageInfo.endCursorの構造を持つ、カーソル形式のコネクションです。入力に応じて候補を表示する選択UIや、店舗を作成する前にその店舗が存在するかを確認する用途に使用します。

パラメーター

名前	指定先	必須	備考
`query`	query	いいえ	検索キーワードです。省略すると、絞り込みを行わずにすべての拠点をページ単位で取得します。
`first`	query	いいえ	ページサイズです。デフォルトは50です。
`after`	query	いいえ	前のページの`pageInfo.endCursor`です。
`filter`	query	いいえ	一覧取得エンドポイントと同じ、JSONエンコードされたフィルターオブジェクトです。

両方のSDKはfieldsのリストも受け付け、照合対象を特定のフィールド（たとえばnameのみ）に限定できます。

curl "https://listingsapi.com/api/v4/locations/search?query=Jenny&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "storeId": null,            "street": "600 Congress Ave, Suite 200",            "city": "Austin",            "approved": "APPROVED",            "archived": false          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "hasPreviousPage": false,        "total": 1      }    }  }}

edges配列が空の場合、一致する結果がなかったことを意味します。ノードには完全な住所、カテゴリ、approvedの状態が含まれるため、結果行を表示するために再度取得する必要はありません。

IDで拠点を取得する

GET /locations-by-idsは、複数のbase64 IDに対応する完全なレコードを1回の呼び出しで返すため、拠点ごとに呼び出す場合よりリクエスト数を減らせます。有効な拠点とアーカイブ済みの拠点の両方を取得できます。コネクションではなく、通常の配列を返します。Webhookのペイロードや独自のストアにあるIDから完全なレコードを取得するために使用します。

パラメーター

名前	指定先	必須	備考
`ids`	query	はい	JSON形式でエンコードされたbase64 IDの配列です。値全体をURLエンコードしてください。`curl -G --data-urlencode`を使うと、この処理が自動的に行われます。

By ids

curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "getLocationsByIds": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": null,        "name": "Jenny Home",        "archived": false,        "archivedAt": null,        "city": "Austin",        "stateIso": "TX",        "countryIso": "US",        "subCategoryId": 1432,        "businessHours": [],        "locationPhotos": [],        "placeActionLinks": [],        "discoveredPlaceActionLinks": []      }    ]  }}

アカウント内に存在しないIDは、エラーにならずに除外されます。返された件数と送信した件数を比較すると、無効になったIDを検出できます。

店舗コードで拠点を取得する

GET /locations-by-store-codesは逆引きを行い、独自の店舗コードから完全なレコードを取得します。通常の配列を返します。POSやフランチャイズの店舗台帳で店舗コードを拠点のキーとして使用しており、Listings APIのIDを保存していない場合に使用します。

パラメーター

名前	指定先	必須	備考
`storeCodes`	query	はい	JSON形式でエンコードされた店舗コード文字列の配列です。値全体をURLエンコードしてください。

By store codes

curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME01","ACME02"]' \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "getLocationsByStoreCodes": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": "ACME01",        "name": "Jenny Home",        "archived": false,        "city": "Austin",        "countryIso": "US",        "planName": "Launch"      }    ]  }}

各オブジェクトのstoreIdを店舗台帳と照合してください。一致するものがないコードは含まれません。拠点に店舗コードがあるのは、作成時または更新時にstoreIdが設定された場合のみです。

拠点を作成する

POST /locationsは拠点を作成し、プランに含まれるすべての掲載先への送信キューに追加します。ただし、enabledSiteIdsフィールドを渡した場合は、そのフィールドで指定した掲載先のみが対象になります。すべてのフィールドはinputの下に配置します。10個のフィールドが必須で、残りは任意です。省略したフィールドは掲載先で空欄として表示されます。

パラメーター

名前	指定先	必須	備考
`input.name`	body	はい	ビジネス名です。2～150文字で指定します。
`input.description`	body	はい	最低200文字です（`SY10005`）。掲載先はこれを掲載情報の紹介文として使用します。
`input.countryIso`	body	はい	サポートされている国コードです（`SY10036`）。国から取得します。
`input.city`	body	はい	国の`hasCity`が`true`の場合は必須です（`SY10126`）。`false`の場合、送信した市区町村は除外されます。
`input.subCategoryId`	body	はい	サブカテゴリから取得した数値の`databaseId`です。
`input.street`	body	はい	5～100文字です（`SY10011`）。
`input.stateIso`	body	はい	国の`stateRequired`が`true`の場合は必須で、その国の`states`のいずれかである必要があります（`SY10010`）。`stateRequired`が`false`の場合は省略してください。
`input.phone`	body	はい	国に応じて検証されます（`SY10015`）。
`input.postalCode`	body	いいえ	任意ですが、国の`hasPostalCode`が`true`の場合は必ず送信してください。送信する値は、その国の形式に一致する必要があります（`SY10014`）。
`input.bizUrl`	body	はい	ウェブサイトとして公開されます。一部の掲載先では、ウェブサイトがない掲載情報は受け付けられません。
`input.storeId`	body	いいえ	アカウント全体で一意の、独自の店舗コードです。
`input.businessHours`	body	いいえ	`{ day, type, slots }`の7件のエントリです。`type`は`OPEN`または`CLOSED`で、休業日は`slots`を空にします。
`input.placeActionLinks`	body	いいえ	Googleのアクションリンクです。`placeActionType`、`uri`、および任意の`isPreferred`を指定します。作成時に`action`は不要です。プレイスアクションリンクを参照してください。
`input.enabledSiteIds`	body	いいえ	プランに含まれるサイトの一部に公開します。IDはプランのサイトから取得します。
`input.clientMutationId`	body	いいえ	関連付けのために、変更されずに返されます。重複した書き込みは防止しません。

このほか、リファレンスページに記載されている任意のフィールドとして、Google GCIDカテゴリ、ソーシャルURL、座標、オーナーの連絡先、支払い方法、サービス提供地域などがあります。

Create

curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",    "storeId": "ACME01",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY", "type": "CLOSED", "slots": [] }    ],    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true }    ]  }}'

JSON

{  "data": {    "createLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME01",        "name": "Acme Kitchen",        "city": "New York",        "countryIso": "US",        "status": "PENDING",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

両方のIDを保持してください。base64のidは以降のすべての書き込みに必要で、databaseIdはダッシュボードやWebhookに表示される番号です。statusはPENDINGで始まり、追加のAPI呼び出しなしで次の状態に進みます。プレイスアクションリンクのnameとsubmissionStatusは、Googleと同期されるまでnullのままです。Pythonのlocations.add()は必須フィールドをローカルで検証し、ネットワーク呼び出しの前にValidationErrorを送出します。一方、locations.create(input)はcamelCaseのdictをそのまま受け取ります。

拠点を更新する

POST /locations/updateは部分更新です。必須フィールドはinput.idのみで、送信したフィールドだけが変更されます。同じ呼び出しで、電話番号の修正も週間スケジュールの書き換えもできます。Pythonのlocations.update()とNodeのupdateLocation()は、どちらも1つのcamelCaseオブジェクトを受け取ります。

パラメーター

名前	指定先	必須	備考
`input.id`	body	はい	拠点のbase64 idです。フィールドは`id`であり、`locationId`ではありません。
`input.phone`、`input.bizUrl`、`input.name`、住所フィールド	body	いいえ	作成の呼び出しで使用できる、書き込み可能な任意のフィールドです。
`input.businessHours`	body	いいえ	7日分すべてを送信してください。週の一部だけでは拒否されます。祝日用に上書きする場合は、`specialDate`を持つ`day: "SPECIAL"`エントリを週間スケジュールと一緒に追加し、週間スケジュールの代わりには絶対に使用しないでください。
`input.moreHours`	body	いいえ	配達などの補助スケジュールで、それぞれが`{ hoursTypeId, moreHour }`です。ここでは`specialDate`は使用しません。
`input.temporarilyClosed`	body	いいえ	`true`は、拠点の休業中に営業時間の公開を停止します。
`input.primaryGbpSiteCategoryId`, `input.additionalGbpSiteCategoryIds`	body	いいえ	`gcid:restaurant`など、GCIDで指定するGoogleのカテゴリです。これらと一緒に`countryIso`を送信してください。
`input.placeActionLinks`	body	いいえ	追加または更新（upsert）します。各項目の`action`には`add`（デフォルト）または`delete`を指定します。指定しなかったリンクは変更されません。
`input.submissionDisabledSiteIds`	body	いいえ	送信対象から除外するサイトのidです。

このほか、リファレンスページに記載されている任意フィールドも使用できます。

Update

curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "businessHours": [      { "day": "MONDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY", "type": "CLOSED", "slots": [] }    ]  }}'

JSON

{  "data": {    "updateLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "status": "APPROVED",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

レスポンスには更新後の拠点が返されるため、新しい値が適用されたことを確認できます。更新のたびに、その拠点の現在のplaceActionLinksの完全なセットが返されます。リンクのURLを変更するには、同じリクエストで古いリンクのdeleteと新しいリンクのaddを送信してください。

拠点をアーカイブする

POST /locations/archiveは、1つ以上の拠点のアーカイブを予約します。アーカイブは即時には行われず、各拠点はARCHIVE_SCHEDULEDに移行し、現在の請求サイクルが終了するまで公開と課金が継続され、次の請求書が生成されるときにアーカイブされます。閉鎖した支店の利用を一括で終了する際に使用してください。

パラメーター

名前	指定先	必須	備考
`input.locationIds`	body	はい	アーカイブする拠点のbase64 idの配列です。
`input.clientMutationId`	body	いいえ	変更されずに返されます。重複した書き込みは防止しません。

`result[].status`	意味
`ARCHIVE_SCHEDULED`	キューに登録されています。請求サイクルが終了するまで、拠点の公開と課金が継続されます。
`ARCHIVED`	以前の呼び出しまたは請求サイクルですでにアーカイブされています。

アーカイブの予約を取り消す

POST /locations/cancel_archiveは、ARCHIVE_SCHEDULEDの拠点をACTIVEに戻し、課金は継続されます。この呼び出しは請求サイクルが終了していない間のみ有効で、拠点が完全にアーカイブされると、その拠点に対して404を返します。

パラメーター

名前	指定先	必須	備考
`input.locationIds`	body	はい	現在`ARCHIVE_SCHEDULED`の拠点のbase64 idの配列です。
`input.clientMutationId`	body	いいえ	変更されずに返されます。

Cancel archive

curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'

JSON

{  "data": {    "cancelLocationsArchive": {      "clientMutationId": null,      "bulkEditTaskId": null,      "errors": null,      "success": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null }      ]    }  }}

各result[]エントリで、拠点がACTIVEに戻ったことを確認できます。どちらのSDKも、追加の位置引数として選択タイプとchangedBy識別子の2つを必要とし、これらをlocationIdsと一緒に送信しますが、RESTのbodyに必要なのはidのみです。

拠点に写真をアップロードする

POST /locations/photosは公開URLを使って画像を添付します。画像は利用者側でホストし、APIが取得して保存します。拠点には、LOGOを1枚、COVERを1枚、ADDITIONALの写真を任意の枚数保存できます。ロゴまたはカバーを再アップロードすると、既存のものが置き換えられます。

パラメーター

名前	指定先	必須	備考
`input.locationId`	body	はい	拠点のbase64 idです。
`input.photos`	body	はい	画像オブジェクトの配列です。空にはできません。
`input.photos[].photo`	body	はい	JPEGまたはPNG画像の公開URLです。フィールドは`photo`であり、`url`ではありません。
`input.photos[].type`	body	いいえ	`LOGO`、`COVER`、または`ADDITIONAL`です。デフォルトは追加写真です。
`input.photos[].starred`	body	いいえ	写真の取り込み時にスターを付けます。対象は追加写真のみで、1拠点あたり最大4枚です。
`input.photos[].source`	body	いいえ	画像の入手元を記録する自由記述のラベルです。

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/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'

JSON

{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "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,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg" }      ],      "errors": null    }  }}

各写真のidを保存してください。スター付与と削除のエンドポイントで使用します。これは小規模なバッチ向けのインライン形式です。大規模なバッチは代わりにキューに登録され、photosは空で返され、request.requestIdが設定されるので、そのidを使って次のエンドポイントをポーリングします。しきい値はサーバー側の設定で決まるため、request.requestIdの有無で処理を分岐してください。

写真の一括アップロードのステータスを確認する

GET /locations/photos/requests/{requestId} は、キューに入ったアップロードの処理が確定するまでポーリングし、その後、画像ごとの結果を報告します。進捗バーを更新し、どのファイルがどのような理由で拒否されたかを正確に表示するために使用します。

パラメーター

名前	指定先	必須	備考
`requestId`	path	はい	キューに入ったアップロードのレスポンスの `request.requestId` に含まれる UUID です。直近のアップロードで返された id のみをポーリングしてください。

Upload status

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

JSON

{  "data": {    "getLocationPhotosUploadStatus": {      "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",      "status": "SUCCESS",      "photos": [        { "mediaId": "TWVkaWFGaWxlOjkxODI3", "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "SUCCESS", "errorMessage": null },        { "mediaId": null, "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ERROR", "errorMessage": "Image dimensions below the minimum 250x250." }      ]    }  }}

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

ジョブのステータスが示すのは処理の完了だけであり、すべての画像が正常に追加されたことではありません。ポーリングの間隔は数秒空けてください。間隔を空けずに繰り返すと、すぐに 429 が返されます。

拠点の写真を取得する

GET /locations/{locationId}/photos は、拠点のすべてのメディアファイルを通常の配列として返します。これにはロゴ、カバー、追加画像が含まれ、それぞれに公開 url、thumbnailUrl、カテゴリ、starred フラグ、全期間の viewsCount が含まれます。アップロード前に呼び出して、どの枠が空いているかを確認し、スターの付与や削除の呼び出しに使用する id を収集してください。

パラメーター

名前	指定先	必須	備考
`locationId`	path	はい	base64 の id です。数値の `databaseId` をそのまま指定することもできます。どちらでもない値を指定すると、`errors` に `SY90002: Invalid Id` を含む HTTP 200 が返されます。

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", "fileType": "image", "starred": false, "viewsCount": 0,        "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.jpg",        "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_f47d62a6.jpg" },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "fileType": "image", "starred": true, "viewsCount": 143,        "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" }    ]  }}

categoryName は、Logo、Cover、または Additional です。グリッド表示には thumbnailUrl を、フルサイズ表示には url を使用してください。メディアがない拠点では、エラーではなく空の配列が返されます。

拠点の写真にスターを付ける

POST /locations/photos/star は、注目画像に対応する掲載先で優先的に表示されるように、追加写真に印を付けます。スターを付けられるのは ADDITIONAL の写真のみで、拠点ごとに最大 4 枚です。スターの解除も同じ仕組みで、body 内の starred フラグによって動作が決まります。

パラメーター

名前	指定先	必須	備考
`input.locationId`	body	はい	拠点の base64 の id です。
`input.photoIds`	body	はい	写真取得またはアップロードのレスポンスに含まれるメディアの id です。
`input.starred`	body	はい	スターを付けるには `true`、解除するには `false` を指定します。動作を決めるのはパスではなくこのフラグであり、`/star` と `/unstar` は同じように動作します。

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=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

どちらのパスでもレスポンスキーは starUnstarLocationPhotos で、その値は errors の配列ではなく単一の error です。スター付きの写真が 5 枚目になると、呼び出し全体が SY15012 で失敗します。このチェックでは、すでにスターが付いている写真と、このリクエストに含まれる写真の合計を数えます。

拠点から写真を削除する

POST /locations/photos/remove は、メディアの id を指定して追加写真の関連付けを解除します。古くなった店舗外観の画像を取り除いたり、誤った一括インポートを取り消したりするために使用します。削除できるのは ADDITIONAL の写真のみで、ロゴやカバーを置き換えるには、該当する type を指定して新しい画像をアップロードしてください。

パラメーター

名前	指定先	必須	備考
`input.locationId`	body	はい	拠点の base64 の id です。
`input.photoIds`	body	はい	写真取得またはアップロードのレスポンスから取得した、関連付けを解除するメディアの 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": {      "clientMutationId": null,      "removedCount": 1,      "errors": null    }  }}

removedCount は実際に関連付けが解除されたファイル数を報告するため、0 で errors: null の場合、それらの id はいずれもこの拠点に関連付けられていなかったことを意味します。削除によってファイルの関連付けは解除されますが、メディアライブラリから完全に削除されるとは限りません。

発生するエラー

コード	意味	対処方法
`SY10005`	作成時に `description` が指定されていないか、200 文字未満です。	説明をより詳しく記述してください。
`SY10011`	`street` が指定されていないか、5 文字未満です。	`street` を送信してください。
`SY10010`	`stateIso` が指定されていないか、その国では無効です。	国に記載されている州コードを送信してください。
`SY10036`	`countryIso` はサポートされている国ではありません。	国に記載されているコードを使用してください。
`SY10126`	`city` が必須の国で、指定されていません。	`city` を送信してください。
`SY15012`	拠点のスター付き写真が 4 枚を超えています。	まず 1 枚のスターを解除するか、アップロードから `starred` を除いてください。
`SY90002`	写真のパスに含まれる id が無効です。	ほかの形式ではなく、base64 の id または数値をそのまま渡してください。
`SY90016`	書き込みに Read キーが使用されました。	Write キーを使用してください。
HTTP `404`	すでに `ARCHIVE_SCHEDULED` ではなくなった拠点で、アーカイブを取り消そうとしています。	拠点は完全にアーカイブされているため、代わりに再有効化のフローを使用してください。
HTTP `429`	レート制限を超えました。	`Retry-After` に従って待機してください。レート制限を参照してください。

書き込みでは、success: false と、data.<operation>.errors に詳細を含む HTTP 200 が返される場合もあります。完全な一覧はエラーコードに記載されています。

次の手順

拠点を追加する、拠点を更新する、拠点の写真をアップロードする、拠点を検索してアーカイブする：これらのエンドポイントを使用するタスクガイドです。
国とカテゴリを検索する：作成に必要なcountryIso、stateIso、subCategoryIdの値を確認できます。
プレイスアクションリンク：作成時と更新時に使用するGoogleのアクションボタンの完全なモデルです。
拠点：リソースのトップページと、PythonおよびNodeのSDKリファレンスです。
写真のメソッドには専用のSDKページがあります：Pythonの写真メソッドとNodeの写真メソッドです。