Listings APIListings API
Se connecter

Node SDK

Client TypeScript officiel pour Listings API, sans dépendances, avec pagination automatique et définitions de types incluses pour Node 18+.

listingsapi-js est le client Node.js/TypeScript officiel pour Listings API v4. Il gère les établissements, les fiches d’annuaire, les avis, les publications, les photos et les données d’analyse des profils depuis un client unique à interface plate, avec pagination par curseur, encodage automatique des identifiants, nouvelles tentatives intégrées et erreurs typées disponibles par défaut.

Installation

bash
npm install listingsapi-js

Authentification

Obtenez votre clé API dans API Keys → New key dans le tableau de bord développeur de Listings API.

TypeScript
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI();                              // reads LISTINGSAPI_KEY from envconst explicit = new ListingsAPI({ apiKey: 'your-api-key' });  // or pass it directly

Le constructeur accepte également baseUrl (par défaut : https://listingsapi.com), timeout (par défaut : 240000 ms) et maxRetries (par défaut : 2). Consultez Configuration.

Exemple rapide

list_locations.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);}}

Ressources

Toutes les méthodes sont disponibles sur l’instance du client :

MéthodesÉléments gérés
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocationsÉtablissements : liste, recherche, création, mise à jour, archivage
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStatsAvis : liste, réponse, modification et archivage des réponses, paramètres, données sur les expressions et données d’analyse
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPostsPublications : annonces, événements et offres sur Google et Facebook
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicateFiches d’annuaire : premium, recherche vocale, doublons
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsDonnées d’analyse des profils Google, Bing et Facebook
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatusPhotos des établissements
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingConnexions OAuth à Google et Facebook, liens des fiches
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategoriesAnnuaires inclus dans l’abonnement, pays pris en charge, abonnements, catégories d’activité

La Social API — marques, comptes de réseaux sociaux connectés et publications sur Facebook, Instagram, X, LinkedIn et Pinterest — n’est pas encore prise en charge par ce SDK ; appelez-la directement en vous référant à la référence REST de la Social API.

Pagination

Les méthodes qui renvoient des listes prennent en charge la pagination par curseur.

TypeScript
// Single pageconst page = await client.fetchAllLocations({ first: 25 });if (!Array.isArray(page)) {console.log(page.locations);   // Location[]console.log(page.pageInfo);    // { hasNextPage, hasPreviousPage, startCursor, endCursor } // Next pageif (page.pageInfo.hasNextPage) {  const next = await client.fetchAllLocations({    first: 25,    after: page.pageInfo.endCursor!,  });}} // Auto-paginate: returns a flat Location[]const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });

searchLocations et fetchInteractions suivent le même principe : un objet page par défaut, un tableau à une seule dimension avec fetchAll: true.

Encodage des identifiants

Vous pouvez passer des identifiants numériques d’établissement partout où un identifiant est attendu : le SDK les encode automatiquement en base64. Les identifiants déjà encodés sont acceptés tels quels, et l’encodeur est exporté si vous avez besoin de l’utiliser directement.

TypeScript
import { encodeLocationId } from 'listingsapi-js'; // These are equivalentawait client.fetchPremiumListings(16808);await client.fetchPremiumListings('TG9jYXRpb246MTY4MDg='); encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='

Gestion des erreurs

Chaque erreur du SDK dérive de ListingsAPIError. Les échecs de l’API lèvent APIError ou l’une de ses sous-classes, que la plateforme les signale par un code de statut HTTP ou dans le corps d’une réponse HTTP 200 (les jetons non valides et la validation des écritures sont signalés dans des charges utiles errors[], et les écritures peuvent signaler success: false). Le SDK lève une exception dans tous ces cas, ce qui vous évite d’inspecter vous-même les indicateurs success. Les échecs réseau lèvent APIConnectionError.

ClasseLevée pour
AuthenticationError401, ou charges utiles d’erreur signalant un jeton non valide
PermissionDeniedError403, ou charges utiles d’erreur d’autorisation
NotFoundError404
ValidationError400/422, ou écritures renvoyant success: false / errors[]
RateLimitError429, contient retryAfter en secondes
InternalServerError5xx
APIConnectionErrorÉchec réseau, aucune requête n’a atteint l’API

Chaque APIError contient statusCode, responseBody, code (le premier code d’erreur de la plateforme, e.g. "SY10005") et errors (chaque entrée étant normalisée au format { code, message, context }).

TypeScript
import { ListingsAPI, APIError, RateLimitError } from 'listingsapi-js'; const client = new ListingsAPI(); try {await client.fetchAllLocations();} catch (error) {if (error instanceof RateLimitError) {  console.log(error.retryAfter);       // seconds to wait} else if (error instanceof APIError) {  console.log(error.statusCode);       // 401, 404, 500, or 200 for payload-level errors  console.log(error.code);             // first platform code, e.g. 'SY10005'  console.log(error.errors);           // [{ code, message, context }, ...]}}

Le client réessaie automatiquement les requêtes ayant reçu une réponse 429 ou 5xx (2 tentatives par défaut, en respectant Retry-After). Consultez Gestion des erreurs pour des exemples de stratégies de nouvelle tentative et des indications sur les codes de statut.

Étapes suivantes