Listings APIListings API
Anmelden

Schnellstart

Verbinden Sie sich mit der Listings API, listen Sie Ihre Standorte auf, erstellen Sie einen Standort und beantworten Sie eine Bewertung in TypeScript.

1. API-Schlüssel festlegen

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

bash
export LISTINGSAPI_KEY="your-api-key"

new ListingsAPI() liest LISTINGSAPI_KEY automatisch aus der Umgebung, oder Sie übergeben apiKey explizit.

2. Ihre Standorte auflisten

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

Erwartete Ausgabe:

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

fetchAllLocations gibt standardmäßig ein Objekt mit locations und pageInfo zurück. Wenn Sie fetchAll: true übergeben, ruft das SDK automatisch die über Cursor verknüpften Folgeseiten ab und gibt stattdessen Location[] ohne Verschachtelung zurück.

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

3. Einen Standort erstellen

Die API erfordert name, city, countryIso, subCategoryId sowie description mit mindestens 200 Zeichen. Rufen Sie gültige Werte für subCategoryId über client.fetchSubcategories() ab und verwenden Sie databaseId des jeweiligen Eintrags.

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

Wenn die Nutzdaten ungültig sind, löst das SDK einen Fehler vom Typ ValidationError aus, der die Fehlereinträge der Plattform enthält, auch wenn die API HTTP 200 zurückgibt. Es gibt kein Flag success, das Sie prüfen können.

4. Auf eine Bewertung antworten

Rufen Sie Bewertungen für einen Standort ab und antworten Sie anschließend anhand der Interaktions-ID. Numerische Standort-IDs werden überall akzeptiert: Das SDK kodiert sie automatisch mit 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. Fehler behandeln

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

Das SDK löst typisierte Fehler bei Antworten mit einem Statuscode außerhalb des 2xx-Bereichs, bei Fehlernutzdaten, die die Plattform mit HTTP 200 zurückgibt, und bei Schreibvorgängen aus, die success: false melden. Außerdem wiederholt es Anfragen bei 429- und 5xx-Antworten automatisch. Unter Fehlerbehandlung finden Sie Vorgehensweisen für Wiederholungsversuche und Hinweise zu Statuscodes.

Nächste Schritte