Listings APIListings API
Accedi

Node SDK

Client TypeScript ufficiale per Listings API, senza dipendenze, con paginazione automatica e definizioni di tipo incluse per Node 18+.

listingsapi-js è il client ufficiale Node.js/TypeScript per Listings API v4. Gestisce sedi, schede nelle directory, recensioni, post, foto e analisi dei profili tramite un unico client con una struttura piatta, con paginazione basata su cursore, codifica automatica degli ID, tentativi automatici integrati ed errori tipizzati.

Installa

bash
npm install listingsapi-js

Autenticati

Ottieni la tua chiave API da Chiavi API → Nuova chiave nella dashboard per sviluppatori di 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

Il costruttore accetta anche baseUrl (valore predefinito https://listingsapi.com), timeout (valore predefinito 240000 ms) e maxRetries (valore predefinito 2). Consulta Configurazione.

Esempio rapido

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

Risorse

Tutti i metodi sono disponibili sull'istanza del client:

MetodiCosa gestiscono
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocationsSedi aziendali: elenco, ricerca, creazione, aggiornamento, archiviazione
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStatsRecensioni: elenco, risposta, modifica e archiviazione delle risposte, impostazioni, dati sulle frasi e sulle analisi
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPostsPost: annunci, eventi e offerte su Google e Facebook
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicateSchede nelle directory: premium, vocali, duplicati
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsAnalisi dei profili Google, Bing e Facebook
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatusFoto delle sedi
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingConnessioni OAuth a Google e Facebook, link alle schede
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategoriesDirectory del piano, paesi supportati, abbonamenti, categorie aziendali

Questo SDK non include ancora metodi per la Social API — marchi, account social collegati e post su Facebook, Instagram, X, LinkedIn e Pinterest; chiamala direttamente seguendo la documentazione di riferimento REST della Social API.

Paginazione

I metodi che restituiscono elenchi supportano la paginazione basata su cursore.

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 e fetchInteractions seguono lo stesso schema: un oggetto pagina per impostazione predefinita, un array piatto con fetchAll: true.

Codifica degli ID

Puoi passare ID numerici delle sedi ovunque: l'SDK li codifica automaticamente in base64. Gli ID già codificati vengono accettati senza modifiche e la funzione di codifica viene esportata se hai bisogno di usarla direttamente.

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

Gestione degli errori

Ogni errore dell'SDK deriva da ListingsAPIError. Gli errori dell'API generano APIError o una delle sue sottoclassi, sia quando la piattaforma li segnala tramite un codice di stato HTTP sia quando li include nel corpo di una risposta HTTP 200 (i token non validi e gli errori di validazione delle operazioni di scrittura vengono restituiti come payload errors[] e le operazioni di scrittura possono segnalare success: false). L'SDK genera un'eccezione in tutti questi casi, quindi non devi mai controllare i flag success direttamente. Gli errori di rete generano APIConnectionError.

ClasseGenerata per
AuthenticationError401 o payload di errore per token non validi
PermissionDeniedError403 o payload di errore relativi ai permessi
NotFoundError404
ValidationError400/422 o operazioni di scrittura che restituiscono success: false / errors[]
RateLimitError429, contiene retryAfter in secondi
InternalServerError5xx
APIConnectionErrorErrore di rete, nulla ha raggiunto l'API

Ogni APIError contiene statusCode, responseBody, code (il primo codice di errore della piattaforma, e.g. "SY10005") e errors (ogni voce normalizzata nel formato { 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 }, ...]}}

Il client ripete automaticamente le richieste che ricevono risposte 429 e 5xx (2 tentativi per impostazione predefinita, rispettando Retry-After). Consulta Gestione degli errori per gli schemi di ripetizione dei tentativi e le indicazioni sui codici di stato.

Passaggi successivi