TikTok Shop 商品研究 API:首屏搜索与地区拒绝处理
读取 TikTok Shop 关键词首屏或已知商品响应,识别地区不支持,保留价格字符串,并将历史选品实验与当前证据分开。

TikTok Shop 搜索返回空数组,与详情返回“这个地区暂不支持”,需要两种不同的处理。旧代码连续用 .get("data", {}) 取值,很容易把后者吞成“没有商品”。这篇 TikTok Shop 商品研究 API 教程先解决这个问题:明确选择一个关键词首屏,或者一个已知商品及其市场,再判断业务返回能不能继续使用。
本次修订日期为 2026 年 11 月 8 日,依据公开参数、历史保存响应与离线测试,没有发起新的业务请求。现在保留的完整搜索样本来自越南市场,详情样本则是 GB 地区拒绝。10 月 1 日的美国市场旧实验仍可查阅,但不能当作今天详情接口成功的证明。
先说结论
- 搜索必填
search_word,示例明确指定市场,以 offset0 和空 page_token 起步。- 详情使用原样字符串
product_id;它的 region 没有参数默认值,不能直接假设美国。- 先检查
region_supported: false,再解析成功码与 data。保存的 GB 拒绝恰好没有这两个字段。- 商品 ID、币种和原始计数要一起保留;一个结果样本不能证明市场规模、收入或全站销量冠军。
保留的封面描述旧版商品、评论、店铺串联构想。“niche verdict”、五星和连接管线均为概念图,不代表这次执行了选品链路或得到商业结论。
先选定一个商品研究任务
| 你现在要做什么 | 参考入口 | 本文请求边界 |
|---|---|---|
| 看关键词返回的商品卡片 | 关键词商品搜索 | search_word、明确 region、offset0、空 token |
| 看一个已知商品的响应 | 商品详情 V2 | 原样字符串 product_id、用户选定 region |
两个入口不是默认串联流程。搜索结束后,不会自动挑销量最高的卡片、查评论或遍历店铺。详情还声明了可选 seller_id,这个首请求不传。搜索没有声明 limit、page_size、排序或筛选对象参数;响应里出现筛选建议,也不等于请求可以增加同名字段。
搜索 region 的参数默认值是 US,详情却没有默认值。两份说明都写了 US/GB/SG/MY/PH/TH/VN/ID,但它们不是强制枚举,更不是当前可用性实测表。代码只检查大写两位地区码,这是本地输入约束,不是“只要格式正确就支持”。商品、商家和 SKU 是不同标识;长 ID 要保留字符串,避免 JavaScript Number 丢失精度。
历史 TikTok 目录,选中的是 Creator Search Insights,显示145项、GET导航路径及已经结束的 API Free Week。图中 Free 标记不是当前 Shop 价格,也不是商品响应。
给 agent 的任务要能停下来
已有项目继续使用本地 SANDBASE_API_KEY 或现有密钥管理,不需要为了一个接口重建配置;不要把密钥粘进提示词。已接入的 agent 需要的是具体关键词、市场和停止条件。新项目可交给它 setup skill 与 Markdown quickstart。
可以直接这样描述:“用我本地的密钥实现 VN 市场 áo khoác zip bé 的一次搜索,验证 completed 信封,保留商品 ID 和 VND 价格字符串,返回首屏就停。用离线样本测试地区不支持,不重试、不换地区、不自动查详情。”如果下一步确实要详情,再单独选定商品和市场。
11 月 8 日的 inspect 显示,两接口各列价 $0.001,具备组织共享每日100次合资格调用的额度资格,UTC零点重置。资格不等于剩余额度,也不是每个接口各送100次。两次明确选择的调用列价合计 $0.002,尚未考虑实际适用额度;这只是算术,不是本文自动执行的流程。没有新计费记录支持“失败必定不收费”等保证。
Python:先识别拒绝,再读取商品
通过 python -m pip install requests 安装依赖,在本地配置密钥后保存下面的代码。它调用 Model API 的 POST /v1/api/<model>,body只放操作参数;不要照搬目录里的 GET 导航地址。每次函数调用最多一次请求,没有自动重试。
import os
import re
import requests
API = "https://api.sandbase.ai/v1/api/tiktok/shop-web"
class UnsupportedRegion(RuntimeError):
def __init__(self, payload):
super().__init__("Provider reports unsupported region; stopped without fallback")
self.payload = payload
def first_request(task, value, region):
if not isinstance(region, str) or not re.fullmatch(r"[A-Z]{2}", region):
raise ValueError("Choose a two-letter uppercase market code")
if not isinstance(value, str) or not value.strip() or value != value.strip():
raise ValueError("Provide a nonblank keyword or unchanged product ID")
if task == "search":
route = "search-products-list"
params = {"search_word": value, "region": region, "offset": 0, "page_token": ""}
elif task == "detail":
if not re.fullmatch(r"[0-9]+", value):
raise ValueError("Keep the selected product ID as a decimal string")
route = "product-detail-v2"
params = {"product_id": value, "region": region}
else:
raise ValueError("Choose search or detail")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
f"{API}/{route}",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=params, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"SandBase HTTP {response.status_code}; request stopped")
body = response.json()
except requests.RequestException:
raise RuntimeError("Network failure; no automatic retry made") from None
except ValueError:
raise RuntimeError("Invalid response JSON") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0]")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Missing documented outputs[0].data object")
if payload.get("region_supported") is False:
raise UnsupportedRegion(payload)
if type(payload.get("code")) is not int or payload["code"] != 0:
raise RuntimeError("Provider success code is missing or invalid")
data = payload.get("data")
if not isinstance(data, dict):
raise RuntimeError("Missing provider data object")
if task == "search":
products = data.get("products")
if not isinstance(products, list) or any(not isinstance(p, dict) for p in products):
raise RuntimeError("Missing or malformed products array")
for p in products:
if not isinstance(p.get("product_id"), str) or not re.fullmatch(r"[0-9]+", p["product_id"]):
raise RuntimeError("Expected an unchanged decimal string product_id")
else:
# This is the historical October 1 layout, not a current success guarantee.
components = data.get("components_map")
if not isinstance(components, list) or any(not isinstance(c, dict) for c in components):
raise RuntimeError("Unrecognized detail shape; inspect locally before adapting")
return payload
if __name__ == "__main__":
result = first_request("search", "áo khoác zip bé", "VN")
print("Returned products:", len(result["data"]["products"]))如果选择已知商品任务,请把最后 if __name__ == "__main__": 下面的两行一起替换为以下内容,并保留原有缩进。占位值要换成真实十进制字符串 ID 和两位市场码,否则会被拒绝。不能只替换调用而保留读取 products 的搜索输出,也不要把详情追加成第二次请求。
result = first_request("detail", "YOUR_SELECTED_PRODUCT_ID", "YOUR_MARKET")
print("Detail response matched the historical layout")这里仅说明返回符合历史布局,不宣称已经核验商品身份。
UnsupportedRegion 会在异常的 payload 属性保留原业务对象,便于本地诊断;异常消息不直接打印它,更不打印密钥。搜索解析器有完整保存样本支持。详情的正向检查只识别旧10月1日实验描述的 components_map 布局,其正向单元测试使用合成结构,不是新抓到的成功商品。遇到别的布局会报错,不能悄悄改成空结果。
这段代码不会从历史详情布局推断商品身份、标题或价格,也不把 completed 当作当前市场可用的证明。原字段返回给调用方,缺失计数不会补零。
历史 search-products-list 参数页,包含POST路径、必填search_word与可选offset、token、region;生成响应的data为空。它说明请求格式,没有展示成功的商品结果。
越南搜索与英国拒绝是独立证据
搜索保存记录 4ac99e1c-df10-49d8-9f89-2ff007551b3b 的时间为10月7日17:37:34.382 UTC,请求词是 áo khoác zip bé,市场VN,offset0、token为空。完整结果有20个商品,has_more为false;load_more_params里的offset仍为0,token仍为空。20只是这次样本条数,不是声明的分页大小或保证。
下面是第一张卡片的原值投影:
{
"product_id": "1733538036469040527",
"product_price_info": {
"currency_name": "VND",
"currency_show_mode": 1,
"currency_symbol": "₫",
"decimal_point_symbol": "",
"discount_decimal": "0.34",
"discount_format": "34%",
"origin_price_decimal": "609199",
"origin_price_format": "609.199",
"promotion_deduction_details": {
"seller_subtotal_deduction": "245.199",
"seller_subtotal_deduction_decimal": "245199"
},
"reduce_price_format": "Saving 206.190₫",
"sale_price_decimal": "403009",
"sale_price_decimal_part_format": "",
"sale_price_format": "403.009",
"sale_price_integer_part_format": "403.009",
"show_currency_space": false,
"single_product_price_decimal": "426440",
"single_product_price_format": "426.440",
"sku_id": "1733538161588143503",
"symbol_position": 0
},
"rate_info": {
"review_count": "5",
"score": 4.6
},
"sold_info": {
"sold_count": 55
}
}VND价格的原始字符串是403009,展示字符串是403.009,不能据此读成美元403.009。展示分隔符不应替代币种和数值语义。评价数量是字符串,sold_count是数值;字段类型、观察时间与币种需要跟着结果保存,缺失仍记未知。这个样本的品牌名与店铺名并不相同,仅靠一个名字无法认证所有权或正品。
详情保存记录 de2e3154-e9a3-4cdd-bfb4-6da5d2ec8e44 比它早几秒,时间为10月7日17:37:27.639 UTC,请求商品1731581114818794403、地区GB。完整业务对象如下:
{
"message": "GB 地区暂不支持,请选择 supported_regions 中的地区 / GB is temporarily unavailable; choose one of supported_regions",
"region": "GB",
"region_supported": false,
"supported_regions": [
"ID",
"JP",
"MX",
"MY",
"PH",
"SG",
"TH",
"US",
"VN"
]
}这里没有code、data和商品对象。参数说明包含GB,负面样本却排除了GB,并新增JP/MX。这一冲突没有被本次修订解决,两份来源都保留。不能把旧拒绝写成永久禁用,也不能把建议地区列表当成同一商品在那些市场存在的证据。实际遇到拒绝就停,不要偷偷轮流换地区尝试。
首屏结果不能直接变成选品结论
当前VN样本明确has_more为false。另一份无日期README是US/coffee的独立片段,显示has_more为true、offset30和非空token,不是VN记录的续页。如果以后需要分页,必须看到实际has_more为true,并取得有效的返回offset和page_token,同时保持关键词与地区不变。不要本地固定加30,不要把api_source加进请求,也不要跨市场复用token。本次没有执行续页。
合法空商品数组只说明这次请求返回空样本,不等于市场没有需求。旧实验确实碰过间歇空页,但这不能自动授权重试。按sold_count排序也只是在排序已返回的卡片,不是确定全站畅销榜。累计售出计数不能直接推导日销量、收入、市场份额或选品成功率;额外商业判断需要相应的数据与方法。
旧10月1日实验如何保留
完整中文历史稿及代码保留原六段Python、下面的JSON、十三个旧运行ID及完整观察。旧helper兼容顶层output、自动重试、缺失值转零的写法仅作存档。str(None)不是商品ID,缺少销量也不是销量为零。
当时范围是两个美国关键词和少数SG/MY搜索,记录了US间歇空页、search-v2嵌套空结果及SG上游400、v1详情缺字段、US v2详情成功、v3与分类接口反复失败,以及有限实验内的US详情/评论成功和店铺游标读取。这些都带日期,不是对当前版本或所有地区的认证。
旧搜索两页各30条且未重叠,七次调用报告汇总60条、27%零销量、24.95美元咖啡卡片及219808累计售出、4.7评分。店铺样本还包含1377502售出的胶原蛋白产品。旧代码把缺失销量也归为零,会影响那个百分比;样本中的最大计数不等于市场第一,也不能据此断言品牌真伪、类目机会或商家主营收入。
以下原始JSON逐字保留:
{
"has_more": true,
"load_more_params": {"api_source": 2, "offset": 30, "page_token": "20261001031049DC4BD36BAFE739165F2A"},
"products": [
{
"product_id": "1729385057785057965",
"title": "Micro Ingredients Organic Instant 10 in 1 Mushroom Coffee Powder",
"brand_info": {"brand_name": "Micro Ingredients"},
"sold_info": {"sold_count": 219808},
"rate_info": {"review_count": "28866", "score": 4.7},
"product_price_info": {
"currency_name": "USD",
"sale_price_decimal": "24.95",
"origin_price_decimal": "27.95"
},
"seller_info": {"seller_id": "7494949083499694765", "shop_name": "Micro Ingredients"}
}
]
}旧详情记录还出现25363个五星、1195个一星、29017评价,而另一张卡片是28866;不同调用不是同一时点。另一个商品响应超过1MB。旧布局没有返回自身标题与价格,也仅是当时观察,不是以后所有详情的保证。
历史 product-reviews-v2 参数页,显示page_start和筛选参数,生成data为空。评论读取属于已归档链路,本次没有复验或调用这一接口。
历史稿还保留了两页评论、未能确认作用的星级筛选、两页店铺目录和完整商品链接解析;短链接当时没有测试。将这些能力恢复到项目之前,要分别复验契约与预算。做商品研究通常也不需要把评论人的姓名和头像带入模型。
历史 seller-products-list 参数页,含seller_id与search_params。空的生成响应不能证明现在能读取店铺或继续翻页;该独立端点不在新示例中调用。
常见问题
completed就是详情成功吗? 不是。先读取业务对象,处理地区拒绝,再谈成功数据;传输完成与获得可用商品是两件事。
空结果可以让agent自动再试吗? 本文会停止。重试需要独立的理由和预算,旧的间歇空页观察不能当成无限循环的依据。
GB、JP、MX现在能用吗? 参数说明和保存的负面样本有冲突,本次没有得到新的当前可用性结论。根据实际选定请求的返回处理,不擅自换市场。
旧选品报告还能直接运行吗? 代码和观察留作审计,重新投入使用前应复验评论、店铺、ID选择和缺失值处理,不能靠旧成功记录替代这些步骤。
其他能力可继续看 TikTok接口导航与创作者研究教程。先把一个任务的市场、原始字段和证据日期保存清楚,再决定是否扩展。
2026 年 SandBase TikTok 枢纽的标价,见 2026 年最佳 TikTok API:价格对比。
觉得有用?分享给更多人