Guida rapida

Connettiti a Listings API, elenca le tue sedi, crea una sede e rispondi a una recensione in TypeScript.

1. Imposta la tua chiave API

Ottieni la tua chiave da Chiavi API → Nuova chiave nella dashboard per sviluppatori di Listings API.

bash

export LISTINGSAPI_KEY="your-api-key"

new ListingsAPI() legge automaticamente LISTINGSAPI_KEY dall'ambiente, oppure puoi passare apiKey esplicitamente.

2. Elenca le tue sedi

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

Output previsto:

bash

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

Per impostazione predefinita, fetchAllLocations restituisce un oggetto con locations e pageInfo. Passa fetchAll: true e l'SDK scorrerà automaticamente le pagine tramite cursore, restituendo invece un Location[] non annidato.

TypeScript

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

3. Crea una sede

L'API richiede name, city, countryIso, subCategoryId e un valore di almeno 200 caratteri per description. Ottieni i valori validi di subCategoryId da client.fetchSubcategories() e usa il campo databaseId di ciascuna voce.

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

Se il payload non è valido, l'SDK genera un'eccezione ValidationError contenente le voci di errore della piattaforma, anche quando l'API restituisce HTTP 200. Non esiste un flag success da controllare.

4. Rispondi a una recensione

Recupera le recensioni di una sede, poi rispondi usando l'ID dell'interazione. Gli ID numerici delle sedi sono accettati ovunque: l'SDK li codifica automaticamente in base64.

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. Gestisci gli errori

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 }, ...]}}

L'SDK genera errori tipizzati per le risposte non 2xx, per i payload di errore che la piattaforma restituisce con HTTP 200 e per le operazioni di scrittura che segnalano success: false. Inoltre, riprova automaticamente le richieste che ricevono risposte 429 e 5xx. Consulta Gestione degli errori per le modalità di ripetizione dei tentativi e le indicazioni sui codici di stato.

Passaggi successivi

Configurazione: personalizzazione dell'URL di base e configurazione del progetto TypeScript
Casi d'uso: dieci procedure complete
Sedi: creazione, aggiornamento, ricerca, archiviazione