Listings APIListings API
登录

配置

配置 listingsapi-js 客户端：API 密钥解析、基础 URL 覆盖、超时和自动重试。

构造函数选项

ListingsAPI 接受一个选项对象，该对象及其所有选项均为可选：

选项类型是否必需默认值说明
apiKeystring否process.env.LISTINGSAPI_KEY您的 Listings API 密钥。省略时，客户端会读取 LISTINGSAPI_KEY 环境变量；如果两者均未设置，则抛出 AuthenticationError。
baseUrlstring否https://listingsapi.com覆盖 API 主机地址，适用于代理或预发布环境。末尾的斜杠会自动移除。
timeoutnumber否240000每个请求的超时时间，以毫秒为单位，通过 AbortSignal.timeout 强制执行。
maxRetriesnumber否2遇到限流、服务器错误和网络故障时自动重试。仅重试读取操作；写入操作绝不重试。设为 0 可禁用。
TypeScript
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env // Every default spelled out:const custom = new ListingsAPI({apiKey: process.env.LISTINGSAPI_KEY,baseUrl: 'https://listingsapi.com',timeout: 240000,   // 4 minutes per attemptmaxRetries: 2,     // up to 3 attempts total});

API 密钥解析

切勿在源代码中硬编码密钥。无参数构造函数会从环境中读取 LISTINGSAPI_KEY：

Shell
export LISTINGSAPI_KEY="your-api-key"
TypeScript
const client = new ListingsAPI();

您也可以传入从密钥管理服务获取的密钥：

TypeScript
import { getSecret } from './secrets.js'; const apiKey = await getSecret('LISTINGSAPI_KEY');const client = new ListingsAPI({ apiKey });

如果这两个位置均未找到密钥，构造函数会在发出任何请求之前立即抛出 AuthenticationError。

覆盖基础 URL

将客户端指向内部代理或预发布环境：

TypeScript
const client = new ListingsAPI({baseUrl: 'https://listings-proxy.internal.example.com',});

末尾的斜杠会自动移除，因此 'https://listingsapi.com/' 和 'https://listingsapi.com' 的行为相同。

超时

内部会使用 AbortSignal.timeout(timeout) 包装每次尝试（Node 18+），因此您无需自行用 AbortController 包装 SDK 调用。默认情况下，每次尝试的超时时间为 240000 毫秒（4 分钟）。

超时的尝试会被视为连接失败：只要还有剩余尝试次数，客户端就会重试，最终失败时会抛出 APIConnectionError。对于延迟敏感的代码路径，请缩短超时时间：

TypeScript
const client = new ListingsAPI({ timeout: 15000 }); // 15 s per attempt

自动重试

仅当使用安全方法 GET、HEAD 和 OPTIONS 时，客户端才会在响应状态为 429、500、502、503 和 504，或发生网络层故障（DNS 错误、连接被拒绝、超时）时重试。自 0.3.2 起，写入请求（POST、DELETE）只发送 1 次，失败时会立即向调用方报告。使用默认设置 maxRetries: 2 时，每次读取最多尝试 3 次。

v4 API 不支持 Idempotency-Key，也不会检测重复写入，因此超时或返回 5xx 的写入操作可能已经提交。盲目重试会创建第 2 个地点、帖子或评价回复。在重复写入之前，请使用您控制的键读取记录进行确认。

每次重试前的等待时间：

  1. 如果响应包含 Retry-After 响应头，且其值为正数秒数，客户端会严格按该时长等待。
  2. 否则，等待时间按指数增长：首次重试前等待 500 毫秒，之后每次重试的等待时间翻倍（1 秒、2 秒，以此类推）。

网络故障会立即重试，无需等待。尝试次数耗尽后，最后一次响应会转换为具有具体类型的错误（RateLimitError、InternalServerError 等；请参阅错误处理），如果网络故障的尝试次数耗尽，则会抛出 APIConnectionError。

TypeScript
// Fail fast and own the retry policy yourself:const client = new ListingsAPI({ maxRetries: 0 });

地点 ID

在 SDK 接受地点 ID 的所有位置，数字 ID 都会自动编码为 API 的 base64 格式（Location:<id>），已编码的 ID 则原样传递。如果您需要自行获取编码后的形式，可以使用已导出的辅助函数：

TypeScript
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808);                  // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // returned as-is

请求头格式

每个请求都使用以下请求头进行身份验证：

Code
Authorization: API <your-key>Content-Type: application/json

SDK 会在每次调用时自动设置这些请求头。您无需配置。

TypeScript 项目设置

SDK 以 TypeScript 为主要开发语言，并内置类型定义，因此无需单独安装 @types 包。请固定版本，以确保构建结果可复现：

Shell
npm install listingsapi-js@0.3.2

适用于 Node 18+ 项目的最小 tsconfig.json 配置：

tsconfig.json
{"compilerOptions": {  "target": "ES2022",  "module": "Node16",  "moduleResolution": "Node16",  "strict": true,  "outDir": "dist"}}

对于在 package.json 中设置了 "type": "module" 的 ESM 项目，请使用 "module": "Node16" 和 "moduleResolution": "Node16"。对于 CJS 项目，使用 "module": "CommonJS" 和 "moduleResolution": "Node" 即可；该包包含这两种构建产物，CommonJS 代码通过 const { ListingsAPI } = require('listingsapi-js') 加载该包。

不使用 TypeScript

listingsapi-js 编译为普通 JavaScript，无任何运行时依赖。您可以在 .js 或 .mjs 文件中导入它，无需构建步骤：

script.mjs
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI();const page = await client.fetchAllLocations({ first: 5 });for (const location of page.locations) {console.log(location.name, location.city); // Acme Dental Midtown}

后续步骤