Listings APIListings API
登录

Python SDK

Listings API 官方 Python 客户端，支持类型化资源、游标分页、自动重试和具名错误。

listingsapi 包是 Listings API 的官方 Python 客户端。它封装了 REST 层，提供带类型的资源类、基于游标的分页、临时错误自动重试，并为每种失败情况提供具名异常，包括平台随 HTTP 200 返回错误载荷的情况。

安装

bash
pip install listingsapi

需要 Python 3.9 或更高版本。唯一的运行时依赖项是 requests。

身份验证

Python
import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")

在 Listings API 开发者控制台中，通过 API 密钥 → 新建密钥获取您的 API 密钥。

客户端接受 3 个可选的关键字参数：

选项默认值说明
base_urlhttps://listingsapi.com接收请求的 API 主机
timeout240.0每个请求的超时时间，单位为秒
max_retries2收到 429 和 5xx 响应时自动重试，并遵循 Retry-After

有关详细信息，请参阅配置。

简单示例

list_locations.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, loc.city) print(f"has_more: {page.has_more}")

资源

每个资源都是客户端的一个属性：

属性管理内容
client.locations商家地点：列出、搜索、通过一次调用创建、更新、归档
client.reviews评价及回复，以及 client.reviews.analytics 下的分析功能
client.posts发布到 Google 和 Facebook 的公告、活动和优惠帖子
client.socialSocial 品牌、已连接的社交账号，以及发布到 Facebook、Instagram、X、LinkedIn 和 Pinterest 的帖子
client.listings高级商家信息和语音商家信息、重复商家信息、连接和断开连接
client.analyticsGoogle、Bing 和 Facebook 商家资料的成效分析
client.photos地点照片：上传、移除、标星
client.connected_accounts与 Google 和 Facebook 的 OAuth 连接
client.workflows预置自动化功能：评价自动回复、声誉报告、商家信息健康状况审核

客户端本身提供 4 个辅助方法：

Python
client.plan_sites()       # directories included in your planclient.subcategories()    # business categories (IDs for locations.add)client.countries()        # supported countries and states (ISO codes)client.subscriptions()    # active subscriptions for the account

分页

返回列表的方法使用基于游标的分页。每个分页方法都返回一个 SyncPage：可迭代，并包含 .has_more、.next_page()、.auto_paging_iter() 和 .total。

Python
# Fetch one pagepage = client.locations.list(first=25)for loc in page:  print(loc.name) # Check if more pages existif page.has_more:  next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

响应对象

所有方法都返回 APIObject（支持属性访问和字典访问）或 SyncPage（可迭代，支持分页）。APIObject 还支持 .get() 和 .to_dict()。

Python
loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()

错误处理

所有 SDK 错误都继承自 listingsapi.ListingsAPIError。API 调用失败时会抛出 APIError 或其子类之一：AuthenticationError、PermissionDeniedError、NotFoundError、ValidationError、RateLimitError（附带 .retry_after）和 InternalServerError。网络故障会抛出 APIConnectionError。

APIError 包含 status_code、code（第一个平台错误码，e.g。SY10005）、errors（每个条目均规范化为 {"code", "message", "context"} 字典）和 response_body。

平台会在 HTTP 200 响应正文中报告某些失败情况：顶层 errors[] 载荷（令牌无效时返回 SY90005）以及包含 success=false 的写入响应。SDK 也会针对这些情况抛出异常，因此您无需自行检查 success 标志。

Python
import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.retrieve(999999)except listingsapi.NotFoundError:  print("No such location")except listingsapi.RateLimitError as e:  print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e:  print(e.status_code, e.code)  for err in e.errors:      print(err["code"], err["message"])

有关完整的异常层次结构，请参阅错误处理。

后续步骤