Listings APIListings API
Oturum aç

Hızlı başlangıç

TypeScript ile Listings API'ye bağlanın, konumlarınızı listeleyin, bir konum oluşturun ve bir yorumu yanıtlayın.

1. API anahtarınızı ayarlayın

Listings API geliştirici kontrol panelinde API anahtarları → Yeni anahtar bölümünden anahtarınızı alın.

bash
export LISTINGSAPI_KEY="your-api-key"

new ListingsAPI(), LISTINGSAPI_KEY değerini ortamdan otomatik olarak okur; isterseniz apiKey değerini açıkça iletebilirsiniz.

2. Konumlarınızı listeleyin

quickstart.ts
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);}
bash
npx tsx quickstart.ts

Beklenen çıktı:

bash
Acme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NYAcme Dental Jersey City -- Jersey City NJ hasNextPage: false

fetchAllLocations, varsayılan olarak locations ve pageInfo içeren bir nesne döndürür. fetchAll: true ilettiğinizde SDK, cursor tabanlı sayfaları otomatik olarak takip eder ve bunun yerine düz bir Location[] döndürür.

TypeScript
const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });if (Array.isArray(all)) {console.log('Total: ' + all.length + ' locations');}

3. Bir konum oluşturun

API; name, city, countryIso, subCategoryId ve en az 200 karakter uzunluğunda bir description gerektirir. Geçerli subCategoryId değerlerini client.fetchSubcategories() üzerinden alın ve her girdinin databaseId değerini kullanın.

TypeScript
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);

Gönderilen veri geçersizse SDK, API HTTP 200 döndürse bile platformun hata girdilerini içeren bir ValidationError fırlatır. Kontrol edilecek bir success bayrağı yoktur.

4. Bir yorumu yanıtlayın

Bir konumun yorumlarını alın, ardından etkileşim kimliğini kullanarak yanıt verin. Sayısal konum kimlikleri her yerde kabul edilir: SDK bunları otomatik olarak base64 ile kodlar.

TypeScript
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. Hataları işleyin

TypeScript
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; 2xx dışındaki yanıtlar, platformun HTTP 200 ile döndürdüğü hata içeren yanıt gövdeleri ve success: false bildiren yazma işlemleri için belirli türlerde hatalar fırlatır. Ayrıca 429 ve 5xx yanıtlarında otomatik olarak yeniden dener. Yeniden deneme yöntemleri ve durum kodlarına ilişkin açıklamalar için Hata işleme bölümüne bakın.

Sonraki adımlar