Panduan mulai cepat
Hubungkan ke Listings API, tampilkan daftar lokasi Anda, buat lokasi, dan balas ulasan menggunakan TypeScript.
1. Atur kunci API Anda
Dapatkan kunci Anda dari Kunci API → Kunci baru di dasbor pengembang Listings API.
export LISTINGSAPI_KEY="your-api-key"new ListingsAPI() membaca LISTINGSAPI_KEY dari variabel lingkungan secara otomatis, atau Anda dapat meneruskan apiKey secara eksplisit.
2. Tampilkan daftar lokasi Anda
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); const result = await client.fetchAllLocations({ first: 5 });if (!Array.isArray(result)) {for (const location of result.locations) { console.log(location.name, '--', location.city, location.stateIso);}console.log('\nhasNextPage:', result.pageInfo.hasNextPage);}npx tsx quickstart.tsKeluaran yang diharapkan:
Acme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NYAcme Dental Jersey City -- Jersey City NJ hasNextPage: falseSecara default, fetchAllLocations mengembalikan objek dengan locations dan pageInfo. Teruskan fetchAll: true agar SDK menelusuri halaman berdasarkan kursor secara otomatis dan mengembalikan Location[] tanpa struktur bertingkat sebagai gantinya.
const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });if (Array.isArray(all)) {console.log('Total: ' + all.length + ' locations');}3. Buat lokasi
API mewajibkan name, city, countryIso, subCategoryId, dan description dengan panjang minimal 200 karakter. Dapatkan nilai subCategoryId yang valid dari client.fetchSubcategories() dan gunakan databaseId dari setiap entri.
const created = await client.createLocation({name: 'Acme Dental',storeId: 'ACME-NYC-001',street: '123 Jump Street',city: 'New York',stateIso: 'NY',postalCode: '10013',countryIso: 'US',phone: '6443859313',subCategoryId: 1432,description: 'Acme Dental is a family-owned dental practice serving downtown New York since 2009. ' + 'Our team provides preventive checkups, cosmetic dentistry, orthodontics, and emergency care, ' + 'with same-day appointments, transparent pricing, and a patient-first approach on every visit.',});console.log(created);Jika payload tidak valid, SDK melempar ValidationError yang memuat entri kesalahan dari platform, bahkan ketika API mengembalikan HTTP 200. Tidak ada penanda success yang perlu diperiksa.
4. Balas ulasan
Ambil ulasan untuk suatu lokasi, lalu balas menggunakan ID interaksi. ID lokasi numerik diterima di semua bagian SDK: SDK secara otomatis mengodekannya dalam base64.
const reviews = await client.fetchInteractions(16808, {startDate: '2026-01-01',endDate: '2026-06-30',first: 10,}); if (!Array.isArray(reviews)) {const unanswered = reviews.interactions.find( (review) => (review.responses ?? []).length === 0,);if (unanswered) { console.log(unanswered.rating, unanswered.content?.slice(0, 80)); await client.respondToReview( unanswered.id, 'Thank you for the kind words! We look forward to seeing you at your next visit.', );}}5. Tangani kesalahan
import { ListingsAPI, APIError, AuthenticationError } from 'listingsapi-js'; const client = new ListingsAPI({ apiKey: 'bad-key' }); try {await client.fetchAllLocations();} catch (error) {if (error instanceof AuthenticationError) { console.log('Invalid API key. Check LISTINGSAPI_KEY.');} else if (error instanceof APIError) { console.log('Status:', error.statusCode); // can be 200 for payload-level errors console.log('Code:', error.code); // first platform code, e.g. 'SY10005' console.log('Errors:', error.errors); // [{ code, message, context }, ...]}}SDK melempar kesalahan dengan tipe tertentu untuk respons non-2xx, payload kesalahan yang dikembalikan platform dengan HTTP 200, dan operasi penulisan yang melaporkan success: false. SDK juga secara otomatis mencoba ulang permintaan yang menghasilkan respons 429 dan 5xx. Lihat Penanganan kesalahan untuk pola percobaan ulang dan panduan kode status.
Langkah berikutnya
- Konfigurasi: penggantian URL dasar dan penyiapan proyek TypeScript
- Kasus penggunaan: 10 panduan penerapan dari awal hingga akhir
- Lokasi: buat, perbarui, cari, arsipkan