Listings APIListings API
Anmelden

Node SDK

Offizieller TypeScript-Client für Listings API ohne Abhängigkeiten, mit automatischer Paginierung und integrierten Typdefinitionen für Node 18+.

listingsapi-js ist der offizielle Node.js/TypeScript-Client für Listings API v4. Er verwaltet Standorte, Verzeichniseinträge, Bewertungen, Beiträge, Fotos und Profilanalysen über einen einzigen Client mit flacher Struktur und bietet standardmäßig cursorbasierte Paginierung, automatische ID-Kodierung, integrierte Wiederholungsversuche und typisierte Fehler.

Installieren

bash
npm install listingsapi-js

Authentifizieren

Erstellen Sie Ihren API-Schlüssel unter API Keys → New key im Listings API-Entwickler-Dashboard.

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

Der Konstruktor akzeptiert außerdem baseUrl (Standardwert https://listingsapi.com), timeout (Standardwert 240000 ms) und maxRetries (Standardwert 2). Siehe Konfiguration.

Kurzes Beispiel

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

Ressourcen

Alle Methoden sind auf der Client-Instanz verfügbar:

MethodenVerwaltete Daten und Funktionen
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocationsUnternehmensstandorte: auflisten, suchen, erstellen, aktualisieren, archivieren
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStatsBewertungen: auflisten, beantworten, Antworten bearbeiten und archivieren, Einstellungen, Phrasen- und Analysedaten
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPostsBeiträge: Ankündigungen, Veranstaltungen und Angebote auf Google und Facebook
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicateVerzeichniseinträge: Premium, Sprachsuche, Duplikate
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsProfilanalysen für Google, Bing und Facebook
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatusStandortfotos
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingOAuth-Verbindungen zu Google und Facebook, Links zu Einträgen
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategoriesIm Tarif enthaltene Verzeichnisse, unterstützte Länder, Abonnements, Unternehmenskategorien

Die Social API – Marken, verbundene Social-Media-Konten und Beiträge auf Facebook, Instagram, X, LinkedIn und Pinterest – wird von diesem SDK noch nicht unterstützt; rufen Sie sie direkt gemäß der Social REST-Referenz auf.

Paginierung

Methoden, die Listen zurückgeben, unterstützen cursorbasierte Paginierung.

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 und fetchInteractions folgen demselben Muster: standardmäßig ein Seitenobjekt, mit fetchAll: true ein flaches Array.

ID-Kodierung

Sie können überall numerische Standort-IDs übergeben: Das SDK kodiert sie automatisch mit Base64. Bereits kodierte IDs werden unverändert akzeptiert, und die Kodierungsfunktion wird exportiert, falls Sie sie selbst benötigen.

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

Fehlerbehandlung

Jeder SDK-Fehler ist von ListingsAPIError abgeleitet. Bei API-Fehlern wird APIError oder eine seiner Unterklassen ausgelöst, unabhängig davon, ob die Plattform sie als HTTP-Status oder im Body einer HTTP-200-Antwort meldet (ungültige Tokens und die Validierung von Schreibvorgängen werden als errors[]-Payloads übermittelt, und Schreibvorgänge können success: false melden). Das SDK löst in all diesen Fällen eine Ausnahme aus, sodass Sie success-Flags nie selbst prüfen müssen. Bei Netzwerkfehlern wird APIConnectionError ausgelöst.

KlasseAusgelöst bei
AuthenticationError401 oder Fehler-Payloads für ungültige Tokens
PermissionDeniedError403 oder Fehler-Payloads für fehlende Berechtigungen
NotFoundError404
ValidationError400/422 oder Schreibvorgängen, die success: false / errors[] zurückgeben
RateLimitError429, enthält retryAfter in Sekunden
InternalServerError5xx
APIConnectionErrorNetzwerkfehler, die API wurde nicht erreicht

Jede Instanz von APIError enthält statusCode, responseBody, code (den ersten Plattformfehlercode, e.g. "SY10005") und errors (jeder Eintrag auf { code, message, context } normalisiert).

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

Bei 429- und 5xx-Antworten wiederholt der Client die Anfrage automatisch (standardmäßig 2 Versuche, unter Berücksichtigung von Retry-After). Beispiele für Wiederholungsversuche und Hinweise zu Statuscodes finden Sie unter Fehlerbehandlung.

Nächste Schritte