掲載情報のエラーを見つけて修正する

拠点の掲載情報を対応が必要な行に絞り込み、掲載先が示す理由を確認し、原因に合った修正を適用して、安全に再ポーリングしたうえで、アカウント全体を確認します。

ほとんどの掲載情報は、手を加えなくても同期されます。同期されない掲載情報では、displayStatusとsyncIssueに理由が示されており、ほぼすべての原因は5つの修正方法のいずれかに対応します。このガイドでは、掲載情報の生データから、何がブロックされていてどう対処すべきかを示すアカウント単位のレポートを作成するまでの手順を説明します。

1. 掲載情報を取得し、問題のある行だけを残す

プレミアム掲載情報を取得し、正常な行をすべて除外します。actionRequiredがtrueの場合、またはsyncStatusがFAILED、CANNOT_SUBMIT、REQUIRING_ACTIONのいずれかの場合、その行には対応が必要です。IN_PROGRESSとPENDING_APPROVALはエラーではなく、掲載先での処理待ちを示します。

Problem rows

curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.actionRequired                or (.syncStatus | IN("FAILED", "CANNOT_SUBMIT", "REQUIRING_ACTION")))]'

JSON

{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "syncIssue": null      },      {        "site": { "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "syncIssue": "Publisher requires website URL"      }    ]  }}

問題のある行の状況は、2つのフィールドで説明されます。displayStatusは、その行の現在の状態についてプラットフォームが示す概要です。syncIssueは、掲載先から理由が提供されている場合に、その理由を示します。両方を確認してください。上のサンプルでは、Local MintのdisplayStatusはパートナー側で問題が発生していると示していますが、syncIssueには、ウェブサイトが未設定であるという実際の原因が示されています。

フィールド	例	用途
`displayStatus`	`Connect your account to sync the listing`	人に表示する説明文です。
`syncIssue`	`Publisher requires website URL`	修正方法の選択に使用します。掲載先が理由を示していない場合は`null`です。
`actionRequired`	`true`	分類に使用します。`true`は、対応するまで何も進まないことを意味します。

すべての拠点を一覧表示から読み取るたびに、拠点自体にもcreateErrors配列が含まれます。この配列にはレコードの作成時に見つかった検証上の問題が格納されており、syncIssueがないまま行が失敗した場合に確認するもう1つの場所となります。

3. 原因に合った修正方法を選ぶ

ブロックされている行のほとんどは、少数の原因によるものです。

原因	現れ方	修正方法
アカウントが接続されていない	Google MapsまたはFacebookが`REQUIRING_ACTION`で、`Connect your account to sync the listing`が示されます。	その掲載先のアカウントを接続してください。Googleを接続して拠点をインポートまたはFacebookページを接続を参照してください。Apple Mapsには接続は不要です。Apple Business Connectを接続を参照してください。
ウェブサイトが未設定	`FAILED`で、`syncIssue: Publisher requires website URL`が示されます。	拠点に`bizUrl`を設定してください。拠点を更新を参照してください。
掲載先が対象国に対応していない	`CANNOT_SUBMIT`で、`syncIssue`はありません。	拠点の`countryIso`を、プランのサイトを一覧表示から取得したそのサイトの`supportedCountries`と比較してください。修正できる点はなく、その掲載先はこの拠点を受け付けません。
住所の非公開に対応していない	`hideAddress: true`が設定された非店舗型ビジネスで、`CANNOT_SUBMIT`または`FAILED`が示されます。	サイトの`hideAddressSupportedCountries`を確認してください。住所を表示するか、この掲載先がスキップされることを受け入れてください。
Facebookページに営業時間がない	Facebookが`IN_PROGRESS`で、`syncIssue: Temporary status is not applicable for this listing because it has no hours or opening information`が示されます。	Facebook上のページに営業時間を追加してから、拠点の更新を送信してください。拠点を更新を参照してください。
説明文またはカテゴリが拒否された	`FAILED`で、`syncIssue`に該当するフィールドが示されます。	拠点の説明文または`subCategoryId`を更新してから、再ポーリングしてください。

国と住所の非公開に関するルールを確認するには、プランのサイト一覧を1回取得してキャッシュしてください。この一覧にはページネーションがなく、変更されることもほとんどありません。

Plan sites

curl -s https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.name == "Yelp")      | {name, supportedCountries, hideAddressSupportedCountries}'

JSON

{  "name": "Yelp",  "supportedCountries": ["US", "CA", "GB", "DE", "FR"],  "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]}

拠点のcountryIsoがsupportedCountriesに含まれていない場合、その掲載先の行はCANNOT_SUBMITから変わることはありません。再試行するのではなく、カバレッジの集計から除外してください。

4. 修正後に再ポーリングする

拠点を更新すると、影響を受ける掲載先への新たな送信が開始されます。行はFAILEDまたはREQUIRING_ACTIONからIN_PROGRESSに戻り、掲載先が受け付けるとSYNCEDに移行します。掲載先での処理には数分から数週間かかるため、秒単位ではなく時間単位の間隔でポーリングしてください。

ポーリングは毎回レート制限にカウントされます。429の場合は、Retry-Afterを読み取り、そこに示された秒数だけ待ってください。SDKは同じ値を含むRateLimitErrorを送出します。

Re-poll

# -D - prints response headers so you can see Retry-After on a 429curl -s -D - https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| grep -i -E "^HTTP|^Retry-After"

syncStatusが変わる前でも、lastUpdateが進んでいれば、掲載先が新たな送信を処理したことを示します。Webhookを利用している場合は、listing.submissionイベントでこのループを置き換えられます。

5. アカウント全体を確認する

アカウント全体でブロックされているすべての行を見つけるには、GET /locations（カーソル形式のコネクション：first、after、edges[].node）のページを順に取得し、拠点ごとにプレミアムエンドポイントを1回呼び出します。問題のある行を、拠点をキーとする1つのレポートにまとめます。Python SDKではauto_paging_iter()でカーソルをたどり、Node SDKではfetchAll: trueでたどります。サンプルでは、手順4のバックオフヘルパーを再利用します。

Account sweep

# One page of locations, then one listings call per location.# Repeat with &after=<pageInfo.endCursor> while hasNextPage is true.curl -s "https://listingsapi.com/api/v4/locations?first=50" \-H "Authorization: API $LISTINGSAPI_KEY" \| jq -r '.data.allLocations.edges[].node.id' \| while read -r id; do    curl -s "https://listingsapi.com/api/v4/locations/$id/listings/premium" \      -H "Authorization: API $LISTINGSAPI_KEY" \      | jq --arg id "$id" '[.data.listingsForLocation[]           | select(.syncStatus != "SYNCED" and .syncStatus != "COMPLETED")           | {location: $id, site: .site.name, status: .syncStatus, issue: .syncIssue}]'    sleep 6   # stay under 10 requests a minute on Launch  done

このレポートには、まだ処理中の行と、実際にブロックされている行がまとめられています。誰かに渡す前に、手順3の表に従って分類してください。IN_PROGRESSとPENDING_APPROVALは待つ必要があり、REQUIRING_ACTIONは接続が必要で、FAILEDは拠点のフィールドの修正が必要です。

次の手順

掲載情報のステータスと公開リンクを確認する: 同じデータのうち、正常な状態のものを確認します。
拠点を更新する: bizUrl、説明文、カテゴリを設定します。
Googleに接続して拠点をインポートするとFacebookページに接続する: REQUIRING_ACTIONの行の問題を解消します。
リファレンス: プレミアム掲載情報を取得する、プランのサイト一覧を取得する、すべての拠点の一覧を取得する、エラーコード。