Listings APIListings API
Masuk

Periksa status profil bisnis dan dapatkan tautan aktif

Cek sinkronisasi platform publikasi per lokasi dan asisten suara, ambil URL profil bisnis aktif, rangkum cakupan; terima webhook tanpa polling.

Setelah lokasi tersedia, satu profil bisnis untuk setiap platform publikasi dalam paket Anda akan diajukan secara otomatis. Panduan ini menunjukkan cara membaca status terkini masing-masing profil bisnis, mengambil URL profil bisnis yang sudah tayang, dan menghentikan polling setelah webhook disiapkan.

1. Ambil profil bisnis premium untuk suatu lokasi

GET /locations/{locationId}/listings/premium mengembalikan satu record untuk setiap platform publikasi premium dalam paket. Hasilnya berupa array biasa, bukan daftar dengan paginasi. Rute pasangannya, /listings/additional, mengembalikan direktori gratis dengan struktur yang sama; tidak ada parameter kueri listingType.

Premium listings
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "listingUrl": null,        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:28Z"      },      {        "site": { "name": "BeLocalFocussed", "url": "belocalfocussed.com" },        "syncStatus": "SYNCED",        "displayStatus": "Synced",        "actionRequired": false,        "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e",        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:30Z"      }    ]  }}

Setiap baris memasangkan site dengan syncStatus yang dapat dibaca mesin dan displayStatus yang dapat dibaca manusia. lastUpdate memberi tahu Anda kapan baris tersebut terakhir berubah, yang berguna untuk mendeteksi pengajuan yang terhenti.

2. Baca status setiap platform publikasi

syncStatus adalah field yang digunakan untuk menentukan percabangan logika. displayStatus adalah teks yang ditampilkan kepada pengguna, dan syncIssue memuat alasan dari platform publikasi jika tersedia.

syncStatusArtiTindakan yang perlu dilakukan
AVAILABLESiap diajukan, belum dimulai.Tidak perlu melakukan apa pun. Proses akan berlanjut dengan sendirinya.
IN_PROGRESSSudah diajukan ke platform publikasi, menunggu respons.Tunggu. Periksa lastUpdate jika sudah berlalu beberapa minggu.
PENDING_APPROVALPlatform publikasi sudah menerima pengajuan dan sedang meninjaunya.Tunggu.
SYNCED atau COMPLETEDSudah tayang. listingUrl sudah terisi.Kumpulkan tautannya (langkah 3).
REQUIRING_ACTIONTerhambat karena memerlukan tindakan Anda. actionRequired bernilai true.Baca displayStatus, lalu lihat Temukan dan perbaiki kesalahan profil bisnis.
FAILEDPlatform publikasi menolak atau tidak dapat memproses pengajuan tersebut.Baca syncIssue, perbaiki lokasi, lalu lakukan polling lagi.
CANNOT_SUBMITPlatform publikasi ini sama sekali tidak dapat menerima lokasi ini.Biasanya karena negara atau kategori yang tidak didukung oleh platform publikasi.

Google Maps dan Facebook tetap berstatus REQUIRING_ACTION hingga akun pada platform publikasi tersebut terhubung: Google Business Profile untuk Google Maps dan Facebook Page untuk Facebook. Ini merupakan kondisi yang wajar untuk lokasi baru, bukan kesalahan.

Apple Maps tidak memerlukan koneksi. Jika pemilik belum menghubungkan akun organisasi Apple Business yang terverifikasi, ListingsAPI mengajukan lokasi melalui akun Apple Business Connect miliknya sendiri, dan Apple memverifikasi pengajuan tersebut sebelum memublikasikannya. Lihat Hubungkan Apple Business Connect.

listingUrl hanya diisi pada baris profil bisnis yang sudah tayang. Filter baris berstatus SYNCED (dan COMPLETED), lalu simpan URL beserta nama situsnya agar Anda dapat menampilkan daftar "lihat profil bisnis yang sudah tayang" atau menyimpannya pada record Anda sendiri.

Live links
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.listingUrl != null)       | {site: .site.name, url: .listingUrl}]'

Baris SYNCED dengan listingUrl bernilai null memang dapat ditemukan: beberapa direktori tidak menyediakan URL halaman publik. Jadikan status sebagai acuan utama dan anggap tautan sebagai opsional.

4. Buat ringkasan cakupan

Menghitung baris berdasarkan syncStatus menghasilkan ringkasan kondisi dalam satu baris untuk setiap lokasi: berapa banyak platform publikasi yang profil bisnisnya sudah tayang, berapa banyak yang masih dalam proses, dan berapa banyak yang terhambat. Angka inilah yang perlu ditampilkan di dasbor.

Coverage
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.listingsForLocation      | group_by(.syncStatus)      | map({status: .[0].syncStatus, count: length})'

Jalankan proses ini untuk banyak lokasi dengan menelusuri halaman hasil GET /locations dan memanggil endpoint premium satu kali untuk setiap lokasi. Setiap panggilan diperhitungkan dalam batas laju permintaan Anda, jadi beri jeda antarpanggilan dan patuhi Retry-After saat menerima 429. Temukan dan perbaiki kesalahan profil bisnis menunjukkan perulangan ini sebagai pemeriksaan menyeluruh dalam satu akun.

5. Periksa asisten suara

Asisten suara (Google Assistant, Alexa, Siri, Cortana, Bixby) memiliki endpoint sendiri, GET /locations/{locationId}/voice-assistants, dengan pilihan status yang lebih sedikit. Google Assistant bergantung pada koneksi Google, sehingga lokasi yang belum memiliki koneksi tersebut juga perlu diperhatikan di sini. Hasil Siri berasal dari profil bisnis lokasi tersebut di Apple Maps.

Voice assistants
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "voiceAssistantsForLocation": [      {        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "voiceIdentifier": "SIRI",        "name": "Siri",        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}
syncStatusArti
NOT_SUBMITTEDBelum dikirim ke asisten.
IN_PROGRESSPengiriman sedang berlangsung.
REQUIRING_ACTIONTerhambat karena menunggu tindakan Anda; baca syncIssue.
LIVETelah dipublikasikan.

Tidak ada tautan aktif untuk asisten suara; LIVE adalah status akhir.

6. Terima peristiwa webhook alih-alih melakukan polling

Jika Anda telah mengonfigurasi URL webhook di /dashboard/webhooks, peristiwa listing.submission dipicu setiap kali pengiriman ke platform publikasi untuk satu lokasi mencapai status akhir. Peristiwa ini memuat status (success, incomplete, atau canceled), situs, serta live_link jika berhasil, yaitu URL yang sama dengan yang Anda kumpulkan pada langkah 3.

Route listing.submission
import base64 def handle(payload: dict) -> None:  if payload["event"] != "listing.submission":      return   data = payload["data"]  # "TG9jYXRpb246Mjc5Mzgx" -> "Location:279381"  global_id = base64.b64decode(data["location_id"]).decode()  database_id = int(global_id.split(":")[1])   site = data["site"]["name"]  status = payload["status"]   if status == "success":      live_link = payload.get("live_link")      save_live_link(database_id, site, live_link)  elif status == "incomplete":      flag_for_review(database_id, site, payload.get("error_message"))

Berikan respons berupa 200 dalam waktu 5 detik dan lakukan pemrosesan setelahnya; tidak ada percobaan ulang. Untuk kerangka kode penerima dan pemeriksaan tanda tangan, lihat Tanggapi peristiwa dengan webhook.

Langkah berikutnya