Listings APIListings API
Masuk

Temukan dan perbaiki kesalahan profil bisnis

Filter profil bisnis lokasi yang perlu ditangani, baca alasan platform publikasi, perbaiki sesuai alasan, polling ulang dengan aman, periksa seluruh akun.

Sebagian besar profil bisnis tersinkronisasi tanpa bantuan. Profil bisnis yang tidak tersinkronisasi menjelaskan alasannya dalam displayStatus dan syncIssue, dan hampir setiap penyebab dapat diatasi dengan salah satu dari lima perbaikan. Panduan ini dimulai dari baris data mentah profil bisnis hingga laporan per akun tentang apa yang terhambat dan cara menanganinya.

1. Ambil profil bisnis dan sisakan baris yang bermasalah

Ambil profil bisnis premium dan singkirkan semua yang tidak bermasalah. Suatu baris perlu ditangani ketika actionRequired bernilai true, atau ketika syncStatus bernilai FAILED, CANNOT_SUBMIT, atau REQUIRING_ACTION. IN_PROGRESS dan PENDING_APPROVAL bukan kesalahan; keduanya menunjukkan antrean platform publikasi.

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. Baca alasannya

Dua field menjelaskan baris yang bermasalah. displayStatus adalah ringkasan platform tentang status baris tersebut. syncIssue adalah alasan dari platform publikasi itu sendiri, jika platform publikasi memberikannya. Baca keduanya: pada contoh di atas, displayStatus Local Mint menyatakan bahwa mitra sedang mengalami masalah, tetapi syncIssue menunjukkan penyebab sebenarnya, yaitu situs web yang belum dicantumkan.

FieldContohGunakan untuk
displayStatusConnect your account to sync the listingTeks yang Anda tampilkan kepada seseorang.
syncIssuePublisher requires website URLMemilih perbaikan. Bernilai null ketika platform publikasi tidak memberikan alasan.
actionRequiredtruePengurutan: true berarti tidak ada kemajuan sampai Anda mengambil tindakan.

Data lokasi itu sendiri juga menyertakan array createErrors setiap kali dibaca melalui Cantumkan semua lokasi. Array ini berisi masalah validasi yang ditemukan saat rekaman dibuat dan merupakan tempat kedua untuk diperiksa ketika suatu baris gagal tanpa syncIssue.

3. Petakan penyebab ke perbaikan

Hampir setiap baris yang terhambat disebabkan oleh sejumlah kecil penyebab.

PenyebabGejalanyaPerbaikan
Akun belum terhubungGoogle Maps atau Facebook berstatus REQUIRING_ACTION dengan Connect your account to sync the listing.Hubungkan akun pada platform publikasi tersebut: Hubungkan Google dan impor lokasi atau Hubungkan Halaman Facebook. Apple Maps tidak memerlukan koneksi; lihat Hubungkan Apple Business Connect.
Situs web belum dicantumkanFAILED dengan syncIssue: Publisher requires website URL.Tetapkan bizUrl pada lokasi. Lihat Perbarui lokasi.
Negara tidak didukung oleh platform publikasiCANNOT_SUBMIT, tanpa syncIssue.Bandingkan countryIso lokasi dengan supportedCountries situs tersebut dari Cantumkan situs dalam paket. Tidak ada yang perlu diperbaiki; platform publikasi tidak akan menerimanya.
Alamat tersembunyi tidak didukungCANNOT_SUBMIT atau FAILED pada bisnis area layanan dengan hideAddress: true.Periksa hideAddressSupportedCountries situs tersebut. Tampilkan alamat atau terima bahwa platform publikasi ini dilewati.
Halaman Facebook tidak memiliki jam bukaFacebook berstatus IN_PROGRESS dengan syncIssue: Temporary status is not applicable for this listing because it has no hours or opening information.Tambahkan jam buka ke Halaman di Facebook, lalu kirim pembaruan lokasi. Lihat Perbarui lokasi.
Deskripsi atau kategori ditolakFAILED dengan syncIssue yang menyebutkan nama field.Perbarui deskripsi atau subCategoryId pada lokasi, lalu lakukan polling ulang.

Untuk memeriksa aturan negara dan alamat tersembunyi, ambil situs dalam paket satu kali dan simpan dalam cache; daftar ini tidak menggunakan paginasi dan jarang berubah.

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

Jika countryIso lokasi tidak ada dalam supportedCountries, baris platform publikasi tersebut tidak akan pernah keluar dari status CANNOT_SUBMIT. Kecualikan baris tersebut dari angka cakupan Anda alih-alih mencoba ulang.

4. Lakukan polling ulang setelah perbaikan

Pembaruan lokasi memicu pengiriman baru ke platform publikasi yang terdampak. Baris berpindah dari FAILED atau REQUIRING_ACTION kembali ke IN_PROGRESS, lalu ke SYNCED ketika platform publikasi menerimanya. Platform publikasi memerlukan waktu beberapa menit hingga beberapa minggu, jadi lakukan polling dengan jadwal dalam hitungan jam, bukan detik.

Setiap polling diperhitungkan dalam batas laju. Saat menerima 429, baca Retry-After dan tunggu selama jumlah detik tersebut; SDK memunculkan RateLimitError dengan nilai yang sama.

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"

Kemajuan pada lastUpdate merupakan tanda bahwa platform publikasi telah memproses pengiriman baru, bahkan sebelum syncStatus berubah. Jika Anda menggunakan webhook, peristiwa listing.submission menggantikan perulangan ini.

5. Lakukan pemeriksaan menyeluruh dalam satu akun

Untuk menemukan setiap baris yang terblokir di seluruh akun, telusuri halaman demi halaman GET /locations (koneksi berbasis kursor: first, after, edges[].node) dan panggil endpoint premium sekali per lokasi. Kumpulkan baris yang bermasalah ke dalam satu laporan dengan lokasi sebagai kunci. Python SDK mengikuti kursor dengan auto_paging_iter(); Node SDK melakukannya dengan fetchAll: true. Contoh-contoh ini menggunakan kembali fungsi bantu backoff dari langkah 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

Laporan ini mengelompokkan baris yang masih diproses bersama baris yang benar-benar terblokir. Pisahkan baris-baris tersebut berdasarkan tabel pada langkah 3 sebelum menyerahkan laporan kepada siapa pun: IN_PROGRESS dan PENDING_APPROVAL memerlukan kesabaran, REQUIRING_ACTION memerlukan koneksi, dan FAILED memerlukan sebuah field pada lokasi.

Langkah selanjutnya