Listings APIListings API
Oturum aç

Node SDK

Node 18+ için sıfır bağımlılığa sahip, otomatik sayfalama ve paketle gelen tür tanımları sunan resmî Listings API TypeScript istemcisi.

listingsapi-js, Listings API v4 için resmi Node.js/TypeScript istemcisidir. Konumları, dizinlerdeki işletme kayıtlarını, yorumları, gönderileri, fotoğrafları ve profil analizi verilerini tek bir düz yapılı istemci üzerinden yönetir; imleç tabanlı sayfalama, otomatik kimlik kodlama, yerleşik yeniden deneme ve tür tanımlı hata desteği sunar.

Kurulum

bash
npm install listingsapi-js

Kimlik doğrulama

API anahtarınızı Listings API geliştirici kontrol panelindeki API Keys → New key bölümünden alın.

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

Kurucu ayrıca baseUrl (varsayılan https://listingsapi.com), timeout (varsayılan 240000 ms) ve maxRetries (varsayılan 2) parametrelerini kabul eder. Yapılandırma bölümüne bakın.

Kısa örnek

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

Kaynaklar

Tüm metotlar istemci örneğinde bulunur:

MetotlarYönettikleri öğeler
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocationsİşletme konumları: listeleme, arama, oluşturma, güncelleme, arşivleme
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStatsYorumlar: listeleme, yanıtlama, yanıtları düzenleme ve arşivleme, ayarlar, ifade ve analiz verileri
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPostsGönderiler: Google ve Facebook'taki duyurular, etkinlikler ve teklifler
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicateDizinlerdeki işletme kayıtları: premium kayıtlar, sesli arama kayıtları, yinelenen kayıtlar
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsGoogle, Bing ve Facebook profil analizi verileri
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatusKonum fotoğrafları
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingGoogle ve Facebook OAuth bağlantıları, işletme kaydı bağlantıları
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategoriesPlan kapsamındaki dizinler, desteklenen ülkeler, abonelikler, işletme kategorileri

Social API — markalar, bağlı sosyal medya hesapları ve Facebook, Instagram, X, LinkedIn ve Pinterest gönderileri — henüz bu SDK tarafından kapsanmamaktadır; Social REST referansını kullanarak doğrudan çağrı yapın.

Sayfalama

Liste döndüren metotlar imleç tabanlı sayfalamayı destekler.

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 ve fetchInteractions aynı şekilde çalışır: varsayılan olarak bir sayfa nesnesi, fetchAll: true ile düz bir dizi döndürür.

Kimlik kodlama

Her yerde sayısal konum kimlikleri kullanabilirsiniz: SDK bunları otomatik olarak base64 ile kodlar. Önceden kodlanmış kimlikler olduğu gibi kabul edilir; kodlayıcıyı kendiniz kullanmanız gerekirse dışa aktarılmış olarak da sunulur.

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

Hata işleme

Tüm SDK hataları ListingsAPIError sınıfından türetilir. Platform API hatalarını ister HTTP durum kodu olarak ister HTTP 200 yanıt gövdesinde bildirsin, bu hatalarda APIError veya alt sınıflarından biri fırlatılır (geçersiz belirteçler ve yazma doğrulaması errors[] veri yükleri olarak gelir; yazma işlemleri de success: false bildirebilir). SDK bunların tümünde hata fırlattığı için success bayraklarını kendiniz incelemeniz gerekmez. Ağ hatalarında APIConnectionError fırlatılır.

SınıfFırlatıldığı durumlar
AuthenticationError401 veya geçersiz belirteç hatası veri yükleri
PermissionDeniedError403 veya izin hatası veri yükleri
NotFoundError404
ValidationError400/422 veya success: false / errors[] döndüren yazma işlemleri
RateLimitError429, saniye cinsinden retryAfter içerir
InternalServerError5xx
APIConnectionErrorAğ hatası, API'ye hiçbir istek ulaşmadı

Her APIError; statusCode, responseBody, code (platformun ilk hata kodu, e.g. "SY10005") ve errors (her öğe { code, message, context } biçimine dönüştürülmüş olarak) içerir.

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

İstemci, 429 ve 5xx yanıtları için otomatik olarak yeniden deneme yapar (Retry-After dikkate alınarak varsayılan olarak 2 deneme). Yeniden deneme yöntemleri ve durum kodlarıyla ilgili bilgi için Hata işleme bölümüne bakın.

Sonraki adımlar