TikTok Shop商品搜索 API (V1)
接口健康状态
健康 可用 少量可用 基本不可用 暂无数据
正在加载健康状态…
在选定区域内通过关键词搜索 TikTok Shop 商品,提供偏移和页面令牌分页。使用该接口发现区域商品并继续浏览搜索结果。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
token | query | string | 是 | - | 此API服务的鉴权令牌。 |
keyword | query | string | 是 | - | 搜索关键词。 |
region | query | string | 否 | US | 商品搜索的目标区域。 可选值: - US:美国- GB:英国- FR:法国- SG:新加坡- MY:马来西亚- PH:菲律宾- TH:泰国- VN:越南- ID:印度尼西亚 |
offset | query | integer | 否 | 0 | 搜索结果偏移量。 |
pageToken | query | string | 否 | - | 下一页的分页令牌。 |
代码示例
bash
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE'text
我想使用 JustOneAPI 提供的“商品搜索 (V1)”接口。
接入地址: https://api.justoneapi.com。
接口路径: /api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE
接口地址: BASE_URL + /api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE
HTTP 方法: GET
身份验证: 在 URL 中传入 token 查询参数。
OpenAPI 定义: https://docs.justoneapi.com/openapi/tiktok-shop/product-search-v1-zh.json
请求参数说明:
- token (query): 此API服务的鉴权令牌。 (必填)
- keyword (query): 搜索关键词。 (必填)
- region (query): 商品搜索的目标区域。
可选值:
- `US`:美国
- `GB`:英国
- `FR`:法国
- `SG`:新加坡
- `MY`:马来西亚
- `PH`:菲律宾
- `TH`:泰国
- `VN`:越南
- `ID`:印度尼西亚
- offset (query): 搜索结果偏移量。
- pageToken (query): 下一页的分页令牌。
返回格式: 请根据实际 Content-Type 安全处理 JSON 或文本响应。
响应处理与错误码:
1. 需通过返回体中的 "code" 字段判断业务结果(code 为 0 表示成功)。
2. 超时建议:建议将请求超时时间设置为 120 秒;如果 120 秒偏长,请至少设置为 60 秒,但可能会有少量请求因超时而未接收到结果。
3. 业务码说明:
- 0: 成功
- 100: Token 无效或已失效
- 301: 采集失败,请重试
- 302: 超出速率限制
- 303: 超出每日配额
- 400: 参数错误
- 500: 内部服务器错误
- 600: 权限不足
- 601: 账户余额不足
- 602: TOKEN 限额超限
4. code 601 表示账户共享余额不足。code 602 表示当前 API TOKEN 自身的累计消费上限已达到。TOKEN 限额不是资金划拨,多个 TOKEN 仍共享同一个账户余额。
请帮我用我擅长的编程语言写一个脚本来调用这个接口,并处理返回结果。python
import requests
BASE_URL = "https://api.justoneapi.com" # 由 OpenAPI servers 提供
url = BASE_URL + "/api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE"
response = requests.get(url, timeout=120)
print(response.status_code)
if response.content:
content_type = response.headers.get("content-type", "").lower()
if "json" in content_type:
try:
print(response.json())
except ValueError:
print(response.text)
elif content_type.startswith("text/") or "xml" in content_type or content_type.split(";", 1)[0].strip() in {"application/javascript", "application/x-www-form-urlencoded", "application/graphql"}:
print(response.text)
else:
with open("response.bin", "wb") as output:
output.write(response.content)
print(f"Saved {len(response.content)} bytes to response.bin")js
const BASE_URL = "https://api.justoneapi.com"; // 由 OpenAPI servers 提供
const url = BASE_URL + "/api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE";
const response = await fetch(url, {
method: "GET",
signal: AbortSignal.timeout(120000)
});
console.log(response.status);
const responseBytes = await response.arrayBuffer();
if (responseBytes.byteLength) {
const contentType = (response.headers.get("content-type") || "").toLowerCase();
const mediaType = contentType.split(";", 1)[0].trim();
const textual = contentType.startsWith("text/") || contentType.includes("json") || contentType.includes("xml") || ["application/javascript", "application/x-www-form-urlencoded", "application/graphql"].includes(mediaType);
if (textual) {
const responseText = new TextDecoder().decode(responseBytes);
let data = responseText;
if (contentType.includes("json")) {
try { data = JSON.parse(responseText); } catch { /* Keep the raw body. */ }
}
console.log(data);
} else {
console.log(`Received ${responseBytes.byteLength} binary bytes`);
}
}java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
public class Main {
public static void main(String[] args) throws Exception {
final String BASE_URL = "https://api.justoneapi.com"; // 由 OpenAPI servers 提供
final String url = BASE_URL + "/api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE";
HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(120)).build();
HttpRequest.Builder builder = HttpRequest.newBuilder()
.uri(URI.create(url))
.timeout(Duration.ofSeconds(120))
.method("GET", HttpRequest.BodyPublishers.noBody());
HttpRequest request = builder.build();
HttpResponse<byte[]> response = client.send(request, HttpResponse.BodyHandlers.ofByteArray());
System.out.println(response.statusCode());
String contentType = response.headers().firstValue("content-type").orElse("").toLowerCase();
String mediaType = contentType.split(";", 2)[0].trim();
if (contentType.startsWith("text/") || contentType.contains("json") || contentType.contains("xml") || mediaType.equals("application/javascript") || mediaType.equals("application/x-www-form-urlencoded") || mediaType.equals("application/graphql")) {
System.out.println(new String(response.body(), StandardCharsets.UTF_8));
} else {
Files.write(Path.of("response.bin"), response.body());
System.out.println("Saved " + response.body().length + " bytes to response.bin");
}
}
}go
package main
import (
"fmt"
"io"
"os"
"strings"
"net/http"
"time"
)
const BASE_URL = "https://api.justoneapi.com" // 由 OpenAPI servers 提供
func main() {
client := &http.Client{Timeout: 120 * time.Second}
url := BASE_URL + "/api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE"
req, _ := http.NewRequest("GET", url, nil)
resp, _ := client.Do(req)
defer resp.Body.Close()
fmt.Println(resp.StatusCode)
bodyBytes, _ := io.ReadAll(resp.Body)
contentType := strings.ToLower(resp.Header.Get("Content-Type"))
mediaType := strings.TrimSpace(strings.SplitN(contentType, ";", 2)[0])
if strings.HasPrefix(contentType, "text/") || strings.Contains(contentType, "json") || strings.Contains(contentType, "xml") || mediaType == "application/javascript" || mediaType == "application/x-www-form-urlencoded" || mediaType == "application/graphql" {
fmt.Println(string(bodyBytes))
} else {
os.WriteFile("response.bin", bodyBytes, 0600)
fmt.Printf("Saved %d bytes to response.bin\n", len(bodyBytes))
}
}php
<?php
$BASE_URL = 'https://api.justoneapi.com'; // 由 OpenAPI servers 提供
$url = $BASE_URL . '/api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$contentType = strtolower((string) curl_getinfo($ch, CURLINFO_CONTENT_TYPE));
curl_close($ch);
echo $status . PHP_EOL;
$mediaType = trim(explode(';', $contentType, 2)[0]);
if (str_starts_with($contentType, 'text/') || str_contains($contentType, 'json') || str_contains($contentType, 'xml') || in_array($mediaType, ['application/javascript', 'application/x-www-form-urlencoded', 'application/graphql'], true)) {
echo $response;
} else {
file_put_contents('response.bin', $response);
echo 'Saved ' . strlen($response) . ' bytes to response.bin' . PHP_EOL;
}返回字段
业务成功时(code = 0)的主要返回字段。
结果与续页9 个字段
data
TikTok Shop 搜索结果及其状态信息。
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | TikTok Shop 返回的内层状态码。 |
message | string | TikTok Shop 返回的内层状态消息。 |
data | object | 本页返回的商品、店铺和搜索信息。 |
data.has_more | boolean | 回包是否报告还有更多搜索结果。 |
data.load_more_params | object | 下一次搜索请求使用的续页参数。 |
data.load_more_params.offset | integer | 回包为下一页提供的偏移量。续页时用同一关键词和地区,将它作为 offset 传入。 |
data.load_more_params.page_token | string | 搜索返回的续页值。续页时将它原样作为 pageToken 与返回的 offset 一同传入。 |
data.products | array | 本页返回的商品条目列表。 |
data.shops | array | 搜索结果中单独返回的店铺列表。 |
商品概览12 个字段
data.data.products[]
搜索结果中的一项商品。
| 字段 | 类型 | 说明 |
|---|---|---|
product_id | string | 以文本返回的 TikTok Shop 商品标识。 |
title | string | 接口返回的商品标题。 |
rate_info | object | 有提供时表示接口返回的商品评分信息。 |
rate_info.score | number | 以数值返回的商品评分。 |
rate_info.review_count | string | 以展示文本返回的商品评价数。 |
sold_info | object | 随商品条目返回的销量信息。 |
sold_info.sold_count | integer | 接口返回的商品售出数量。 |
brand_info | object | 有提供时表示接口返回的商品品牌信息。 |
brand_info.brand_name | string | 商品返回的品牌名称。 |
seo_url | object | 随商品条目返回的商品页面链接信息。 |
seo_url.canonical_url | string | 接口返回的商品规范页面链接。 |
seo_url.slug | string | 随商品规范链接返回的页面别名。 |
商品价格25 个字段
data.data.products[]
| 字段 | 类型 | 说明 |
|---|---|---|
product_price_info | object | 随商品条目返回的价格信息。 |
product_price_info.price_prefix | string | 有提供时显示在价格前面的文本。 |
product_price_info.sku_id | string | 接口返回的此价格所关联的 SKU 标识。 |
product_price_info.symbol_position | integer | 接口返回的货币符号位置代码。 |
product_price_info.show_currency_space | boolean | 价格显示格式是否要求在货币符号旁加空格。 |
product_price_info.currency_show_mode | integer | 随价格返回的币种展示模式代码。 |
product_price_info.currency_name | string | 随价格返回的币种标识。 |
product_price_info.currency_symbol | string | 随价格返回的货币符号。 |
product_price_info.sale_price_decimal | string | 以十进制文本返回的销售价金额。 |
product_price_info.sale_price_format | string | 格式化后的销售价展示文本。 |
product_price_info.single_product_price_format | string | 格式化后的单件商品价格展示文本。 |
product_price_info.single_product_price_decimal | string | 以十进制文本返回的单件商品价格金额。 |
product_price_info.sale_price_integer_part_format | string | 销售价展示文本中格式化后的整数部分。 |
product_price_info.sale_price_decimal_part_format | string | 销售价展示文本中格式化后的小数部分。 |
product_price_info.decimal_point_symbol | string | 接口返回的价格展示格式小数分隔符。 |
product_price_info.promotion_deduction_details | object | 随价格返回的促销抵扣信息。 |
product_price_info.promotion_deduction_details.seller_subtotal_deduction | string | 促销信息中返回的卖家小计抵扣展示文本。 |
product_price_info.promotion_deduction_details.seller_subtotal_deduction_decimal | string | 以十进制文本返回的卖家小计抵扣金额。 |
product_price_info.raw_origin_price_decimal | string | 以十进制文本返回的原始原价金额。 |
product_price_info.raw_origin_price_format | string | 原始原价的格式化展示文本。 |
product_price_info.origin_price_decimal | string | 有提供时以十进制文本返回的原价金额。 |
product_price_info.origin_price_format | string | 接口返回的原价格式化展示文本。 |
product_price_info.discount_format | string | 格式化后的折扣展示文本。 |
product_price_info.discount_decimal | string | 以十进制文本返回的折扣值。 |
product_price_info.reduce_price_format | string | 接口返回的降价金额格式化展示文本。 |
SKU 价格27 个字段
data.data.products[]
| 字段 | 类型 | 说明 |
|---|---|---|
sku_info | array | 此商品返回的 SKU 价格条目列表。 |
sku_info[] | object | 此商品的一项 SKU 价格记录。 |
sku_info[].SkuId | string | 价格记录返回的 SKU 标识。 |
sku_info[].PriceInfo | object | 接口返回的 SKU 价格信息。 |
sku_info[].PriceInfo.sku_id | string | 接口返回的此价格所关联的 SKU 标识。 |
sku_info[].PriceInfo.symbol_position | integer | 接口返回的货币符号位置代码。 |
sku_info[].PriceInfo.show_currency_space | boolean | 价格显示格式是否要求在货币符号旁加空格。 |
sku_info[].PriceInfo.currency_show_mode | integer | 随价格返回的币种展示模式代码。 |
sku_info[].PriceInfo.currency_name | string | 随价格返回的币种标识。 |
sku_info[].PriceInfo.currency_symbol | string | 随价格返回的货币符号。 |
sku_info[].PriceInfo.sale_price_decimal | string | 以十进制文本返回的销售价金额。 |
sku_info[].PriceInfo.sale_price_format | string | 格式化后的销售价展示文本。 |
sku_info[].PriceInfo.single_product_price_format | string | 格式化后的单件商品价格展示文本。 |
sku_info[].PriceInfo.single_product_price_decimal | string | 以十进制文本返回的单件商品价格金额。 |
sku_info[].PriceInfo.sale_price_integer_part_format | string | 销售价展示文本中格式化后的整数部分。 |
sku_info[].PriceInfo.sale_price_decimal_part_format | string | 销售价展示文本中格式化后的小数部分。 |
sku_info[].PriceInfo.decimal_point_symbol | string | 接口返回的价格展示格式小数分隔符。 |
sku_info[].PriceInfo.promotion_deduction_details | object | 随价格返回的促销抵扣信息。 |
sku_info[].PriceInfo.promotion_deduction_details.seller_subtotal_deduction | string | 促销信息中返回的卖家小计抵扣展示文本。 |
sku_info[].PriceInfo.promotion_deduction_details.seller_subtotal_deduction_decimal | string | 以十进制文本返回的卖家小计抵扣金额。 |
sku_info[].PriceInfo.raw_origin_price_decimal | string | 以十进制文本返回的原始原价金额。 |
sku_info[].PriceInfo.raw_origin_price_format | string | 原始原价的格式化展示文本。 |
sku_info[].PriceInfo.origin_price_decimal | string | 有提供时以十进制文本返回的原价金额。 |
sku_info[].PriceInfo.origin_price_format | string | 接口返回的原价格式化展示文本。 |
sku_info[].PriceInfo.discount_format | string | 格式化后的折扣展示文本。 |
sku_info[].PriceInfo.discount_decimal | string | 以十进制文本返回的折扣值。 |
sku_info[].PriceInfo.reduce_price_format | string | 接口返回的降价金额格式化展示文本。 |
商品卖家22 个字段
data.data.products[]
| 字段 | 类型 | 说明 |
|---|---|---|
seller_info | object | 随商品返回的卖家信息。 |
seller_info.seller_id | string | 以文本返回的 TikTok Shop 卖家标识。 |
seller_info.shop_name | string | 接口返回的店铺显示名称。 |
seller_info.store_blueV_label | object | 接口返回的店铺蓝色认证标志图像。 |
seller_info.store_blueV_label.label_image_light | object | 浅色模式的认证标志图片。 |
seller_info.store_blueV_label.label_image_light.height | integer | 返回的图片高度。 |
seller_info.store_blueV_label.label_image_light.width | integer | 返回的图片宽度。 |
seller_info.store_blueV_label.label_image_light.uri | string | 随图片信息返回的 URI。 |
seller_info.store_blueV_label.label_image_light.url_list | array | 接口返回的图片可用链接列表。 |
seller_info.store_blueV_label.label_image_light.url_list[] | string | 接口为图片返回的一条链接。 |
seller_info.store_blueV_label.label_image_dark | object | 深色模式的认证标志图片。 |
seller_info.store_blueV_label.label_image_dark.height | integer | 返回的图片高度。 |
seller_info.store_blueV_label.label_image_dark.width | integer | 返回的图片宽度。 |
seller_info.store_blueV_label.label_image_dark.uri | string | 随图片信息返回的 URI。 |
seller_info.store_blueV_label.label_image_dark.url_list | array | 接口返回的图片可用链接列表。 |
seller_info.store_blueV_label.label_image_dark.url_list[] | string | 接口为图片返回的一条链接。 |
seller_info.shop_logo | object | 店铺标志图片信息。 |
seller_info.shop_logo.height | integer | 返回的图片高度。 |
seller_info.shop_logo.width | integer | 返回的图片宽度。 |
seller_info.shop_logo.uri | string | 随图片信息返回的 URI。 |
seller_info.shop_logo.url_list | array | 接口返回的图片可用链接列表。 |
seller_info.shop_logo.url_list[] | string | 接口为图片返回的一条链接。 |
店铺搜索结果21 个字段
data.data.shops[]
搜索结果中的一家店铺。
| 字段 | 类型 | 说明 |
|---|---|---|
seller_id | string | 以文本返回的 TikTok Shop 卖家标识。 |
shop_name | string | 接口返回的店铺显示名称。 |
store_blueV_label | object | 接口返回的店铺蓝色认证标志图像。 |
store_blueV_label.label_image_light | object | 浅色模式的认证标志图片。 |
store_blueV_label.label_image_light.height | integer | 返回的图片高度。 |
store_blueV_label.label_image_light.width | integer | 返回的图片宽度。 |
store_blueV_label.label_image_light.uri | string | 随图片信息返回的 URI。 |
store_blueV_label.label_image_light.url_list | array | 接口返回的图片可用链接列表。 |
store_blueV_label.label_image_light.url_list[] | string | 接口为图片返回的一条链接。 |
store_blueV_label.label_image_dark | object | 深色模式的认证标志图片。 |
store_blueV_label.label_image_dark.height | integer | 返回的图片高度。 |
store_blueV_label.label_image_dark.width | integer | 返回的图片宽度。 |
store_blueV_label.label_image_dark.uri | string | 随图片信息返回的 URI。 |
store_blueV_label.label_image_dark.url_list | array | 接口返回的图片可用链接列表。 |
store_blueV_label.label_image_dark.url_list[] | string | 接口为图片返回的一条链接。 |
shop_logo | object | 店铺标志图片信息。 |
shop_logo.height | integer | 返回的图片高度。 |
shop_logo.width | integer | 返回的图片宽度。 |
shop_logo.uri | string | 随图片信息返回的 URI。 |
shop_logo.url_list | array | 接口返回的图片可用链接列表。 |
shop_logo.url_list[] | string | 接口为图片返回的一条链接。 |
商品图片12 个字段
data.data.products[]
| 字段 | 类型 | 说明 |
|---|---|---|
image | object | 接口返回的商品主图信息。 |
image.height | integer | 返回的图片高度。 |
image.width | integer | 返回的图片宽度。 |
image.uri | string | 随图片信息返回的 URI。 |
image.url_list | array | 接口返回的图片可用链接列表。 |
image.url_list[] | string | 接口为图片返回的一条链接。 |
transparent_image | object | 接口返回的商品透明图片信息。 |
transparent_image.height | integer | 返回的图片高度。 |
transparent_image.width | integer | 返回的图片宽度。 |
transparent_image.uri | string | 随图片信息返回的 URI。 |
transparent_image.url_list | array | 接口返回的图片可用链接列表。 |
transparent_image.url_list[] | string | 接口为图片返回的一条链接。 |
营销标签11 个字段
data.data.products[]
| 字段 | 类型 | 说明 |
|---|---|---|
product_marketing_info | object | 随商品返回的营销展示信息。 |
product_marketing_info.placement_labels_ui | object | 商品营销标签的展示分组。 |
product_marketing_info.placement_labels_ui.ui_list | array | 接口返回的商品营销标签展示分组列表。 |
product_marketing_info.placement_labels_ui.ui_list[] | object | 结果中的一项营销标签分组。 |
product_marketing_info.placement_labels_ui.ui_list[].placement | integer | 接口返回的营销标签分组展示位置代码。 |
product_marketing_info.placement_labels_ui.ui_list[].labels | array | 这个展示分组中返回的营销标签列表。 |
product_marketing_info.placement_labels_ui.ui_list[].labels[] | object | 展示分组中的一个营销标签。 |
product_marketing_info.placement_labels_ui.ui_list[].labels[].meta | object | 接口返回的营销标签信息。 |
product_marketing_info.placement_labels_ui.ui_list[].labels[].meta.label_type | string | 接口返回的营销标签类型。 |
product_marketing_info.placement_labels_ui.ui_list[].labels[].lom | object | 接口返回的营销标签展示内容。 |
product_marketing_info.placement_labels_ui.ui_list[].labels[].lom.value | string | 接口返回的营销标签展示值。 |
筛选分组22 个字段
data.data
| 字段 | 类型 | 说明 |
|---|---|---|
filter_sections | array | 有提供时表示搜索结果中的筛选分组。 |
filter_sections[] | object | 搜索结果中的一个筛选分组。 |
filter_sections[].id | string | 筛选分组的标识。 |
filter_sections[].title | string | 筛选分组的显示标题。 |
filter_sections[].filterGroupType | integer | 接口返回的筛选分组类型代码。 |
filter_sections[].type | string | 接口返回的筛选分组类型标签。 |
filter_sections[].options | object | 以显示名称为键的筛选选项标识映射。 |
filter_sections[].options.{key} | string | 作为键的显示名称所对应的筛选选项标识。 |
filter_sections[].hasAllOption | boolean | 筛选分组是否标记为包含全部选项。 |
filter_sections[].isColorSection | boolean | 筛选分组是否标记为颜色筛选。 |
filter_sections[].optionGroups | array | 有提供时表示这个筛选分组内的选项子组。 |
filter_sections[].optionGroups[] | object | 一个筛选选项子组。 |
filter_sections[].optionGroups[].title | string | 筛选选项子组的显示标题。 |
filter_sections[].optionGroups[].options | object | 以显示名称为键的筛选选项标识映射。 |
filter_sections[].optionGroups[].options.{key} | string | 作为键的显示名称所对应的筛选选项标识。 |
filter_sections[].optionGroups[].hasAllOption | boolean | 选项子组是否标记为包含全部选项。 |
filter_sections[].isPriceRange | boolean | 筛选分组是否标记为价格区间筛选。 |
filter_sections[].showCustomPriceInput | boolean | 价格筛选是否标记为展示自定义输入。 |
filter_sections[].priceRangeInputInfo | object | 价格区间筛选的展示边界和币种。 |
filter_sections[].priceRangeInputInfo.minDisplay | string | 以展示文本返回的价格下限。 |
filter_sections[].priceRangeInputInfo.maxDisplay | string | 以展示文本返回的价格上限。 |
filter_sections[].priceRangeInputInfo.currency | string | 接口返回的价格区间筛选币种。 |
快捷筛选6 个字段
data.data
| 字段 | 类型 | 说明 |
|---|---|---|
filter_quick_options | array | 有提供时表示回包返回的快捷筛选选项列表。 |
filter_quick_options[] | object | 一个快捷筛选选项。 |
filter_quick_options[].displayName | string | 快捷筛选选项的显示名称。 |
filter_quick_options[].sectionTitle | string | 快捷筛选选项所属分组的显示标题。 |
filter_quick_options[].filterOptionId | string | 快捷筛选选项的标识。 |
filter_quick_options[].filterGroupType | integer | 接口返回的快捷筛选选项所属分组类型代码。 |
响应示例
正在加载响应示例…