API pendukung

Semua endpoint API Pendukung: contoh cURL, Python, Node; negara dan negara bagian yang didukung, katalog subkategori, dan platform publikasi paket Anda.

Endpoint pendukung menyediakan tiga katalog referensi yang digunakan oleh bagian API lainnya untuk validasi: negara dan negara bagian yang didukung, kategori bisnis yang tersedia, serta direktori platform publikasi yang tercakup dalam paket Anda. Ketiganya hanya dapat dibaca, tidak menggunakan paginasi, dan mengembalikan kumpulan data lengkap, sehingga kunci Read (baca) sudah cukup dan penyimpanan dalam cache lebih penting daripada paginasi.

Ringkasan endpoint

Daftar negara dan negara bagian yang didukung

GET /countries

Mengembalikan katalog lengkap di dalam data.supportedCountries. Setiap negara memuat kode ISO, id dalam format base64, databaseId berupa angka, array states yang setiap entrinya memiliki kode ISO sendiri, serta tiga penanda alamat: hasCity (kota wajib diisi), stateRequired (negara bagian wajib diisi dan divalidasi terhadap states), dan hasPostalCode (negara tersebut menggunakan kode pos). Negara yang tidak dibagi menjadi negara bagian mengembalikan array states kosong.

Parameter

Endpoint ini tidak menerima parameter. Endpoint ini selalu mengembalikan kumpulan data lengkap.

curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "hasCity": true,        "id": "Q291bnRyeToxMw==",        "iso": "AU",        "name": "Australia",        "states": [          { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" },          { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "hasCity": true,        "id": "Q291bnRyeToxNw==",        "iso": "BE",        "name": "Belgium",        "states": []      }    ]  }}

Kedua field iso berisi nilai yang Anda perlukan. iso negara menjadi countryIso saat pembuatan dan pembaruan, sedangkan iso negara bagian menjadi stateIso. Memvalidasi keduanya terhadap daftar ini sebelum operasi tulis mengubah 400 di sisi server menjadi pesan yang jelas dalam formulir Anda sendiri.

Daftar subkategori

GET /sub-categories

Mengembalikan sekitar 6.000 rekaman kategori di dalam data.subcategories dalam satu array tanpa paginasi. Pencarian ini mengubah jenis bisnis yang Anda ketahui sebagai teks bebas menjadi id numerik yang diperlukan oleh operasi tulis lokasi.

Parameter

Tidak ada. Seluruh katalog dikembalikan pada setiap panggilan.

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

Setiap rekaman memuat lima field, dan field yang Anda gunakan bergantung pada tujuan penggunaannya.

Satu lokasi menerima satu kategori utama dalam subCategoryId dan hingga 9 kategori tambahan dalam additionalCategoryIds.

Daftar situs dalam paket

GET /plan-sites

Mengembalikan setiap direktori platform publikasi yang termasuk dalam paket akun Anda, di dalam data.planSites. Inilah daftar acuan resmi untuk id situs numerik, dan hanya id yang tercantum di sini yang valid di bagian API lainnya.

Parameter

Tidak ada. Cakupan respons dibatasi pada paket akun Anda.

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

Kedua array negara menjawab pertanyaan yang berbeda. supportedCountries menunjukkan negara tempat situs menerima profil bisnis, jadi filter berdasarkan countryIso lokasi Anda sebelum menawarkan platform publikasi. hideAddressSupportedCountries menunjukkan negara tempat situs menerapkan pengaturan untuk menyembunyikan alamat, yang dibutuhkan oleh bisnis dengan area layanan. Kedua array dapat memuat 50 kode atau lebih; contoh di atas telah dipersingkat.

Id situs bersifat tetap dan berguna untuk diketahui: 1 adalah Google Maps dan 184 adalah Facebook, dua platform publikasi yang menjadi tujuan sebagian besar alur koneksi.

Tautan tindakan tempat

Tautan tindakan tempat tidak memiliki endpoint tersendiri. Tautan tindakan tempat adalah tombol Google seperti Order online (pesan online), Reserve a table (reservasi meja), dan Book an appointment (buat janji temu), dan platform mengelolanya sebagai field pada lokasi, bukan sebagai resource terpisah. Anda menetapkannya melalui array placeActionLinks saat membuat dan memperbarui lokasi, lalu membacanya kembali melalui endpoint pembacaan lokasi mana pun.

Setiap entri memerlukan placeActionType dan uri, dapat menyertakan flag isPreferred opsional dengan maksimal satu tautan pilihan per jenis, dan menerima action bernilai add atau delete saat diperbarui. Jenis yang valid, aturan penghapusan, dan perilaku sinkronisasi semuanya dijelaskan di Tautan Tindakan Tempat.

Error yang akan Anda temui

Tidak satu pun endpoint ini melakukan operasi tulis, sehingga endpoint ini tidak pernah mengembalikan SY90016 saat Anda menggunakan key Read. Daftar lengkap tersedia di Kode error.

Langkah berikutnya

• Cari negara dan kategori: versi panduan tugas, dengan penjelasan langkah demi langkah tentang peralihan ke pembuatan lokasi.
• Tambahkan lokasi: tempat countryIso dan subCategoryId digunakan.
• Temukan dan perbaiki error profil bisnis: menggunakan plan sites untuk membedakan platform publikasi yang belum ada dari platform publikasi yang mengalami kegagalan.
• Referensi API pendukung untuk daftar lengkap field pada ketiga endpoint.