Hubungkan Google Business Profile dan impor lokasi Anda

Buat tautan koneksi Google, cocokkan profil bisnis Google pemilik ke lokasi Anda, konfirmasi hasilnya, lalu impor profil bisnis yang belum memiliki lokasi.

Akun Google yang terhubung memungkinkan publikasi dan pelaporan untuk suatu lokasi di Google. Selama belum ada akun yang terhubung, baris Google Maps dalam daftar profil bisnis premium lokasi tersebut tetap REQUIRING_ACTION, ulasan Google tidak diambil, postingan tidak dapat dipublikasikan ke GOOGLE, dan analitik Google mengembalikan null. Menghubungkan akun tersebut mengatasi keempat hal ini.

Alur massal (langkah 1 hingga 6) menghubungkan satu akun Google secara keseluruhan dalam satu kali proses dan mencocokkan setiap profil bisnis milik akun tersebut dengan lokasi Anda. Alur lokasi tunggal (langkah 7) menghubungkan satu lokasi setiap kali: tautannya terikat pada lokasi tersebut, sehingga tidak ada langkah pencocokan setelahnya.

1. Buat tautan penghubung dan arahkan pemilik ke tautan tersebut

Tautan ini hanya berlaku untuk akun pemilik kunci API, sehingga isi permintaan hanya memuat dua URL pengalihan Anda. Arahkan pemilik ke url yang dikembalikan; Google mengarahkan mereka kembali ke successUrl atau errorUrl setelah mereka selesai.

Connect link

curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/google/success",    "errorUrl": "https://app.example.com/connect/google/error"  }}'

JSON

{  "data": {    "bulkConnectLinkForGoogle": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

url di atas adalah nilai contoh. Arahkan pemilik ke url yang dikembalikan dalam respons Anda sendiri.

Tautan ini berlaku selama 24 jam. Pastikan url tidak bernilai null, bukan hanya mengandalkan success. Jika kredensial pemilik kedaluwarsa di kemudian hari, buat tautan baru dengan cara yang sama: koneksi yang ada diperbarui, bukan diduplikasi.

2. Ambil daftar akun yang terhubung setelah kembali dari OAuth

Saat pemilik tiba di successUrl Anda, ambil daftar akun Google. Halaman ini menggunakan offset: records[] ditambah pageInfo.totalRecords, dengan paginasi menggunakan page dan perPage.

List accounts

curl "https://listingsapi.com/api/v4/connected-accounts?publisher=GoogleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "email": "owner@brightsmile-dental.com",          "status": "CONNECTED",          "requestMatchesStatus": "MATCH_COMPLETED",          "connectedLocationsCount": 0        }      ]    }  }}

Pilih rekaman yang nilai email-nya merujuk pada pemilik yang baru saja memberikan persetujuan, lalu simpan connectedAccountId dari rekaman tersebut. Setiap pemanggilan selanjutnya menggunakan UUID ini.

`status`	Arti
`CONNECTED`	Kredensial valid. Pencocokan dapat dipicu dengan aman.
`MATCH_IN_PROGRESS`	Proses pencocokan berada dalam antrean atau sedang berjalan.
`CONNECTIVITY_ISSUE`	Otorisasi telah kedaluwarsa. `connectivityIssue` menjelaskan alasannya; terbitkan ulang tautan penghubung.

Filter kueri opsional status menggunakan istilah yang berbeda (Connected, NotConnected, ConnectionIssue); memasukkan kembali nilai status dari rekaman itu sendiri akan menghasilkan 400.

3. Picu pencocokan

Pencocokan mengambil setiap profil yang dapat diakses akun tersebut dan memasangkan masing-masing profil dengan salah satu lokasi Anda. Proses ini hanya menghasilkan saran; belum ada yang ditautkan.

Trigger matches

curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["4f712c17-4f95-42dd-90f4-97171a2e67b5"] } }'

Responsnya adalah data.connectedAccountsTriggerMatches dengan success dan failedIds. success: true berarti tugas telah dimasukkan ke antrean; setiap akun yang tidak dapat dimasukkan ke antrean tercantum dalam failedIds.

4. Periksa secara berkala hingga MATCH_COMPLETED

Periksa detail akun setiap 15 detik dengan perulangan yang dibatasi. Interval ini juga menjaga agar penggunaan paket Launch tetap dalam batas 10 permintaan per menit.

Poll details

curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/details \-H "Authorization: API $LISTINGSAPI_KEY"

Rekaman dikembalikan pada data.connectedAccountDetails.details dan memiliki field yang sama dengan rekaman dalam daftar. requestMatchesStatus bernilai MATCH_IN_PROGRESS selama tugas berjalan dan MATCH_COMPLETED saat saran sudah siap. Completed berarti proses pencocokan telah selesai, bukan berarti ada yang sudah ditautkan: connectedLocationsCount tetap bernilai 0 hingga Anda mengonfirmasinya.

5. Tinjau dan konfirmasikan saran

Setiap saran memasangkan salah satu lokasi Anda (locationInfo, dengan locationId sebagai databaseId-nya) dengan satu profil bisnis Google (suggestedLocationInfo). Tampilkan keduanya kepada operator, atau terima secara otomatis jika nama dan kotanya cocok.

Suggestions

curl "https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "connectionSuggestionsForAccount": {      "pageInfo": { "hasNextPage": false, "totalRecords": 2 },      "records": [        {          "accountType": "GMB",          "matchedDataDatabaseId": "0d5e306f-0da0-46e3-929f-fd3c67ccd8cc",          "locationId": "73415",          "locationInfo": { "name": "My Business", "city": "Lincoln", "stateIso": "NE" },          "suggestedLocationInfo": { "locationInfo": { "name": "My Business", "city": "Lincoln" } }        }      ]    }  }}

Saran tidak memiliki id. Untuk mengonfirmasinya, Anda membuat id rekaman pencocokan: hasil pengodean base64 dari <MatchRecordType>:<matchedDataDatabaseId>, dengan tipe yang dipilih dari accountType. Untuk Google (GMB), tipenya adalah GmbLocationMatchedData, sehingga rekaman di atas dikodekan menjadi R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=. Facebook (FB) menggunakan FbLocationMatchedData dan Apple (APPLE) menggunakan AppleLocationMatchedData.

Confirm matches

# base64 of GmbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M="] } }'

Responsnya adalah data.confirmConnectMatches dengan success dan failedIds. failedIds memuat nilai matchedDataDatabaseId yang telah didekodekan dan tidak dapat dikonfirmasi, seperti rekaman yang sudah digunakan atau lokasi yang telah diarsipkan sejak pencocokan. id yang dibuat dengan tipe yang salah tidak menghasilkan 400: pemanggilan tersebut mengembalikan 200 dengan success: false dan tanpa failedIds, jadi periksa success setiap kali. Saran yang tidak dikirim tetap tidak berubah.

6. Impor profil bisnis yang belum memiliki lokasi

Pencocokan hanya memasangkan profil bisnis dengan lokasi yang sudah Anda miliki. Untuk mengimpor sisanya, ambil daftar semua profil bisnis yang dapat diakses akun tersebut, lalu buat lokasi dari setiap profil bisnis yang Anda inginkan.

Account listings

curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "perPage": 50 }'

JSON

{  "data": {    "connectedAccountListings": {      "pageInfo": { "hasNextPage": false, "totalRecords": 60 },      "records": [        {          "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==",          "locationName": "Trial",          "address": "123 William St, NY 10038, Manhattan, US",          "liveLink": null        }      ]    }  }}

Sertakan locationInfo dengan istilah pencarian untuk mempersempit hasil dari akun besar berdasarkan nama, alamat, telepon, kode pos, atau kode toko. id pada setiap record adalah connectedAccountListingId yang digunakan oleh dua panggilan berikutnya. Kedua SDK belum menyediakan fungsi untuk create-location-from-listing, sehingga contoh Python dan Node memanggil REST secara langsung dengan header yang sama.

Create from listing

curl -X POST https://listingsapi.com/api/v4/connected-accounts/create-location-from-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'

JSON

{  "data": {    "createLocationFromConnectedAccountListing": { "success": true, "locationId": 88277, "errors": null }  }}

Lokasi dibuat dari data Google (nama, alamat, jam operasional, kategori, telepon, atribut) dan langsung ditautkan ke profil bisnis tersebut. Profil bisnis Google tetap berstatus IN_PROGRESS hingga pembaruan lokasi pertama Anda dipublikasikan ke profil bisnis tersebut. locationId adalah databaseId biasa. Jika gagal, success bernilai false dan errors memuat kode seperti SY81067 (id profil bisnis tidak ditemukan). Field yang digunakan adalah connectedAccountListingId; listingId ditolak oleh skema.

Jika profil bisnis tersebut terkait dengan lokasi yang sudah Anda miliki, tautkan profil bisnis itu alih-alih membuat lokasi duplikat.

Link a listing

curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'

Penautan yang gagal mengembalikan success: false dengan message, misalnya Listing record not found, atau keterangan bahwa profil bisnis tersebut sudah terhubung ke lokasi lain.

7. Hubungkan satu lokasi sebagai alternatif

Jika Anda sudah mengetahui lokasi mana yang akan dihubungkan oleh pemilik, lewati pencocokan dan buat tautan yang terkait dengan lokasi tersebut. Jika berhasil, pemilik kembali ke successUrl Anda, dan kredensial hanya dikaitkan dengan lokasi tersebut.

Single-location link

curl -X POST https://listingsapi.com/api/v4/locations/oauth_connect_url \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}'

Responsnya adalah data.createConnectUrl dengan success, url, dan errors. Tautan hanya dapat digunakan sekali, jadi buat tautan baru untuk setiap percobaan. URL pengalihan yang relatif atau tidak dapat diurai menghasilkan respons success: true dengan null url, jadi periksa url. Key yang tidak diizinkan mengakses lokasi ini menerima respons 403 dengan SY90003.

8. Proses selanjutnya

Setelah profil bisnis ditautkan, baris Google Maps dalam daftar profil bisnis premium lokasi tersebut beralih dari REQUIRING_ACTION, melalui IN_PROGRESS, lalu mencapai status SYNCED dengan listingUrl. Google otomatis ditambahkan sebagai sumber ulasan, sehingga ulasan mulai masuk ke daftar interaksi, dan pembaruan yang Anda buat pada lokasi diterapkan ke profil bisnis.

Jika URL webhook sudah diatur di dasbor, Anda tidak perlu melakukan polling. Setiap payload memuat location_id dan data.connected_account_id.

Peristiwa	Dipicu saat	Tindakan yang perlu dilakukan
`connection.location_connected`	Profil bisnis ditautkan ke lokasi; `data.platform` bernilai `google`.	Tandai lokasi sebagai terhubung di UI Anda.
`connection.reauth_required`	Kredensial akun telah dinyatakan tidak valid. Tidak ada data yang disinkronkan hingga otorisasi diberikan kembali.	Buat tautan baru (langkah 1) dan minta pemilik untuk masuk kembali.
`connection.listing_inaccessible`	Kredensial masih valid, tetapi akses ke satu profil bisnis tersebut telah dicabut.	Minta pemilik untuk memulihkan akses di Google, atau tautkan profil bisnis lain.

Langkah berikutnya

Buat Google Business Profile: untuk lokasi yang tidak memiliki profil bisnis Google untuk dicocokkan.
Hubungkan Halaman Facebook: alur yang sama untuk platform publikasi lain yang menggunakan OAuth.
Periksa status profil bisnis dan tautan aktif dan Ambil ulasan: pantau hasil yang masuk.
Referensi SDK: Akun terhubung di Python dan Akun terhubung di Node.
Referensi: Hubungkan akun Google, Picu pencocokan lokasi, Konfirmasi hasil pencocokan koneksi, Ambil profil bisnis dari akun terhubung, Buat lokasi dari profil bisnis, dan indeks Akun terhubung.