Listings APIListings API
登录

配置

配置 Listings API Python 客户端：API 密钥、基础 URL、超时、重试和日志记录。

构造函数签名

Python
listingsapi.ListingsAPI(    api_key: str | None = None,    *,    base_url: str | None = None,    timeout: float = 240.0,    max_retries: int = 2,)

所有参数均为可选参数。如果省略 api_key，客户端会从环境中读取 LISTINGSAPI_KEY；如果两者均未设置，则在构造时抛出 AuthenticationError。

选项

选项类型默认值说明
api_keystr | NoneNoneAPI 密钥。未提供时使用环境变量 LISTINGSAPI_KEY 的值。
base_urlstr | Nonehttps://listingsapi.comAPI 源地址。末尾的斜杠会自动移除。
timeoutfloat240.0每个请求的超时时间，单位为秒（单独应用于每个 HTTP 请求）。
max_retriesint2收到 429 和 5xx 响应时自动重试。设置为 0 可禁用重试。

API 密钥

bash
export LISTINGSAPI_KEY="your-api-key"
Python
import listingsapi # From environment (recommended)client = listingsapi.ListingsAPI() # Explicit keyclient = listingsapi.ListingsAPI(api_key="your-api-key")

超时

默认值为 240.0 秒。对于运行时间较短的脚本或交互式使用场景，您可能需要设置更短的超时时间：

Python
client = listingsapi.ListingsAPI(timeout=30.0)

超时时间单独应用于每个 HTTP 请求。批量分页调用（auto_paging_iter）中的每个请求都独立遵循此超时设置。

重试

SDK 在其 requests 会话上挂载了一个 urllib3 Retry 适配器，收到 429、500、502、503 和 504 响应时会自动重试，但仅限安全方法：GET、HEAD 和 OPTIONS。写入请求（POST、DELETE）只发送 1 次，失败时会立即抛出异常。默认重试 2 次，指数退避因子为 0.5 秒。重试会遵循 Retry-After 响应头，因此，如果 429 指定了等待时间，就会在等待该时长后重试。

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

Python
# More aggressive retry for long-running batch jobsclient = listingsapi.ListingsAPI(max_retries=5) # Disable retries entirely (e.g. when you want fast failures)client = listingsapi.ListingsAPI(max_retries=0)

如果所有重试后仍收到 429，则会将其作为 RateLimitError 抛出；有关手动退避的实现方法，请参阅错误处理。

覆盖基础 URL

适用于预发布环境或内部代理：

Python
client = listingsapi.ListingsAPI(base_url="https://staging.example.com")

末尾的斜杠会自动移除。所有请求都发送到此源地址的 /api/v4/ 路径下。

日志

SDK 通过标准 logging 模块，使用 listingsapi 日志记录器记录日志。在 DEBUG 级别下，它会记录每个请求的方法和 URL（对于 GET，还会记录查询参数）；请求体和您的 API 密钥绝不会被记录。

Python
import logginglogging.basicConfig()logging.getLogger("listingsapi").setLevel(logging.DEBUG) import listingsapiclient = listingsapi.ListingsAPI()client.locations.list(first=1)

后续步骤