Skip to content

TikTok Shop商品搜索 API (V1) ​

GET
接口健康状态
健康 可用 少量可用 基本不可用 暂无数据
正在加载健康状态…

在选定区域内通过关键词搜索 TikTok Shop 商品,提供偏移和页面令牌分页。使用该接口发现区域商品并继续浏览搜索结果。

请求参数 ​

参数名位置类型必填默认值说明
tokenquerystring是-此API服务的鉴权令牌。
keywordquerystring是-搜索关键词。
regionquerystring否US商品搜索的目标区域。


可选值:

- US:美国

- GB:英国

- FR:法国

- SG:新加坡

- MY:马来西亚

- PH:菲律宾

- TH:泰国

- VN:越南

- ID:印度尼西亚
offsetqueryinteger否0搜索结果偏移量。
pageTokenquerystring否-下一页的分页令牌。

代码示例 ​

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 搜索结果及其状态信息。

字段类型说明
codeintegerTikTok Shop 返回的内层状态码。
messagestringTikTok Shop 返回的内层状态消息。
dataobject本页返回的商品、店铺和搜索信息。
data.has_moreboolean回包是否报告还有更多搜索结果。
data.load_more_paramsobject下一次搜索请求使用的续页参数。
data.load_more_params.offsetinteger回包为下一页提供的偏移量。续页时用同一关键词和地区,将它作为 offset 传入。
data.load_more_params.page_tokenstring搜索返回的续页值。续页时将它原样作为 pageToken 与返回的 offset 一同传入。
data.productsarray本页返回的商品条目列表。
data.shopsarray搜索结果中单独返回的店铺列表。
商品概览12 个字段

data.data.products[]

搜索结果中的一项商品。

字段类型说明
product_idstring以文本返回的 TikTok Shop 商品标识。
titlestring接口返回的商品标题。
rate_infoobject有提供时表示接口返回的商品评分信息。
rate_info.scorenumber以数值返回的商品评分。
rate_info.review_countstring以展示文本返回的商品评价数。
sold_infoobject随商品条目返回的销量信息。
sold_info.sold_countinteger接口返回的商品售出数量。
brand_infoobject有提供时表示接口返回的商品品牌信息。
brand_info.brand_namestring商品返回的品牌名称。
seo_urlobject随商品条目返回的商品页面链接信息。
seo_url.canonical_urlstring接口返回的商品规范页面链接。
seo_url.slugstring随商品规范链接返回的页面别名。
商品价格25 个字段

data.data.products[]

字段类型说明
product_price_infoobject随商品条目返回的价格信息。
product_price_info.price_prefixstring有提供时显示在价格前面的文本。
product_price_info.sku_idstring接口返回的此价格所关联的 SKU 标识。
product_price_info.symbol_positioninteger接口返回的货币符号位置代码。
product_price_info.show_currency_spaceboolean价格显示格式是否要求在货币符号旁加空格。
product_price_info.currency_show_modeinteger随价格返回的币种展示模式代码。
product_price_info.currency_namestring随价格返回的币种标识。
product_price_info.currency_symbolstring随价格返回的货币符号。
product_price_info.sale_price_decimalstring以十进制文本返回的销售价金额。
product_price_info.sale_price_formatstring格式化后的销售价展示文本。
product_price_info.single_product_price_formatstring格式化后的单件商品价格展示文本。
product_price_info.single_product_price_decimalstring以十进制文本返回的单件商品价格金额。
product_price_info.sale_price_integer_part_formatstring销售价展示文本中格式化后的整数部分。
product_price_info.sale_price_decimal_part_formatstring销售价展示文本中格式化后的小数部分。
product_price_info.decimal_point_symbolstring接口返回的价格展示格式小数分隔符。
product_price_info.promotion_deduction_detailsobject随价格返回的促销抵扣信息。
product_price_info.promotion_deduction_details.seller_subtotal_deductionstring促销信息中返回的卖家小计抵扣展示文本。
product_price_info.promotion_deduction_details.seller_subtotal_deduction_decimalstring以十进制文本返回的卖家小计抵扣金额。
product_price_info.raw_origin_price_decimalstring以十进制文本返回的原始原价金额。
product_price_info.raw_origin_price_formatstring原始原价的格式化展示文本。
product_price_info.origin_price_decimalstring有提供时以十进制文本返回的原价金额。
product_price_info.origin_price_formatstring接口返回的原价格式化展示文本。
product_price_info.discount_formatstring格式化后的折扣展示文本。
product_price_info.discount_decimalstring以十进制文本返回的折扣值。
product_price_info.reduce_price_formatstring接口返回的降价金额格式化展示文本。
SKU 价格27 个字段

data.data.products[]

字段类型说明
sku_infoarray此商品返回的 SKU 价格条目列表。
sku_info[]object此商品的一项 SKU 价格记录。
sku_info[].SkuIdstring价格记录返回的 SKU 标识。
sku_info[].PriceInfoobject接口返回的 SKU 价格信息。
sku_info[].PriceInfo.sku_idstring接口返回的此价格所关联的 SKU 标识。
sku_info[].PriceInfo.symbol_positioninteger接口返回的货币符号位置代码。
sku_info[].PriceInfo.show_currency_spaceboolean价格显示格式是否要求在货币符号旁加空格。
sku_info[].PriceInfo.currency_show_modeinteger随价格返回的币种展示模式代码。
sku_info[].PriceInfo.currency_namestring随价格返回的币种标识。
sku_info[].PriceInfo.currency_symbolstring随价格返回的货币符号。
sku_info[].PriceInfo.sale_price_decimalstring以十进制文本返回的销售价金额。
sku_info[].PriceInfo.sale_price_formatstring格式化后的销售价展示文本。
sku_info[].PriceInfo.single_product_price_formatstring格式化后的单件商品价格展示文本。
sku_info[].PriceInfo.single_product_price_decimalstring以十进制文本返回的单件商品价格金额。
sku_info[].PriceInfo.sale_price_integer_part_formatstring销售价展示文本中格式化后的整数部分。
sku_info[].PriceInfo.sale_price_decimal_part_formatstring销售价展示文本中格式化后的小数部分。
sku_info[].PriceInfo.decimal_point_symbolstring接口返回的价格展示格式小数分隔符。
sku_info[].PriceInfo.promotion_deduction_detailsobject随价格返回的促销抵扣信息。
sku_info[].PriceInfo.promotion_deduction_details.seller_subtotal_deductionstring促销信息中返回的卖家小计抵扣展示文本。
sku_info[].PriceInfo.promotion_deduction_details.seller_subtotal_deduction_decimalstring以十进制文本返回的卖家小计抵扣金额。
sku_info[].PriceInfo.raw_origin_price_decimalstring以十进制文本返回的原始原价金额。
sku_info[].PriceInfo.raw_origin_price_formatstring原始原价的格式化展示文本。
sku_info[].PriceInfo.origin_price_decimalstring有提供时以十进制文本返回的原价金额。
sku_info[].PriceInfo.origin_price_formatstring接口返回的原价格式化展示文本。
sku_info[].PriceInfo.discount_formatstring格式化后的折扣展示文本。
sku_info[].PriceInfo.discount_decimalstring以十进制文本返回的折扣值。
sku_info[].PriceInfo.reduce_price_formatstring接口返回的降价金额格式化展示文本。
商品卖家22 个字段

data.data.products[]

字段类型说明
seller_infoobject随商品返回的卖家信息。
seller_info.seller_idstring以文本返回的 TikTok Shop 卖家标识。
seller_info.shop_namestring接口返回的店铺显示名称。
seller_info.store_blueV_labelobject接口返回的店铺蓝色认证标志图像。
seller_info.store_blueV_label.label_image_lightobject浅色模式的认证标志图片。
seller_info.store_blueV_label.label_image_light.heightinteger返回的图片高度。
seller_info.store_blueV_label.label_image_light.widthinteger返回的图片宽度。
seller_info.store_blueV_label.label_image_light.uristring随图片信息返回的 URI。
seller_info.store_blueV_label.label_image_light.url_listarray接口返回的图片可用链接列表。
seller_info.store_blueV_label.label_image_light.url_list[]string接口为图片返回的一条链接。
seller_info.store_blueV_label.label_image_darkobject深色模式的认证标志图片。
seller_info.store_blueV_label.label_image_dark.heightinteger返回的图片高度。
seller_info.store_blueV_label.label_image_dark.widthinteger返回的图片宽度。
seller_info.store_blueV_label.label_image_dark.uristring随图片信息返回的 URI。
seller_info.store_blueV_label.label_image_dark.url_listarray接口返回的图片可用链接列表。
seller_info.store_blueV_label.label_image_dark.url_list[]string接口为图片返回的一条链接。
seller_info.shop_logoobject店铺标志图片信息。
seller_info.shop_logo.heightinteger返回的图片高度。
seller_info.shop_logo.widthinteger返回的图片宽度。
seller_info.shop_logo.uristring随图片信息返回的 URI。
seller_info.shop_logo.url_listarray接口返回的图片可用链接列表。
seller_info.shop_logo.url_list[]string接口为图片返回的一条链接。
店铺搜索结果21 个字段

data.data.shops[]

搜索结果中的一家店铺。

字段类型说明
seller_idstring以文本返回的 TikTok Shop 卖家标识。
shop_namestring接口返回的店铺显示名称。
store_blueV_labelobject接口返回的店铺蓝色认证标志图像。
store_blueV_label.label_image_lightobject浅色模式的认证标志图片。
store_blueV_label.label_image_light.heightinteger返回的图片高度。
store_blueV_label.label_image_light.widthinteger返回的图片宽度。
store_blueV_label.label_image_light.uristring随图片信息返回的 URI。
store_blueV_label.label_image_light.url_listarray接口返回的图片可用链接列表。
store_blueV_label.label_image_light.url_list[]string接口为图片返回的一条链接。
store_blueV_label.label_image_darkobject深色模式的认证标志图片。
store_blueV_label.label_image_dark.heightinteger返回的图片高度。
store_blueV_label.label_image_dark.widthinteger返回的图片宽度。
store_blueV_label.label_image_dark.uristring随图片信息返回的 URI。
store_blueV_label.label_image_dark.url_listarray接口返回的图片可用链接列表。
store_blueV_label.label_image_dark.url_list[]string接口为图片返回的一条链接。
shop_logoobject店铺标志图片信息。
shop_logo.heightinteger返回的图片高度。
shop_logo.widthinteger返回的图片宽度。
shop_logo.uristring随图片信息返回的 URI。
shop_logo.url_listarray接口返回的图片可用链接列表。
shop_logo.url_list[]string接口为图片返回的一条链接。
商品图片12 个字段

data.data.products[]

字段类型说明
imageobject接口返回的商品主图信息。
image.heightinteger返回的图片高度。
image.widthinteger返回的图片宽度。
image.uristring随图片信息返回的 URI。
image.url_listarray接口返回的图片可用链接列表。
image.url_list[]string接口为图片返回的一条链接。
transparent_imageobject接口返回的商品透明图片信息。
transparent_image.heightinteger返回的图片高度。
transparent_image.widthinteger返回的图片宽度。
transparent_image.uristring随图片信息返回的 URI。
transparent_image.url_listarray接口返回的图片可用链接列表。
transparent_image.url_list[]string接口为图片返回的一条链接。
营销标签11 个字段

data.data.products[]

字段类型说明
product_marketing_infoobject随商品返回的营销展示信息。
product_marketing_info.placement_labels_uiobject商品营销标签的展示分组。
product_marketing_info.placement_labels_ui.ui_listarray接口返回的商品营销标签展示分组列表。
product_marketing_info.placement_labels_ui.ui_list[]object结果中的一项营销标签分组。
product_marketing_info.placement_labels_ui.ui_list[].placementinteger接口返回的营销标签分组展示位置代码。
product_marketing_info.placement_labels_ui.ui_list[].labelsarray这个展示分组中返回的营销标签列表。
product_marketing_info.placement_labels_ui.ui_list[].labels[]object展示分组中的一个营销标签。
product_marketing_info.placement_labels_ui.ui_list[].labels[].metaobject接口返回的营销标签信息。
product_marketing_info.placement_labels_ui.ui_list[].labels[].meta.label_typestring接口返回的营销标签类型。
product_marketing_info.placement_labels_ui.ui_list[].labels[].lomobject接口返回的营销标签展示内容。
product_marketing_info.placement_labels_ui.ui_list[].labels[].lom.valuestring接口返回的营销标签展示值。
筛选分组22 个字段

data.data

字段类型说明
filter_sectionsarray有提供时表示搜索结果中的筛选分组。
filter_sections[]object搜索结果中的一个筛选分组。
filter_sections[].idstring筛选分组的标识。
filter_sections[].titlestring筛选分组的显示标题。
filter_sections[].filterGroupTypeinteger接口返回的筛选分组类型代码。
filter_sections[].typestring接口返回的筛选分组类型标签。
filter_sections[].optionsobject以显示名称为键的筛选选项标识映射。
filter_sections[].options.{key}string作为键的显示名称所对应的筛选选项标识。
filter_sections[].hasAllOptionboolean筛选分组是否标记为包含全部选项。
filter_sections[].isColorSectionboolean筛选分组是否标记为颜色筛选。
filter_sections[].optionGroupsarray有提供时表示这个筛选分组内的选项子组。
filter_sections[].optionGroups[]object一个筛选选项子组。
filter_sections[].optionGroups[].titlestring筛选选项子组的显示标题。
filter_sections[].optionGroups[].optionsobject以显示名称为键的筛选选项标识映射。
filter_sections[].optionGroups[].options.{key}string作为键的显示名称所对应的筛选选项标识。
filter_sections[].optionGroups[].hasAllOptionboolean选项子组是否标记为包含全部选项。
filter_sections[].isPriceRangeboolean筛选分组是否标记为价格区间筛选。
filter_sections[].showCustomPriceInputboolean价格筛选是否标记为展示自定义输入。
filter_sections[].priceRangeInputInfoobject价格区间筛选的展示边界和币种。
filter_sections[].priceRangeInputInfo.minDisplaystring以展示文本返回的价格下限。
filter_sections[].priceRangeInputInfo.maxDisplaystring以展示文本返回的价格上限。
filter_sections[].priceRangeInputInfo.currencystring接口返回的价格区间筛选币种。
快捷筛选6 个字段

data.data

字段类型说明
filter_quick_optionsarray有提供时表示回包返回的快捷筛选选项列表。
filter_quick_options[]object一个快捷筛选选项。
filter_quick_options[].displayNamestring快捷筛选选项的显示名称。
filter_quick_options[].sectionTitlestring快捷筛选选项所属分组的显示标题。
filter_quick_options[].filterOptionIdstring快捷筛选选项的标识。
filter_quick_options[].filterGroupTypeinteger接口返回的快捷筛选选项所属分组类型代码。

响应示例 ​

正在加载响应示例…