Cari negara, negara bagian, dan kategori

Cek negara dan kode negara bagian yang didukung, cari ID numerik kategori bisnis, dan lihat platform publikasi paket Anda sebelum membuat lokasi.

Untuk membuat lokasi, diperlukan tiga nilai yang harus diperoleh dari API: countryIso dan stateIso yang diterima API, subCategoryId numerik, dan, jika Anda ingin membatasi platform publikasi, id situs dalam paket Anda. Tiga endpoint katalog menyediakan nilai-nilai tersebut. Ketiganya mengembalikan array biasa tanpa paginasi.

1. Tampilkan daftar negara dan kode negara bagian

GET /countries mengembalikan setiap negara yang didukung beserta kode ISO, flag hasCity, dan array states negara tersebut. Nilai iso digunakan untuk mengisi countryIso dan stateIso saat pembuatan dan pembaruan. Python SDK menyediakannya sebagai client.countries() dan Node SDK sebagai client.fetchCountries().

Countries

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

JSON

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

hasCity: true berarti city wajib disertakan saat pembuatan; dengan false, kota yang Anda kirim akan diabaikan. stateRequired: true berarti stateIso wajib disertakan dan harus berupa salah satu states negara tersebut; dengan false, jangan sertakan nilai tersebut. hasPostalCode: true berarti negara tersebut menggunakan kode pos, jadi kirimkan postalCode bersama alamat. Endpoint negara menjelaskan setiap flag.

2. Temukan id kategori

GET /sub-categories mengembalikan katalog kategori lengkap. Nilai yang Anda kirim sebagai subCategoryId adalah databaseId, yaitu bilangan bulat, bukan id dalam base64. Misalnya, kategori restoran adalah 1432. Filter daftar berdasarkan nama dalam kode Anda sendiri; tidak ada parameter pencarian di sisi server.

Find a category

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'

JSON

{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}

Field	Kegunaan
`databaseId`	Bilangan bulat yang dikirim sebagai `subCategoryId`, atau di dalam `additionalCategoryIds` untuk maksimal 9 kategori sekunder.
`name`	Label yang mudah dibaca manusia untuk ditampilkan dalam pemilih dan digunakan sebagai acuan pencocokan.
`key`	Slug nama yang sesuai untuk URL dan tetap sama meskipun namanya diubah.
`primary`	Menunjukkan apakah kategori tersebut boleh menjadi subkategori utama suatu lokasi. Hanya pilih entri `true` untuk `subCategoryId`.

3. Lihat platform publikasi yang tercakup dalam paket Anda

GET /plan-sites mencantumkan setiap platform publikasi dalam paket Anda beserta id numerik, url, negara yang diterimanya, dan negara tempat platform tersebut menerapkan hideAddress. Hanya id ini yang merupakan nilai valid untuk enabledSiteIds saat pembuatan dan submissionDisabledSiteIds saat pembaruan. Filter berdasarkan negara lokasi agar Anda hanya menawarkan platform publikasi yang akan menerima lokasi tersebut.

Plan sites

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'

JSON

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

Kedua array negara dipotong di sini; respons langsung dapat mencantumkan 50 kode atau lebih per situs. Untuk bisnis dengan area layanan, periksa juga hideAddressSupportedCountries, karena platform publikasi yang menerima negara tersebut mungkin tetap menolak profil bisnis tanpa alamat jalan.

4. Simpan hasil pencarian ini dalam cache

Ketiga katalog jarang berubah dan tidak menggunakan paginasi, jadi ambil masing-masing sekali saat aplikasi mulai berjalan, simpan dalam memori atau tabel kecil, dan perbarui secara terjadwal. Memanggil endpoint tersebut langsung pada setiap pembuatan menghabiskan kuota batas laju permintaan tanpa mengembalikan data baru; pada paket Launch, panggilan tersebut menggunakan 3 dari jatah 10 permintaan per menit Anda.

Katalog	Ukuran	Waktu pembaruan
Negara	Puluhan negara, ratusan negara bagian	Jarang. Sekali sehari sudah lebih dari cukup.
Subkategori	Sekitar 6.000 entri	Setiap hari, atau ketika pembuatan gagal karena `subCategoryId` tidak dikenal.
Situs dalam paket	Puluhan platform publikasi	Saat paket berubah, karena daftar ini terbatas pada paket Anda.

Buat pemetaan name dalam huruf kecil ke databaseId untuk subkategori dan pemetaan countryIso ke states untuk negara. Validasi alamat menggunakan cache sebelum Anda memanggil operasi pembuatan, agar countryIso yang tidak didukung (SY10036) atau city yang tidak disertakan (SY10126) terdeteksi di aplikasi Anda sebelum permintaan dikirim.

Langkah berikutnya

Tambahkan lokasi: gunakan subCategoryId, countryIso, dan ID situs yang baru saja Anda cari.
Perbarui lokasi: ubah kategori atau kecualikan platform publikasi dengan submissionDisabledSiteIds.
Daftar negara dan negara bagian yang didukung, Daftar subkategori, dan Daftar situs paket: halaman referensi.