Profil bisnis

Tiap endpoint profil bisnis: contoh cURL/Python/Node, status sinkronisasi premium, asisten suara, deteksi duplikat per lokasi/akun, penyembunyian duplikat

Profil bisnis adalah entri satu lokasi di satu direktori platform publikasi. Pembuatan lokasi memasukkan satu profil bisnis untuk setiap platform publikasi dalam paket Anda ke antrean, dan endpoint profil bisnis membaca status masing-masing profil bisnis, menampilkan daftar duplikat yang ditemukan oleh proses deteksi, serta mengonfirmasi atau menolaknya. Keempat endpoint GET dapat digunakan dengan kunci Read (baca); kedua endpoint POST memerlukan kunci Write (tulis).

Ringkasan endpoint

Metode	Path	Fungsi	Referensi
`GET`	`/locations/{locationId}/listings/premium`	Status sinkronisasi setiap platform publikasi premium untuk suatu lokasi.	Dapatkan profil bisnis premium
`GET`	`/locations/{locationId}/voice-assistants`	Status sinkronisasi di Google Assistant, Alexa, Siri, Cortana, Bixby.	Dapatkan profil bisnis asisten suara
`GET`	`/locations/listings/duplicates`	Ringkasan duplikat yang terdeteksi di seluruh akun, dibagi dalam halaman.	Dapatkan semua profil bisnis duplikat dalam satu akun
`GET`	`/locations/{locationId}/listings/duplicates`	Duplikat untuk satu lokasi, dikelompokkan berdasarkan situs.	Dapatkan profil bisnis duplikat untuk suatu lokasi
`POST`	`/locations/listings/mark-as-duplicate`	Konfirmasikan item profil bisnis sebagai duplikat untuk disembunyikan.	Tandai profil bisnis sebagai duplikat
`POST`	`/locations/listings/mark-as-not-duplicate`	Tolak item profil bisnis yang keliru terdeteksi sebagai duplikat.	Tandai profil bisnis sebagai bukan duplikat

Baca status profil bisnis premium

GET /locations/{locationId}/listings/premium

Mengembalikan satu rekaman untuk setiap platform publikasi premium dalam paket lokasi tersebut di bawah data.listingsForLocation. Hasilnya berupa array biasa, bukan daftar yang dibagi dalam halaman. Path sejajar /listings/additional mengembalikan direktori gratis dalam struktur yang sama; tidak ada parameter kueri listingType, dan nilai yang dikirim melalui parameter tersebut diabaikan.

Parameter

Nama	Letak	Wajib	Catatan
`locationId`	path	Ya	id base64 atau `databaseId` numerik.

Premium listings

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "listingsForLocation": [      {        "id": "TGlzdGluZzoxMDQ0Njg3MjM=",        "site": { "databaseId": "1", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3Mjc=",        "site": { "databaseId": "387", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3MDk=",        "site": { "databaseId": "301", "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "listingUrl": null,        "syncIssue": "Publisher requires website URL",        "lastUpdate": "2026-07-06T18:34:03Z"      }    ]  }}

Tentukan percabangan berdasarkan syncStatus. Tampilkan displayStatus kepada pengguna, baca syncIssue untuk mengetahui alasan dari platform publikasi, dan gunakan lastUpdate untuk mendeteksi pengiriman yang terhenti. listingUrl hanya diisi pada baris yang sudah tayang.

`syncStatus`	Arti
`AVAILABLE`	Siap disinkronkan, belum dimulai.
`IN_PROGRESS`	Sudah dikirim ke platform publikasi, menunggu respons.
`PENDING_APPROVAL`	Platform publikasi sedang meninjaunya.
`SYNCED` atau `COMPLETED`	Sudah tayang. `listingUrl` terisi.
`REQUIRING_ACTION`	Terhambat karena menunggu tindakan Anda. `actionRequired` bernilai `true`; baca `displayStatus`.
`FAILED`	Sinkronisasi gagal. Baca `syncIssue`.
`CANNOT_SUBMIT`	Platform publikasi ini sama sekali tidak dapat menerima lokasi ini.

Google Maps, Facebook, dan Waze tetap berstatus REQUIRING_ACTION dengan displayStatus: "Connect your account to sync the listing" hingga akun yang sesuai dihubungkan. Hal ini wajar untuk lokasi baru.

Baca status asisten suara

GET /locations/{locationId}/voice-assistants

Mengembalikan satu rekaman untuk setiap asisten suara di bawah data.voiceAssistantsForLocation: Google Assistant, Amazon Alexa, Apple Siri, Microsoft Cortana, dan Samsung Bixby. Hasilnya berupa array biasa dengan pilihan status yang lebih sedikit daripada endpoint premium.

Parameter

Nama	Letak	Wajib	Catatan
`locationId`	path	Ya	id base64 atau `databaseId` numerik.

Voice assistants

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "voiceAssistantsForLocation": [      {        "databaseId": "104468723",        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "connectedAccountId": null,        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "databaseId": "104468711",        "voiceIdentifier": "SIRI",        "name": "Siri",        "connectedAccountId": null,        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}

Tandai setiap baris yang actionRequired-nya bernilai true atau yang syncIssue-nya terisi. errors memuat string kesalahan dari sisi platform publikasi, dan connectedAccountId mengidentifikasi akun terhubung yang digunakan untuk sinkronisasi jika ada akun yang berlaku. Hasil Google Assistant berasal dari koneksi Google Business Profile, sehingga ketiadaan koneksi Google merupakan alasan paling umum mengapa Google Assistant memerlukan perhatian. Hasil Siri berasal dari profil bisnis lokasi tersebut di Apple Maps.

`syncStatus`	Arti
`NOT_SUBMITTED`	Belum dikirim ke asisten.
`IN_PROGRESS`	Pengiriman sedang berlangsung.
`REQUIRING_ACTION`	Masukan pelanggan diperlukan sebelum sinkronisasi dapat dilanjutkan.
`LIVE`	Sudah dipublikasikan. Tidak ada tautan ke profil yang tayang untuk asisten suara.

Rekap duplikat di seluruh akun

GET /locations/listings/duplicates

Mengembalikan semua duplikat terdeteksi yang dapat diakses oleh kunci, di seluruh lokasi dan platform publikasi, di bawah data.duplicateListingsRollup. Hasilnya berupa halaman berbasis offset: page dan perPage sebagai masukan, serta records[] beserta pageInfo.totalRecords, pageInfo.totalPages, dan pageInfo.hasNextPage sebagai keluaran. Filter berupa parameter query datar, bukan JSON. Jika tidak ada parameter yang diberikan, nilai default status adalah POTENTIAL dan nilai default tag adalah all, sehingga pemanggilan tanpa parameter mengembalikan duplikat berstatus terbuka dalam akun.

Parameter

Nama	Letak	Wajib	Catatan
`status`	query	Tidak	`POTENTIAL` (default), `PROCESSING`, `FIXED`, atau `FAILED`. Tidak membedakan huruf besar dan kecil. Nilai lainnya menghasilkan `400`.
`siteId`	query	Tidak	Batasi ke satu platform publikasi berdasarkan id situs numeriknya (`site.databaseId` dari endpoint premium, atau id plan-sites).
`tag`	query	Tidak	Batasi cakupan rekap ke satu tag. Nilai default adalah `all`.
`page`	query	Tidak	Nomor halaman dimulai dari 1. Nilai default adalah `1`.
`perPage`	query	Tidak	Jumlah rekaman per halaman.

Wrapper Python dan Node hanya menyediakan tag dan page. Untuk memfilter berdasarkan status atau siteId, atau menetapkan perPage, panggil rute secara langsung seperti yang ditunjukkan dalam Tangani profil bisnis duplikat.

Account rollup

curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=POTENTIAL&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "duplicateListingsRollup": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false,        "totalPages": 34,        "totalRecords": 1673      },      "records": [        {          "id": "3329229",          "name": "Woodbury Train Station",          "nameValid": false,          "duplicateProcessingState": "POTENTIAL",          "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",          "locationId": "73451",          "siteName": "City Squares",          "siteUrl": "citysquares.com"        }      ]    }  }}

Rekap menunjukkan tempat duplikat berada: setiap rekaman mencantumkan locationId dan siteName. duplicateProcessingState adalah status siklus hidup yang sama dengan yang dilaporkan endpoint per lokasi sebagai status. Telusuri halaman satu per satu hingga hasNextPage bernilai false; perulangan tanpa jeda adalah cara tercepat untuk terkena 429.

Status	Makna
`POTENTIAL`	Terdeteksi, belum ada yang menindaklanjutinya.
`PROCESSING`	Dikonfirmasi sebagai duplikat; penonaktifan sedang diproses bersama platform publikasi.
`FIXED`	Platform publikasi telah menghapus atau menggabungkannya.
`FAILED`	Penonaktifan tidak berhasil. Periksa `liveLink`.

Tampilkan daftar duplikat untuk satu lokasi

GET /locations/{locationId}/listings/duplicates

Mengembalikan semua duplikat terdeteksi untuk satu lokasi di bawah data.duplicateListingsForLocation, yang dikelompokkan menurut situs platform publikasi. Hasilnya berupa array biasa. Setiap kelompok adalah sebuah situs (name, url) dengan array listings, dan setiap entri memuat listingItemId yang diterima oleh kedua endpoint penandaan. Array kosong berarti tidak ada duplikat yang terdeteksi.

Parameter

Nama	Letak	Wajib	Catatan
`locationId`	path	Ya	id Base64 atau `databaseId` numerik.

Duplicates for a location

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/duplicates \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "duplicateListingsForLocation": [      {        "id": "U2l0ZToxNTA=",        "name": "City Squares",        "url": "citysquares.com",        "listings": [          {            "id": "RHVwbGljYXRlOjIzNTk4NDUw",            "listingItemId": "TGlzdGluZ0l0ZW06MjM1OTg0NTA=",            "name": "Woodbury Train Station",            "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",            "status": "POTENTIAL"          }        ]      }    ]  }}

Buka liveLink untuk meninjau entri, lalu simpan listingItemId. Dalam Node SDK, d.id yang telah diratakan adalah nilai yang perlu diteruskan. status menggunakan 4 nilai yang sama dengan rekap akun di atas.

Konfirmasikan item profil bisnis sebagai duplikat

POST /locations/listings/mark-as-duplicate

Menandai item profil bisnis sebagai duplikat yang telah dikonfirmasi agar dapat dinonaktifkan melalui platform publikasi. Kirim nilai listingItemId di bawah input, dan gabungkan semua item yang telah dikonfirmasi untuk satu lokasi dalam satu pemanggilan, alih-alih satu pemanggilan per item. Ini adalah operasi tulis dan memerlukan kunci Write (tulis).

Parameter

Nama	Letak	Wajib	Catatan
`input.listingItemIds`	body	Ya	Array nilai `listingItemId` base64 dari endpoint duplikat.
`input.locationId`	body	Tidak	id lokasi Base64 atau numerik. Membatasi cakupan operasi ke satu lokasi.

Mark as duplicate

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

JSON

{  "data": {    "markAsDuplicate": {      "success": true,      "errors": null    }  }}

success: true berarti item diterima dan beralih ke PROCESSING. Respons 200 dengan success: false, atau respons 400, disertai array errors yang setiap entrinya memuat code, message, dan path; penyebab umumnya adalah id yang tidak dikenal atau salah format. Python SDK mengembalikan payload; Node SDK justru melempar ValidationError, sehingga promise yang terselesaikan berarti operasi berhasil.

Nyatakan item profil bisnis sebagai bukan duplikat

POST /locations/listings/mark-as-not-duplicate

Menyatakan calon duplikat sebagai hasil deteksi positif palsu. Deteksi bersifat konservatif dan akan menandai cabang waralaba lain, profil kedua yang sah, atau lokasi yang berganti nama. Setelah dinyatakan bukan duplikat, item tidak lagi muncul di kedua endpoint duplikat. Endpoint ini menerima body yang identik dengan endpoint di atas dan juga digunakan untuk membatalkan penandaan item yang keliru.

Parameter

Nama	Letak	Wajib	Catatan
`input.listingItemIds`	body	Ya	Array nilai `listingItemId` base64 yang akan dinyatakan bukan duplikat.
`input.locationId`	body	Tidak	id lokasi Base64 atau numerik. Membatasi cakupan operasi ke satu lokasi.

Mark as not duplicate

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-not-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

JSON

{  "data": {    "markAsNotDuplicate": {      "success": true,      "errors": null    }  }}

Responsnya adalah data.markAsNotDuplicate dengan field success dan errors yang sama seperti pada pemanggilan penandaan sebagai duplikat. Item yang dinyatakan bukan duplikat dicatat sebagai bukan duplikat yang telah dikonfirmasi dan tidak muncul kembali pada proses deteksi berikutnya.

Kesalahan yang akan Anda temui

Kode atau status	Arti	Solusi
`401`	Kunci API tidak disertakan atau tidak valid.	Kirim `Authorization: API $LISTINGSAPI_KEY`.
`400` pada agregasi akun	`status` bukan salah satu dari `POTENTIAL`, `PROCESSING`, `FIXED`, `FAILED`.	Gunakan salah satu dari empat nilai tersebut.
`400` pada endpoint mark	ID item profil bisnis tidak dikenal atau formatnya salah. Baca `errors[].code` dan `message`.	Kirim nilai `listingItemId` dari endpoint duplicates.
`200` dengan `success: false`	Permintaan dijalankan, tetapi input ditolak. Detailnya ada di `data.<op>.errors`.	Periksa isi respons setiap operasi tulis, bukan hanya statusnya.
`SY90016` (HTTP `400`)	Kunci Read digunakan untuk operasi tulis.	Gunakan kunci Write untuk kedua endpoint mark.
`429`	Batas laju terlampaui. Paket Launch mengizinkan 10 permintaan per menit.	Tunggu `Retry-After`, lalu lanjutkan. Lihat Batas laju.

Semua kode tercantum dalam referensi kesalahan.

Langkah berikutnya

Periksa status profil bisnis dan tautan aktif: gunakan endpoint premium dan voice untuk membuat dasbor cakupan.
Temukan dan perbaiki kesalahan profil bisnis: tangani baris REQUIRING_ACTION dan FAILED.
Tangani profil bisnis duplikat: proses peninjauan di keempat endpoint duplikat, termasuk pelacakan status.
Hubungkan Google dan impor lokasi: hubungkan Google Business Profile yang digunakan oleh Google Maps dan Google Assistant.
Hubungkan Apple Business Connect: publikasikan ke Apple Maps melalui akun Apple Business milik pemilik yang telah diverifikasi.
Halaman utama sumber daya: Profil bisnis. Referensi SDK: Profil bisnis Python, Profil bisnis Node.