Listings APIListings API
Entrar

Node SDK

Cliente oficial em TypeScript para Listings API, sem dependências, com paginação automática e definições de tipos incluídas para Node 18+.

listingsapi-js é o cliente oficial de Node.js/TypeScript para a Listings API v4. Ele gerencia locais, listagens em diretórios, avaliações, publicações, fotos e análises de perfis por meio de um único cliente com métodos diretamente na instância, com paginação baseada em cursor, codificação automática de IDs, novas tentativas integradas e erros tipados disponíveis por padrão.

Instalar

bash
npm install listingsapi-js

Autenticar

Obtenha sua chave de API em API Keys → New key no painel de desenvolvedores da 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

O construtor também aceita baseUrl (padrão: https://listingsapi.com), timeout (padrão: 240000 ms) e maxRetries (padrão: 2). Consulte Configuração.

Exemplo rápido

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

Recursos

Todos os métodos estão na instância do cliente:

MétodosO que gerenciam
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocationsLocais de empresas: listar, pesquisar, criar, atualizar, arquivar
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStatsAvaliações: listar, responder, editar e arquivar respostas, configurações, dados de expressões e análises
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPostsPublicações: anúncios, eventos e ofertas no Google e no Facebook
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicateListagens em diretórios: premium, voz, duplicatas
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsAnálises de perfis do Google, Bing e Facebook
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatusFotos de locais
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingConexões OAuth com o Google e o Facebook, links de listagens
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategoriesDiretórios do plano, países disponíveis, assinaturas, categorias de empresas

A Social API — marcas, contas de redes sociais conectadas e publicações no Facebook, Instagram, X, LinkedIn e Pinterest — ainda não tem suporte neste SDK; faça chamadas diretamente a ela conforme a referência REST da Social API.

Paginação

Os métodos que retornam listas oferecem suporte à paginação baseada em cursor.

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 e fetchInteractions seguem o mesmo padrão: um objeto de página por padrão e um array sem aninhamento com fetchAll: true.

Codificação de IDs

Passe IDs numéricos de locais em qualquer lugar: o SDK os codifica em base64 automaticamente. IDs já codificados são aceitos sem alterações, e o codificador é exportado caso você precise usá-lo diretamente.

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

Tratamento de erros

Todo erro do SDK deriva de ListingsAPIError. Falhas da API lançam APIError ou uma de suas subclasses, seja quando a plataforma as informa como um status HTTP ou no corpo de uma resposta HTTP 200 (tokens inválidos e validações de escrita chegam como payloads errors[], e operações de escrita podem informar success: false). O SDK lança exceções para todos esses casos, então você nunca precisa inspecionar os indicadores success por conta própria. Falhas de rede lançam APIConnectionError.

ClasseLançada em caso de
AuthenticationError401 ou payloads de erro de token inválido
PermissionDeniedError403 ou payloads de erro de permissão
NotFoundError404
ValidationError400/422 ou operações de escrita que retornam success: false / errors[]
RateLimitError429, contém retryAfter em segundos
InternalServerError5xx
APIConnectionErrorFalha de rede, nada chegou à API

Todo APIError contém statusCode, responseBody, code (o primeiro código de erro da plataforma, e.g. "SY10005") e errors (cada entrada normalizada para { 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 }, ...]}}

O cliente faz novas tentativas automaticamente para respostas 429 e 5xx (2 tentativas por padrão, respeitando Retry-After). Consulte Tratamento de erros para ver padrões de novas tentativas e orientações sobre códigos de status.

Próximos passos