Node SDK
Listings API 官方 TypeScript 客户端，无依赖，支持自动分页，并附带类型定义，适用于 Node 18+。
listingsapi-js 是 Listings API v4 的官方 Node.js/TypeScript 客户端。它通过一个扁平化客户端统一管理地点、目录商家信息、评价、帖子、照片和商家资料分析数据，并内置基于游标的分页、自动 ID 编码、重试和带类型的错误。
安装
npm install listingsapi-js身份验证
在 Listings API 开发者控制台中，通过 API Keys → New key 获取您的 API 密钥。
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构造函数还接受 baseUrl（默认值为 https://listingsapi.com）、timeout（默认值为 240000 毫秒）和 maxRetries（默认值为 2）。请参阅配置。
简要示例
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);}}资源
所有方法都位于客户端实例上：
此 SDK 尚未封装 Social API，其功能包括品牌、已连接的社交账号，以及向 Facebook、Instagram、X、LinkedIn 和 Pinterest 发布帖子；请参照 Social REST 参考文档直接调用该 API。
分页
返回列表的方法支持基于游标的分页。
// 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 和 fetchInteractions 遵循相同的模式：默认返回分页对象，使用 fetchAll: true 时返回扁平数组。
ID 编码
在任何需要地点 ID 的位置，都可以传入数字 ID：SDK 会自动对其进行 base64 编码。已编码的 ID 会原样接受；编码器也已导出，供您在需要时自行使用。
import { encodeLocationId } from 'listingsapi-js'; // These are equivalentawait client.fetchPremiumListings(16808);await client.fetchPremiumListings('TG9jYXRpb246MTY4MDg='); encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='错误处理
所有 SDK 错误都派生自 ListingsAPIError。API 失败时，无论平台通过 HTTP 状态码还是 HTTP 200 响应体报告错误，都会抛出 APIError 或其子类的实例（无效令牌和写入验证错误以 errors[] 载荷的形式返回，写入操作还可能报告 success: false）。SDK 会针对所有这些情况抛出异常，因此您无需自行检查 success 标志。网络失败时会抛出 APIConnectionError。
每个 APIError 都携带 statusCode、responseBody、code（第一个平台错误代码，e.g。"SY10005"）和 errors（每个条目都规范化为 { code, message, context }）。
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 }, ...]}}客户端会自动重试收到 429 和 5xx 响应的请求（默认尝试 2 次，并遵循 Retry-After）。有关重试模式和状态码的说明，请参阅错误处理。