Listings APIListings API
Masuk

Node SDK

Klien TypeScript resmi untuk Listings API, tanpa dependensi, dengan paginasi otomatis dan definisi tipe bawaan untuk Node 18+.

listingsapi-js adalah klien Node.js/TypeScript resmi untuk Listings API v4. Klien ini mengelola lokasi, profil bisnis di direktori, ulasan, postingan, foto, dan analitik profil melalui satu klien berstruktur datar, dengan dukungan bawaan untuk paginasi berbasis kursor, pengodean ID otomatis, percobaan ulang bawaan, dan error bertipe.

Instalasi

bash
npm install listingsapi-js

Autentikasi

Dapatkan kunci API Anda dari API Keys → New key di dasbor pengembang 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

Konstruktor juga menerima baseUrl (nilai default https://listingsapi.com), timeout (nilai default 240000 ms), dan maxRetries (nilai default 2). Lihat Konfigurasi.

Contoh singkat

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

Sumber daya

Semua metode tersedia pada instans klien:

MetodeYang dikelola
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocationsLokasi bisnis: menampilkan daftar, mencari, membuat, memperbarui, mengarsipkan
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStatsUlasan: menampilkan daftar, membalas, mengedit dan mengarsipkan tanggapan, pengaturan, data frasa dan analitik
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPostsPostingan: pengumuman, acara, dan penawaran di Google dan Facebook
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicateProfil bisnis di direktori: premium, suara, duplikat
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsAnalitik profil Google, Bing, dan Facebook
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatusFoto lokasi
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingKoneksi OAuth ke Google dan Facebook, tautan profil bisnis
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategoriesDirektori dalam paket, negara yang didukung, langganan, kategori bisnis

Social API — merek, akun media sosial yang terhubung, dan postingan ke Facebook, Instagram, X, LinkedIn, dan Pinterest — belum dicakup oleh SDK ini; panggil API tersebut secara langsung dengan mengacu pada Referensi REST Social.

Paginasi

Metode yang mengembalikan daftar mendukung paginasi berbasis kursor.

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 dan fetchInteractions mengikuti pola yang sama: objek halaman secara default, array datar dengan fetchAll: true.

Pengodean ID

Berikan ID lokasi numerik di mana saja: SDK akan mengodekannya secara otomatis dengan base64. ID yang sudah dikodekan diterima tanpa perubahan, dan fungsi pengodean diekspor jika Anda perlu menggunakannya sendiri.

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

Penanganan error

Setiap error SDK diturunkan dari ListingsAPIError. Kegagalan API melempar APIError atau salah satu subkelasnya, baik platform melaporkannya sebagai status HTTP maupun di dalam isi respons HTTP 200 (token tidak valid dan validasi operasi tulis diterima sebagai payload errors[], dan operasi tulis dapat melaporkan success: false). SDK melempar error untuk semua kondisi ini, sehingga Anda tidak perlu memeriksa sendiri flag success. Kegagalan jaringan melempar APIConnectionError.

KelasDilempar untuk
AuthenticationError401, atau payload error token tidak valid
PermissionDeniedError403, atau payload error izin
NotFoundError404
ValidationError400/422, atau operasi tulis yang mengembalikan success: false / errors[]
RateLimitError429, menyertakan retryAfter dalam detik
InternalServerError5xx
APIConnectionErrorKegagalan jaringan, tidak ada permintaan yang mencapai API

Setiap APIError menyertakan statusCode, responseBody, code (kode error platform pertama, e.g. "SY10005"), dan errors (setiap entri dinormalisasi menjadi { 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 }, ...]}}

Klien secara otomatis mencoba ulang permintaan yang menerima respons 429 dan 5xx (2 percobaan secara default, dengan mengikuti Retry-After). Lihat Penanganan error untuk pola percobaan ulang dan panduan kode status.

Langkah berikutnya