Listings APIListings API
Se connecter

Démarrage rapide

Connectez-vous à Listings API, listez vos établissements, créez un établissement et répondez à un avis en TypeScript.

1. Configurez votre clé API

Obtenez votre clé dans Clés API → Nouvelle clé dans le tableau de bord développeur de Listings API.

bash
export LISTINGSAPI_KEY="your-api-key"

new ListingsAPI() lit automatiquement LISTINGSAPI_KEY dans l’environnement, ou vous pouvez fournir apiKey explicitement.

2. Listez vos établissements

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

Résultat attendu :

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

fetchAllLocations renvoie par défaut un objet contenant locations et pageInfo. Si vous fournissez fetchAll: true, le SDK parcourt automatiquement les pages à l’aide des curseurs et renvoie à la place un Location[] à un seul niveau.

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

3. Créez un établissement

L’API exige name, city, countryIso, subCategoryId et un description d’au moins 200 caractères. Obtenez les valeurs valides de subCategoryId à partir de client.fetchSubcategories() et utilisez le databaseId de chaque entrée.

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

Si les données envoyées sont invalides, le SDK lève une exception ValidationError contenant les entrées d’erreur de la plateforme, même lorsque l’API renvoie HTTP 200. Il n’y a aucun indicateur success à vérifier.

4. Répondez à un avis

Récupérez les avis d’un établissement, puis répondez à l’aide de l’ID d’interaction. Les ID numériques d’établissement sont acceptés partout : le SDK les encode automatiquement en 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. Gérez les erreurs

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

Le SDK lève des exceptions typées pour les réponses dont le code HTTP n’est pas 2xx, pour les données d’erreur que la plateforme renvoie avec HTTP 200 et pour les opérations d’écriture signalant success: false. Il relance aussi automatiquement les requêtes ayant reçu une réponse 429 ou 5xx. Consultez Gestion des erreurs pour connaître les stratégies de nouvelle tentative et les recommandations relatives aux codes d’état.

Étapes suivantes