Bewertungen

Rufen Sie Bewertungen mit dem listingsapi-js SDK ab, beantworten und analysieren Sie sie.

Bewertungen (in der API als „interactions“ bezeichnet) sind Sternebewertungen und Freitextfeedback, die von Google, Facebook und Yelp erfasst werden. Alle Bewertungsmethoden sind auf der Clientinstanz ListingsAPI verfügbar. Schreibvorgänge, die serverseitig fehlschlagen, lösen ValidationError aus, sodass Sie niemals die success-Flags der Rückgabewerte prüfen müssen.

fetchInteractions

Rufen Sie Bewertungen für einen Standort mit optionalen Filtern und cursorbasierter Paginierung ab. Numerische Standort-IDs werden automatisch kodiert.

TypeScript

// Single pageconst result = await client.fetchInteractions(16808, {first:         25,startDate:     '2026-01-01',endDate:       '2026-06-30',ratingFilters: [1, 2],}); if (!Array.isArray(result)) {console.log(result.interactions);   // Interaction[]console.log(result.totalCount);     // number | undefinedconsole.log(result.pageInfo);       // { hasNextPage, hasPreviousPage, startCursor, endCursor }} // All reviews at once, returns a flat Interaction[]const all = await client.fetchInteractions(16808, {fetchAll:  true,startDate: '2026-01-01',});

Optionen

Parameter	Typ	Beschreibung
`first`	`number`	Seitengröße für die Vorwärtspaginierung.
`after`	`string`	Cursor aus einem vorherigen `pageInfo.endCursor`.
`before`	`string`	Cursor für die Rückwärtspaginierung.
`last`	`number`	Seitengröße für die Rückwärtspaginierung.
`fetchAll`	`boolean`	Automatisch paginieren und ein flaches `Interaction[]` zurückgeben.
`pageSize`	`number`	Intern verwendete Seitengröße, wenn `fetchAll` auf `true` gesetzt ist (Standard: `100`).
`startDate`	`string`	Untergrenze, `YYYY-MM-DD`.
`endDate`	`string`	Obergrenze, `YYYY-MM-DD`.
`category`	`string`	Filter nach Interaktionskategorie.
`siteUrls`	`string[]`	Auf bestimmte Verzeichnisse beschränken, e.g. `['maps.google.com']`.
`ratingFilters`	`number[]`	Zu berücksichtigende Sternebewertungen, e.g. `[1, 2]`.

Rückgabewerte

Ohne fetchAll ein InteractionResponse-Objekt: success, interactions (Interaction[]), pageInfo (hasNextPage, hasPreviousPage, startCursor, endCursor), totalCount, sofern von der API gemeldet, und raw (die ungeparsten Nutzdaten). Mit fetchAll: true ein flaches Interaction[]. Jedes Interaction enthält id, content, rating, siteName, siteUrl, reviewerName, publishedAt, category und responses.

fetchReviewDetails

Rufen Sie anhand der Interaktions-ID detaillierte Informationen zu bestimmten Bewertungen ab. Bei einem leeren Eingabearray wird die Verarbeitung sofort beendet und ein leeres Objekt ohne Netzwerkaufruf zurückgegeben.

TypeScript

const details = await client.fetchReviewDetails(['interaction-uuid-1','interaction-uuid-2',]);

respondToReview

Veröffentlichen Sie eine Antwort auf eine Bewertung. Die Übermittlung an das Quellverzeichnis erfolgt asynchron.

TypeScript

await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);

Parameter	Typ	Beschreibung
`interactionId`	`string`	Die Interaktions-ID der Bewertung.
`responseContent`	`string`	Zu veröffentlichender Antworttext.

editReviewResponse

Bearbeiten Sie eine vorhandene Antwort.

TypeScript

await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);

Parameter	Typ	Beschreibung
`reviewId`	`string`	Die Bewertung, zu der die Antwort gehört.
`responseId`	`string`	Die zu bearbeitende Antwort.
`responseContent`	`string`	Neuer Antworttext.

archiveReviewResponse

Archivieren Sie eine Antwort (blenden Sie sie aus).

TypeScript

await client.archiveReviewResponse('response-uuid');

Bewertungsanalysen

Alle drei Analysemethoden akzeptieren eine Standort-ID sowie einen optionalen { startDate, endDate }-Bereich (YYYY-MM-DD) und geben ein ReviewAnalytics-Objekt zurück, dessen Struktur je nach Endpunkt variiert.

fetchReviewAnalyticsOverview

Gesamtstatistiken für einen Datumsbereich: aggregierte Sternebewertungen und Bewertungsanzahlen für den Standort.

TypeScript

const overview = await client.fetchReviewAnalyticsOverview(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});console.log(overview);

fetchReviewAnalyticsTimeline

Anzahl der Bewertungen und Sternebewertungen im Zeitverlauf, geeignet für die Darstellung in Diagrammen.

TypeScript

const timeline = await client.fetchReviewAnalyticsTimeline(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});

fetchReviewAnalyticsSitesStats

Aufschlüsselung der Bewertungen nach Quellwebsite (Google, Facebook, Yelp).

TypeScript

const siteStats = await client.fetchReviewAnalyticsSitesStats(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});

fetchReviewPhrases

Analyse von Formulierungen und Stimmungen für einen oder mehrere Standorte innerhalb eines Datumsbereichs. Akzeptiert ein einzelnes Optionsobjekt; locationIds ist erforderlich, und bei einer leeren Liste wird [] ohne Netzwerkaufruf zurückgegeben.

TypeScript

const phrases = await client.fetchReviewPhrases({locationIds: ['TG9jYXRpb246MTY4MDg=', 'TG9jYXRpb246MTY4MDk='],startDate:   '2026-01-01',endDate:     '2026-06-30',siteUrls:    ['maps.google.com'],}); for (const p of phrases) {console.log(p.phrase, p.count, p.sentiment);}

Optionen

Parameter	Typ	Erforderlich	Beschreibung
`locationIds`	`string[]`	Ja	Base64-kodierte Standort-IDs.
`startDate`	`string`	Nein	Untergrenze, `YYYY-MM-DD`.
`endDate`	`string`	Nein	Obergrenze, `YYYY-MM-DD`.
`siteUrls`	`string[]`	Nein	Auf bestimmte Verzeichnisse beschränken.

Bewertungseinstellungen

fetchReviewSettings

Rufen Sie die Einstellungen für Bewertungsquellen eines Standorts ab.

TypeScript

const settings = await client.fetchReviewSettings(16808);console.log(settings);

editReviewSettings

Legen Sie die URLs der Bewertungsquellen fest, die für einen Standort überwacht werden, oder aktualisieren Sie sie. Jeder Eintrag ist ein ReviewSiteUrl mit einem name und einem url.

TypeScript

await client.editReviewSettings(16808, [{ name: 'Google', url: 'https://www.google.com/maps/place/acme-dental' },{ name: 'Yelp',   url: 'https://www.yelp.com/biz/acme-dental-new-york' },]);

Parameter	Typ	Beschreibung
`locationId`	`string \| number`	Numerische IDs werden automatisch kodiert.
`siteUrls`	`ReviewSiteUrl[]`	Einträge vom Typ `{ name, url }` pro Bewertungsquelle.

fetchReviewSiteConfig

Rufen Sie die kontoweite Liste der zulässigen Bewertungsquellen ab. Akzeptiert keine Argumente und gibt ein ReviewSiteConfig[] zurück.

TypeScript

const config = await client.fetchReviewSiteConfig();

Standorte: Standort-IDs nachschlagen
Analysen: Profilanalysen für Google, Bing und Facebook
Anwendungsfälle: Anleitungen zur Überwachung von Bewertungen und zur gesammelten Beantwortung