TikTok Shop Product Search API (V1)
API health status
Healthy Available Limited Mostly unavailable No data
Loading health status...
Searches TikTok Shop products by keyword within a selected region, with offset and page-token pagination. Use it to discover regional products and continue through search results.
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
token | query | string | Yes | - | Authentication token for this API service. |
keyword | query | string | Yes | - | Search keyword. |
region | query | string | No | US | Target region for product search. Available Values: - US: United States- GB: United Kingdom- FR: France- SG: Singapore- MY: Malaysia- PH: Philippines- TH: Thailand- VN: Vietnam- ID: Indonesia |
offset | query | integer | No | 0 | Search result offset. |
pageToken | query | string | No | - | Pagination token for the next page. |
Code Samples
bash
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE'text
I want to use the "Product Search (V1)" API from JustOneAPI.
Base URL: https://api.justoneapi.com.
API Path: /api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE
API Endpoint: BASE_URL + /api/tiktok-shop/search-products/v1?token=YOUR_API_KEY&keyword=VALUE
HTTP Method: GET
Authentication: Append the "token" query parameter to the URL.
OpenAPI Definition: https://docs.justoneapi.com/openapi/tiktok-shop/product-search-v1-en.json
Parameters:
- token (query): Authentication token for this API service. (Required)
- keyword (query): Search keyword. (Required)
- region (query): Target region for product search.
Available Values:
- `US`: United States
- `GB`: United Kingdom
- `FR`: France
- `SG`: Singapore
- `MY`: Malaysia
- `PH`: Philippines
- `TH`: Thailand
- `VN`: Vietnam
- `ID`: Indonesia
- offset (query): Search result offset.
- pageToken (query): Pagination token for the next page.
Return format: safely handle JSON or text according to the actual Content-Type.
Response Handling & Error Codes:
1. Business results should be determined by the "code" field in the response body (code 0 means success).
2. Timeout Recommendation: Set the request timeout to 120 seconds. If 120 seconds is too long for your use case, use at least 60 seconds, but a small number of requests may time out before receiving a result.
3. Business Code Reference:
- 0: Success
- 100: Invalid or Inactive Token
- 301: Collection Failed. Please Retry.
- 302: Rate Limit Exceeded
- 303: Daily Quota Exceeded
- 400: Invalid Parameters
- 500: Internal Server Error
- 600: Permission Denied
- 601: Insufficient Balance
- 602: Token Budget Exceeded
4. Code 601 means the shared account balance is insufficient. Code 602 means the current API token's own cumulative budget limit has been reached. Token budget limits do not transfer funds out of the shared account balance.
Please help me write a script in my preferred programming language to call this API and handle the response.python
import requests
BASE_URL = "https://api.justoneapi.com" # Provided by 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"; // Provided by 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"; // Provided by 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" // Provided by 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'; // Provided by 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;
}Response Fields
Key fields in a successful response (code = 0).
Results and continuation9 fields
data
TikTok Shop search result and its reported status.
| Field | Type | Description |
|---|---|---|
code | integer | Inner status code reported by TikTok Shop. |
message | string | Inner status message reported by TikTok Shop. |
data | object | Products, shops and search metadata returned for this page. |
data.has_more | boolean | Whether the response reports more search results. |
data.load_more_params | object | Continuation parameters returned for the next search request. |
data.load_more_params.offset | integer | Offset returned for the next page. Pass it as offset with the same keyword and region. |
data.load_more_params.page_token | string | Opaque token returned for continuing the search. Pass it unchanged as pageToken with the returned offset. |
data.products | array | Product entries returned on this search page. |
data.shops | array | Shop entries returned separately in the search results. |
Product overview12 fields
data.data.products[]
One product in the search results.
| Field | Type | Description |
|---|---|---|
product_id | string | TikTok Shop product identifier returned as text. |
title | string | Title returned for the product listing. |
rate_info | object | Rating information returned for the product, when available. |
rate_info.score | number | Rating score reported as a number. |
rate_info.review_count | string | Review count reported as display text. |
sold_info | object | Sales count information returned for the listing. |
sold_info.sold_count | integer | Sold count reported for the product. |
brand_info | object | Brand information returned for the product, when available. |
brand_info.brand_name | string | Brand name reported for the product. |
seo_url | object | Product page link metadata returned with the listing. |
seo_url.canonical_url | string | Canonical product page URL returned for the listing. |
seo_url.slug | string | Product page slug returned with the canonical link. |
Product prices25 fields
data.data.products[]
| Field | Type | Description |
|---|---|---|
product_price_info | object | Price information returned with the product listing. |
product_price_info.price_prefix | string | Optional text displayed before the returned price. |
product_price_info.sku_id | string | Identifier reported for the SKU associated with this price. |
product_price_info.symbol_position | integer | Position code reported for the currency symbol. |
product_price_info.show_currency_space | boolean | Whether the price format calls for a currency space. |
product_price_info.currency_show_mode | integer | Currency display mode code reported with the price. |
product_price_info.currency_name | string | Currency identifier reported with the price. |
product_price_info.currency_symbol | string | Currency symbol reported with the price. |
product_price_info.sale_price_decimal | string | Sale price amount returned as decimal text. |
product_price_info.sale_price_format | string | Formatted sale price display text. |
product_price_info.single_product_price_format | string | Formatted display text for the single-product price. |
product_price_info.single_product_price_decimal | string | Single-product price amount returned as decimal text. |
product_price_info.sale_price_integer_part_format | string | Formatted integer part of the displayed sale price. |
product_price_info.sale_price_decimal_part_format | string | Formatted decimal part of the displayed sale price. |
product_price_info.decimal_point_symbol | string | Decimal separator reported for the price format. |
product_price_info.promotion_deduction_details | object | Promotion deduction information returned with the price. |
product_price_info.promotion_deduction_details.seller_subtotal_deduction | string | Displayed seller subtotal deduction reported with the promotion. |
product_price_info.promotion_deduction_details.seller_subtotal_deduction_decimal | string | Seller subtotal deduction amount returned as decimal text. |
product_price_info.raw_origin_price_decimal | string | Raw original-price amount reported as decimal text. |
product_price_info.raw_origin_price_format | string | Formatted display text for the raw original price. |
product_price_info.origin_price_decimal | string | Original-price amount returned as decimal text, when provided. |
product_price_info.origin_price_format | string | Formatted display text for the reported original price. |
product_price_info.discount_format | string | Formatted discount display text. |
product_price_info.discount_decimal | string | Discount value returned as decimal text. |
product_price_info.reduce_price_format | string | Formatted display text for the reported price reduction. |
SKU prices27 fields
data.data.products[]
| Field | Type | Description |
|---|---|---|
sku_info | array | SKU price entries returned for this product. |
sku_info[] | object | One SKU price entry for this product. |
sku_info[].SkuId | string | SKU identifier returned for the price entry. |
sku_info[].PriceInfo | object | Price information returned for the SKU. |
sku_info[].PriceInfo.sku_id | string | Identifier reported for the SKU associated with this price. |
sku_info[].PriceInfo.symbol_position | integer | Position code reported for the currency symbol. |
sku_info[].PriceInfo.show_currency_space | boolean | Whether the price format calls for a currency space. |
sku_info[].PriceInfo.currency_show_mode | integer | Currency display mode code reported with the price. |
sku_info[].PriceInfo.currency_name | string | Currency identifier reported with the price. |
sku_info[].PriceInfo.currency_symbol | string | Currency symbol reported with the price. |
sku_info[].PriceInfo.sale_price_decimal | string | Sale price amount returned as decimal text. |
sku_info[].PriceInfo.sale_price_format | string | Formatted sale price display text. |
sku_info[].PriceInfo.single_product_price_format | string | Formatted display text for the single-product price. |
sku_info[].PriceInfo.single_product_price_decimal | string | Single-product price amount returned as decimal text. |
sku_info[].PriceInfo.sale_price_integer_part_format | string | Formatted integer part of the displayed sale price. |
sku_info[].PriceInfo.sale_price_decimal_part_format | string | Formatted decimal part of the displayed sale price. |
sku_info[].PriceInfo.decimal_point_symbol | string | Decimal separator reported for the price format. |
sku_info[].PriceInfo.promotion_deduction_details | object | Promotion deduction information returned with the price. |
sku_info[].PriceInfo.promotion_deduction_details.seller_subtotal_deduction | string | Displayed seller subtotal deduction reported with the promotion. |
sku_info[].PriceInfo.promotion_deduction_details.seller_subtotal_deduction_decimal | string | Seller subtotal deduction amount returned as decimal text. |
sku_info[].PriceInfo.raw_origin_price_decimal | string | Raw original-price amount reported as decimal text. |
sku_info[].PriceInfo.raw_origin_price_format | string | Formatted display text for the raw original price. |
sku_info[].PriceInfo.origin_price_decimal | string | Original-price amount returned as decimal text, when provided. |
sku_info[].PriceInfo.origin_price_format | string | Formatted display text for the reported original price. |
sku_info[].PriceInfo.discount_format | string | Formatted discount display text. |
sku_info[].PriceInfo.discount_decimal | string | Discount value returned as decimal text. |
sku_info[].PriceInfo.reduce_price_format | string | Formatted display text for the reported price reduction. |
Product seller22 fields
data.data.products[]
| Field | Type | Description |
|---|---|---|
seller_info | object | Seller information returned with the product. |
seller_info.seller_id | string | TikTok Shop seller identifier returned as text. |
seller_info.shop_name | string | Display name returned for the shop. |
seller_info.store_blueV_label | object | Blue verification badge artwork reported for the shop. |
seller_info.store_blueV_label.label_image_light | object | Verification badge artwork for the light display. |
seller_info.store_blueV_label.label_image_light.height | integer | Reported image height. |
seller_info.store_blueV_label.label_image_light.width | integer | Reported image width. |
seller_info.store_blueV_label.label_image_light.uri | string | Image URI returned with the image information. |
seller_info.store_blueV_label.label_image_light.url_list | array | Available URLs returned for the image. |
seller_info.store_blueV_label.label_image_light.url_list[] | string | One URL returned for the image. |
seller_info.store_blueV_label.label_image_dark | object | Verification badge artwork for the dark display. |
seller_info.store_blueV_label.label_image_dark.height | integer | Reported image height. |
seller_info.store_blueV_label.label_image_dark.width | integer | Reported image width. |
seller_info.store_blueV_label.label_image_dark.uri | string | Image URI returned with the image information. |
seller_info.store_blueV_label.label_image_dark.url_list | array | Available URLs returned for the image. |
seller_info.store_blueV_label.label_image_dark.url_list[] | string | One URL returned for the image. |
seller_info.shop_logo | object | Shop logo image information. |
seller_info.shop_logo.height | integer | Reported image height. |
seller_info.shop_logo.width | integer | Reported image width. |
seller_info.shop_logo.uri | string | Image URI returned with the image information. |
seller_info.shop_logo.url_list | array | Available URLs returned for the image. |
seller_info.shop_logo.url_list[] | string | One URL returned for the image. |
Shop results21 fields
data.data.shops[]
One shop in the search results.
| Field | Type | Description |
|---|---|---|
seller_id | string | TikTok Shop seller identifier returned as text. |
shop_name | string | Display name returned for the shop. |
store_blueV_label | object | Blue verification badge artwork reported for the shop. |
store_blueV_label.label_image_light | object | Verification badge artwork for the light display. |
store_blueV_label.label_image_light.height | integer | Reported image height. |
store_blueV_label.label_image_light.width | integer | Reported image width. |
store_blueV_label.label_image_light.uri | string | Image URI returned with the image information. |
store_blueV_label.label_image_light.url_list | array | Available URLs returned for the image. |
store_blueV_label.label_image_light.url_list[] | string | One URL returned for the image. |
store_blueV_label.label_image_dark | object | Verification badge artwork for the dark display. |
store_blueV_label.label_image_dark.height | integer | Reported image height. |
store_blueV_label.label_image_dark.width | integer | Reported image width. |
store_blueV_label.label_image_dark.uri | string | Image URI returned with the image information. |
store_blueV_label.label_image_dark.url_list | array | Available URLs returned for the image. |
store_blueV_label.label_image_dark.url_list[] | string | One URL returned for the image. |
shop_logo | object | Shop logo image information. |
shop_logo.height | integer | Reported image height. |
shop_logo.width | integer | Reported image width. |
shop_logo.uri | string | Image URI returned with the image information. |
shop_logo.url_list | array | Available URLs returned for the image. |
shop_logo.url_list[] | string | One URL returned for the image. |
Product images12 fields
data.data.products[]
| Field | Type | Description |
|---|---|---|
image | object | Main image information returned for the product. |
image.height | integer | Reported image height. |
image.width | integer | Reported image width. |
image.uri | string | Image URI returned with the image information. |
image.url_list | array | Available URLs returned for the image. |
image.url_list[] | string | One URL returned for the image. |
transparent_image | object | Transparent image information returned for the product. |
transparent_image.height | integer | Reported image height. |
transparent_image.width | integer | Reported image width. |
transparent_image.uri | string | Image URI returned with the image information. |
transparent_image.url_list | array | Available URLs returned for the image. |
transparent_image.url_list[] | string | One URL returned for the image. |
Marketing labels11 fields
data.data.products[]
| Field | Type | Description |
|---|---|---|
product_marketing_info | object | Marketing display information returned with the product. |
product_marketing_info.placement_labels_ui | object | Display groups for product marketing labels. |
product_marketing_info.placement_labels_ui.ui_list | array | Product marketing label groups returned for display. |
product_marketing_info.placement_labels_ui.ui_list[] | object | One marketing label group in the result. |
product_marketing_info.placement_labels_ui.ui_list[].placement | integer | Placement code reported for the marketing label group. |
product_marketing_info.placement_labels_ui.ui_list[].labels | array | Marketing labels returned for this display group. |
product_marketing_info.placement_labels_ui.ui_list[].labels[] | object | One marketing label in the display group. |
product_marketing_info.placement_labels_ui.ui_list[].labels[].meta | object | Metadata returned for the marketing label. |
product_marketing_info.placement_labels_ui.ui_list[].labels[].meta.label_type | string | Type label reported for the marketing label. |
product_marketing_info.placement_labels_ui.ui_list[].labels[].lom | object | Display content returned for the marketing label. |
product_marketing_info.placement_labels_ui.ui_list[].labels[].lom.value | string | Display value returned for the marketing label. |
Filter sections22 fields
data.data
| Field | Type | Description |
|---|---|---|
filter_sections | array | Filter sections described in the search results, when provided. |
filter_sections[] | object | One filter section in the search results. |
filter_sections[].id | string | Identifier of the filter section. |
filter_sections[].title | string | Display title of the filter section. |
filter_sections[].filterGroupType | integer | Type code reported for the filter section. |
filter_sections[].type | string | Type label reported for the filter section. |
filter_sections[].options | object | Filter option identifiers keyed by their display labels. |
filter_sections[].options.{key} | string | Filter option identifier for the display label used as the key. |
filter_sections[].hasAllOption | boolean | Whether the section is marked as having an all-options choice. |
filter_sections[].isColorSection | boolean | Whether the section is marked as a color filter. |
filter_sections[].optionGroups | array | Groups of filter options within this section, when provided. |
filter_sections[].optionGroups[] | object | One group of filter options. |
filter_sections[].optionGroups[].title | string | Display title of the filter option group. |
filter_sections[].optionGroups[].options | object | Filter option identifiers keyed by their display labels. |
filter_sections[].optionGroups[].options.{key} | string | Filter option identifier for the display label used as the key. |
filter_sections[].optionGroups[].hasAllOption | boolean | Whether the option group is marked as having an all-options choice. |
filter_sections[].isPriceRange | boolean | Whether the section is marked as a price range filter. |
filter_sections[].showCustomPriceInput | boolean | Whether the price filter is marked to show a custom input. |
filter_sections[].priceRangeInputInfo | object | Displayed bounds and currency for the price range filter. |
filter_sections[].priceRangeInputInfo.minDisplay | string | Minimum price bound returned as display text. |
filter_sections[].priceRangeInputInfo.maxDisplay | string | Maximum price bound returned as display text. |
filter_sections[].priceRangeInputInfo.currency | string | Currency returned for the price range filter. |
Quick filters6 fields
data.data
| Field | Type | Description |
|---|---|---|
filter_quick_options | array | Quick filter options reported in the response, when available. |
filter_quick_options[] | object | One quick filter option. |
filter_quick_options[].displayName | string | Display name of the quick filter option. |
filter_quick_options[].sectionTitle | string | Display title of the section associated with the quick option. |
filter_quick_options[].filterOptionId | string | Identifier of the quick filter option. |
filter_quick_options[].filterGroupType | integer | Filter group type code reported for the quick option. |
Response Example
Loading the response example...