Listings APIListings API
Iniciar sesión

Node SDK

Cliente oficial de TypeScript para Listings API, sin dependencias, con paginación automática y definiciones de tipos incluidas para Node 18+.

listingsapi-js es el cliente oficial de Node.js/TypeScript para Listings API v4. Gestiona ubicaciones, fichas en directorios, reseñas, publicaciones, fotos y análisis de perfiles desde un único cliente sin jerarquías, con paginación basada en cursores, codificación automática de ID, reintentos integrados y errores tipados de serie.

Instalar

bash
npm install listingsapi-js

Autenticarse

Obtén tu clave de API en Claves de API → Nueva clave en el panel para desarrolladores de 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

El constructor también acepta baseUrl (por defecto, https://listingsapi.com), timeout (por defecto, 240000 ms) y maxRetries (por defecto, 2). Consulta Configuración.

Ejemplo 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 los métodos están en la instancia del cliente:

MétodosQué gestionan
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocationsUbicaciones de negocios: enumerar, buscar, crear, actualizar, archivar
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStatsReseñas: enumerar, responder, editar y archivar respuestas, configuración, datos de frases y análisis
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPostsPublicaciones: anuncios, eventos y ofertas en Google y Facebook
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicateFichas en directorios: premium, voz, duplicados
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsAnálisis de perfiles de Google, Bing y Facebook
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatusFotos de ubicaciones
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingConexiones OAuth con Google y Facebook, enlaces a fichas
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategoriesDirectorios del plan, países admitidos, suscripciones, categorías de negocios

Este SDK todavía no incluye métodos para la Social API —marcas, cuentas de redes sociales conectadas y publicaciones en Facebook, Instagram, X, LinkedIn y Pinterest—; realiza llamadas directas siguiendo la referencia REST de Social.

Paginación

Los métodos que devuelven listas admiten paginación basada en cursores.

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 y fetchInteractions siguen el mismo patrón: un objeto de página por defecto y un array plano con fetchAll: true.

Codificación de ID

Pasa los ID numéricos de ubicación en cualquier lugar: el SDK los codifica automáticamente en base64. Los ID ya codificados se aceptan tal cual, y el codificador se exporta por si necesitas usarlo directamente.

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

Gestión de errores

Todos los errores del SDK derivan de ListingsAPIError. Los fallos de la API lanzan APIError o una de sus subclases, tanto si la plataforma los comunica mediante un estado HTTP como si lo hace dentro del cuerpo de una respuesta HTTP 200 (los tokens no válidos y la validación de escrituras llegan como cargas útiles errors[], y las escrituras pueden comunicar success: false). El SDK lanza excepciones en todos estos casos, por lo que nunca tienes que comprobar los indicadores success por tu cuenta. Los fallos de red lanzan APIConnectionError.

ClaseSe lanza en caso de
AuthenticationError401 o cargas útiles de error por token no válido
PermissionDeniedError403 o cargas útiles de error de permisos
NotFoundError404
ValidationError400/422 o escrituras que devuelven success: false / errors[]
RateLimitError429, incluye retryAfter en segundos
InternalServerError5xx
APIConnectionErrorFallo de red, no llegó nada a la API

Cada APIError incluye statusCode, responseBody, code (el primer código de error de la plataforma, e.g. "SY10005") y errors (cada entrada normalizada a { 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 }, ...]}}

El cliente reintenta automáticamente las solicitudes que reciben respuestas 429 y 5xx (2 intentos por defecto, respetando Retry-After). Consulta Gestión de errores para ver patrones de reintento y orientación sobre los códigos de estado.

Siguientes pasos