拠点を追加する
掲載先が必要とするフィールドを指定して拠点を作成し、検証エラーに対処して、送信用のキューに登録されたことを確認します。
掲載情報、レビュー、投稿、分析データはすべて拠点IDに紐づいています。POST /api/v4/locationsは拠点を作成し、ご利用のプランに含まれる掲載先ごとに1件の掲載情報をキューに登録します。
1. 必須フィールドを揃える
必須フィールドは10個です。サービス提供地域型のビジネスも住所全体を送信します。hideAddress: trueを指定すると、ListingsAPIは住所を保存しますが、掲載先には送信しません。掲載先では省略された任意フィールドが空欄で表示されるため、用意できる情報はすべて送信してください。
2. 拠点を作成する
POST /api/v4/locationsは、JSONリクエストボディ内のinputオブジェクトでフィールドを受け取ります。Python SDKのメソッドlocations.add()は、同じフィールドをキーワード引数として受け取り、リクエストを送信する前に必須フィールドを検証します。Node SDKのメソッドcreateLocation()は、camelCaseオブジェクトを直接受け取ります。
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "name": "Acme Kitchen", "storeId": "ACME-NYC-001", "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 farms. Open for lunch and dinner seven days a week, with takeout and delivery available.", "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": "11:00am", "end": "10:00pm" }] }, { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "11:00am", "end": "10:00pm" }] }, { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "11:00am", "end": "10:00pm" }] }, { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "11:00am", "end": "10:00pm" }] }, { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "11:00am", "end": "11:00pm" }] }, { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "12:00pm", "end": "11:00pm" }] }, { "day": "SUNDAY", "type": "CLOSED", "slots": [] } ] }}'3. レスポンスを確認する
作成が成功すると、success: trueと、data.createLocation.locationに格納された新しい拠点が返されます。両方の識別子を保存してください。idは以降のすべての書き込みで指定するbase64値で、databaseIdはダッシュボードとWebhookペイロードに表示される数値です。
{ "data": { "createLocation": { "success": true, "errors": null, "location": { "id": "TG9jYXRpb246MTgwMDI5MA==", "databaseId": 1800290, "storeId": "ACME-NYC-001", "name": "Acme Kitchen", "city": "New York", "stateIso": "NY", "countryIso": "US", "status": "PENDING" } } }}拠点の検証とキューへの登録が行われている間、statusはPENDINGになります。追加のAPI呼び出しなしで次の状態に進みます。
4. 検証エラーに対処する
作成は2つの段階で失敗する可能性があります。リクエストの形式が不正な場合やキーが無効な場合は、最上位にerrors配列を含む4xxが返されます。リクエストの形式が正しくても、APIが拒否するフィールドが含まれている場合は、success: falseとdata.createLocation.errors内の問題の詳細を伴う200が返されるため、ステータスコードだけでなく、すべての書き込みのレスポンスボディを確認してください。
{ "data": { "createLocation": { "success": false, "errors": [ { "code": "SY10005", "message": "SY10005: description must be at least 200 characters", "path": ["input", "description"] } ], "location": null } }}どちらのSDKも失敗時に例外を発生させます。Pythonのlocations.add()は必須フィールドをローカルで確認し、リクエストを送信する前にValidationErrorを発生させます。NodeのcreateLocation()はAPIが入力を拒否するとValidationErrorをスローするため、上記のサンプルでは成功フラグを確認していません。
よく発生するコードは次のとおりです。
5. 送信が開始されたことを確認する
拠点を作成すると、ご利用のプランに含まれる掲載先ごとに1件の掲載情報がキューに追加されます。各掲載情報はAVAILABLEまたはIN_PROGRESSの状態から始まり、掲載先が受け入れると、listingUrlを伴うSYNCEDの状態に移行します。
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"Webhookを設定していれば、ポーリングは不要です。レコードが存在するとprofile.createdイベントが発生し、各掲載先のステータスが変化すると、その掲載先のlisting.submissionイベントが発生します。
次の手順
- 拠点を更新する: 営業時間を変更し、臨時休業を設定し、Googleのカテゴリを追加します。
- 拠点の写真をアップロードする: ロゴ、カバー画像、ギャラリー画像をアップロードします。
- Googleに接続して拠点をインポートする: Google Business Profileを連携し、Googleの掲載情報、レビュー、投稿の同期を開始します。
- Apple Business Connectに接続する: オーナーの確認済みApple Businessアカウントを通じて、またはオーナーがそのアカウントを持っていない場合はListingsAPIアカウントを通じて、Apple Mapsに公開します。
- 掲載情報のステータスと公開リンクを確認する: キューに追加したばかりの送信の進行状況を確認します。