Listings APIListings API
Masuk

Tambahkan lokasi

Buat lokasi dengan kolom yang dibutuhkan platform publikasi, tangani kesalahan validasi, dan pastikan lokasi tersebut telah masuk antrean pengiriman.

Profil bisnis, ulasan, postingan, dan analitik semuanya dikaitkan dengan ID lokasi. POST /api/v4/locations membuat lokasi dan memasukkan satu profil bisnis ke antrean untuk setiap platform publikasi dalam paket Anda.

1. Kumpulkan kolom yang wajib diisi

Ada 10 kolom yang wajib diisi. Bisnis dengan area layanan juga mengirimkan alamat lengkap: dengan hideAddress: true, ListingsAPI menyimpan alamat tersebut tetapi tidak mengirimkannya ke platform publikasi. Platform publikasi menampilkan kolom opsional yang tidak disertakan sebagai kolom kosong, jadi kirimkan semua informasi yang Anda miliki.

KolomWajibCatatan
nameYa2 hingga 150 karakter.
descriptionYaMinimal 200 karakter (SY10005).
countryIsoYaKode 2 huruf untuk negara yang didukung (SY10036).
cityYaWajib jika hasCity negara tersebut bernilai true (SY10126). Jika nilainya false, kota yang Anda kirimkan akan diabaikan.
subCategoryIdYadatabaseId numerik dari daftar subkategori.
streetYa5 hingga 100 karakter (SY10011).
stateIsoYaWajib jika stateRequired negara tersebut bernilai true, dan harus berupa salah satu states negara tersebut (SY10010). Jangan sertakan jika stateRequired bernilai false.
postalCodeTidakOpsional, tetapi kirimkan jika hasPostalCode negara tersebut bernilai true. Nilai yang Anda kirimkan harus sesuai dengan format negara tersebut (SY10014).
phoneYaDivalidasi berdasarkan negara (SY10015).
bizUrlYaDipublikasikan sebagai situs web. Beberapa platform publikasi menolak profil bisnis tanpa situs web.
storeIdTidakKode toko Anda sendiri, yang unik di seluruh akun. Gunakan kode ini untuk menemukan kembali lokasi tanpa menyimpan ID kami.
businessHoursTidakSatu entri untuk setiap hari dalam seminggu. Lihat Perbarui lokasi untuk formatnya.

2. Buat lokasi

POST /api/v4/locations menerima kolom dalam objek input di dalam isi permintaan JSON. Metode Python SDK locations.add() menerima kolom yang sama sebagai argumen kata kunci dan memvalidasi kolom wajib sebelum mengirimkan permintaan. Metode Node SDK createLocation() menerima objek camelCase secara langsung.

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "storeId": "ACME-NYC-001",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

3. Baca respons

Pembuatan yang berhasil mengembalikan success: true dan lokasi baru dalam data.createLocation.location. Simpan kedua pengenal: id adalah nilai base64 yang digunakan setiap operasi tulis berikutnya, dan databaseId adalah nilai numerik yang ditampilkan di dasbor dan payload webhook.

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

status bernilai PENDING selama lokasi divalidasi dan dimasukkan ke antrean. Nilainya beralih ke tahap berikutnya tanpa panggilan API tambahan.

4. Tangani kesalahan validasi

Pembuatan dapat gagal pada 2 tahap. Permintaan dengan format yang salah atau kunci yang tidak valid mengembalikan 4xx dengan array errors di tingkat teratas. Permintaan dengan format yang benar tetapi memiliki kolom yang ditolak API mengembalikan 200 dengan success: false dan masalahnya di dalam data.createLocation.errors, jadi periksa isi respons setiap operasi tulis, bukan hanya kode statusnya.

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

Kedua SDK memunculkan pengecualian saat terjadi kegagalan. locations.add() pada Python memeriksa kolom wajib secara lokal dan memunculkan ValidationError sebelum mengirimkan permintaan. createLocation() pada Node memunculkan ValidationError ketika API menolak masukan, sehingga contoh di atas tidak memeriksa penanda keberhasilan.

Kode yang paling sering Anda temui:

KodePenyebabPerbaikan
SY10005Deskripsi tidak disertakan atau panjangnya kurang dari 200 karakter.Tulis deskripsi yang lebih lengkap.
SY10011street tidak disertakan atau panjangnya kurang dari 5 karakter.Kirimkan street.
SY10010stateIso tidak disertakan atau tidak valid untuk negara tersebut.Kirimkan kode negara bagian dari endpoint negara.
SY10036countryIso bukan negara yang didukung.Gunakan kode dari endpoint negara.
SY10126city tidak disertakan untuk negara yang mewajibkannya.Kirimkan city.
SY90016Kunci tersebut hanya memiliki akses Read.Gunakan kunci Write.

5. Pastikan pengiriman telah dimulai

Pembuatan lokasi memasukkan satu profil bisnis untuk setiap platform publikasi dalam paket Anda ke antrean. Setiap profil bisnis dimulai dengan status AVAILABLE atau IN_PROGRESS dan beralih ke SYNCED beserta listingUrl setelah platform publikasi menerimanya.

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

Jika webhook telah dikonfigurasi, polling tidak diperlukan. Peristiwa profile.created dipicu saat catatan sudah ada, dan peristiwa listing.submission dipicu untuk setiap platform publikasi saat statusnya berubah.

Langkah selanjutnya