Skip to content

TikTok Shop Product Search API (V1) ​

GET
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 ​

NameInTypeRequiredDefaultDescription
tokenquerystringYes-Authentication token for this API service.
keywordquerystringYes-Search keyword.
regionquerystringNoUSTarget 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
offsetqueryintegerNo0Search result offset.
pageTokenquerystringNo-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.

FieldTypeDescription
codeintegerInner status code reported by TikTok Shop.
messagestringInner status message reported by TikTok Shop.
dataobjectProducts, shops and search metadata returned for this page.
data.has_morebooleanWhether the response reports more search results.
data.load_more_paramsobjectContinuation parameters returned for the next search request.
data.load_more_params.offsetintegerOffset returned for the next page. Pass it as offset with the same keyword and region.
data.load_more_params.page_tokenstringOpaque token returned for continuing the search. Pass it unchanged as pageToken with the returned offset.
data.productsarrayProduct entries returned on this search page.
data.shopsarrayShop entries returned separately in the search results.
Product overview12 fields

data.data.products[]

One product in the search results.

FieldTypeDescription
product_idstringTikTok Shop product identifier returned as text.
titlestringTitle returned for the product listing.
rate_infoobjectRating information returned for the product, when available.
rate_info.scorenumberRating score reported as a number.
rate_info.review_countstringReview count reported as display text.
sold_infoobjectSales count information returned for the listing.
sold_info.sold_countintegerSold count reported for the product.
brand_infoobjectBrand information returned for the product, when available.
brand_info.brand_namestringBrand name reported for the product.
seo_urlobjectProduct page link metadata returned with the listing.
seo_url.canonical_urlstringCanonical product page URL returned for the listing.
seo_url.slugstringProduct page slug returned with the canonical link.
Product prices25 fields

data.data.products[]

FieldTypeDescription
product_price_infoobjectPrice information returned with the product listing.
product_price_info.price_prefixstringOptional text displayed before the returned price.
product_price_info.sku_idstringIdentifier reported for the SKU associated with this price.
product_price_info.symbol_positionintegerPosition code reported for the currency symbol.
product_price_info.show_currency_spacebooleanWhether the price format calls for a currency space.
product_price_info.currency_show_modeintegerCurrency display mode code reported with the price.
product_price_info.currency_namestringCurrency identifier reported with the price.
product_price_info.currency_symbolstringCurrency symbol reported with the price.
product_price_info.sale_price_decimalstringSale price amount returned as decimal text.
product_price_info.sale_price_formatstringFormatted sale price display text.
product_price_info.single_product_price_formatstringFormatted display text for the single-product price.
product_price_info.single_product_price_decimalstringSingle-product price amount returned as decimal text.
product_price_info.sale_price_integer_part_formatstringFormatted integer part of the displayed sale price.
product_price_info.sale_price_decimal_part_formatstringFormatted decimal part of the displayed sale price.
product_price_info.decimal_point_symbolstringDecimal separator reported for the price format.
product_price_info.promotion_deduction_detailsobjectPromotion deduction information returned with the price.
product_price_info.promotion_deduction_details.seller_subtotal_deductionstringDisplayed seller subtotal deduction reported with the promotion.
product_price_info.promotion_deduction_details.seller_subtotal_deduction_decimalstringSeller subtotal deduction amount returned as decimal text.
product_price_info.raw_origin_price_decimalstringRaw original-price amount reported as decimal text.
product_price_info.raw_origin_price_formatstringFormatted display text for the raw original price.
product_price_info.origin_price_decimalstringOriginal-price amount returned as decimal text, when provided.
product_price_info.origin_price_formatstringFormatted display text for the reported original price.
product_price_info.discount_formatstringFormatted discount display text.
product_price_info.discount_decimalstringDiscount value returned as decimal text.
product_price_info.reduce_price_formatstringFormatted display text for the reported price reduction.
SKU prices27 fields

data.data.products[]

FieldTypeDescription
sku_infoarraySKU price entries returned for this product.
sku_info[]objectOne SKU price entry for this product.
sku_info[].SkuIdstringSKU identifier returned for the price entry.
sku_info[].PriceInfoobjectPrice information returned for the SKU.
sku_info[].PriceInfo.sku_idstringIdentifier reported for the SKU associated with this price.
sku_info[].PriceInfo.symbol_positionintegerPosition code reported for the currency symbol.
sku_info[].PriceInfo.show_currency_spacebooleanWhether the price format calls for a currency space.
sku_info[].PriceInfo.currency_show_modeintegerCurrency display mode code reported with the price.
sku_info[].PriceInfo.currency_namestringCurrency identifier reported with the price.
sku_info[].PriceInfo.currency_symbolstringCurrency symbol reported with the price.
sku_info[].PriceInfo.sale_price_decimalstringSale price amount returned as decimal text.
sku_info[].PriceInfo.sale_price_formatstringFormatted sale price display text.
sku_info[].PriceInfo.single_product_price_formatstringFormatted display text for the single-product price.
sku_info[].PriceInfo.single_product_price_decimalstringSingle-product price amount returned as decimal text.
sku_info[].PriceInfo.sale_price_integer_part_formatstringFormatted integer part of the displayed sale price.
sku_info[].PriceInfo.sale_price_decimal_part_formatstringFormatted decimal part of the displayed sale price.
sku_info[].PriceInfo.decimal_point_symbolstringDecimal separator reported for the price format.
sku_info[].PriceInfo.promotion_deduction_detailsobjectPromotion deduction information returned with the price.
sku_info[].PriceInfo.promotion_deduction_details.seller_subtotal_deductionstringDisplayed seller subtotal deduction reported with the promotion.
sku_info[].PriceInfo.promotion_deduction_details.seller_subtotal_deduction_decimalstringSeller subtotal deduction amount returned as decimal text.
sku_info[].PriceInfo.raw_origin_price_decimalstringRaw original-price amount reported as decimal text.
sku_info[].PriceInfo.raw_origin_price_formatstringFormatted display text for the raw original price.
sku_info[].PriceInfo.origin_price_decimalstringOriginal-price amount returned as decimal text, when provided.
sku_info[].PriceInfo.origin_price_formatstringFormatted display text for the reported original price.
sku_info[].PriceInfo.discount_formatstringFormatted discount display text.
sku_info[].PriceInfo.discount_decimalstringDiscount value returned as decimal text.
sku_info[].PriceInfo.reduce_price_formatstringFormatted display text for the reported price reduction.
Product seller22 fields

data.data.products[]

FieldTypeDescription
seller_infoobjectSeller information returned with the product.
seller_info.seller_idstringTikTok Shop seller identifier returned as text.
seller_info.shop_namestringDisplay name returned for the shop.
seller_info.store_blueV_labelobjectBlue verification badge artwork reported for the shop.
seller_info.store_blueV_label.label_image_lightobjectVerification badge artwork for the light display.
seller_info.store_blueV_label.label_image_light.heightintegerReported image height.
seller_info.store_blueV_label.label_image_light.widthintegerReported image width.
seller_info.store_blueV_label.label_image_light.uristringImage URI returned with the image information.
seller_info.store_blueV_label.label_image_light.url_listarrayAvailable URLs returned for the image.
seller_info.store_blueV_label.label_image_light.url_list[]stringOne URL returned for the image.
seller_info.store_blueV_label.label_image_darkobjectVerification badge artwork for the dark display.
seller_info.store_blueV_label.label_image_dark.heightintegerReported image height.
seller_info.store_blueV_label.label_image_dark.widthintegerReported image width.
seller_info.store_blueV_label.label_image_dark.uristringImage URI returned with the image information.
seller_info.store_blueV_label.label_image_dark.url_listarrayAvailable URLs returned for the image.
seller_info.store_blueV_label.label_image_dark.url_list[]stringOne URL returned for the image.
seller_info.shop_logoobjectShop logo image information.
seller_info.shop_logo.heightintegerReported image height.
seller_info.shop_logo.widthintegerReported image width.
seller_info.shop_logo.uristringImage URI returned with the image information.
seller_info.shop_logo.url_listarrayAvailable URLs returned for the image.
seller_info.shop_logo.url_list[]stringOne URL returned for the image.
Shop results21 fields

data.data.shops[]

One shop in the search results.

FieldTypeDescription
seller_idstringTikTok Shop seller identifier returned as text.
shop_namestringDisplay name returned for the shop.
store_blueV_labelobjectBlue verification badge artwork reported for the shop.
store_blueV_label.label_image_lightobjectVerification badge artwork for the light display.
store_blueV_label.label_image_light.heightintegerReported image height.
store_blueV_label.label_image_light.widthintegerReported image width.
store_blueV_label.label_image_light.uristringImage URI returned with the image information.
store_blueV_label.label_image_light.url_listarrayAvailable URLs returned for the image.
store_blueV_label.label_image_light.url_list[]stringOne URL returned for the image.
store_blueV_label.label_image_darkobjectVerification badge artwork for the dark display.
store_blueV_label.label_image_dark.heightintegerReported image height.
store_blueV_label.label_image_dark.widthintegerReported image width.
store_blueV_label.label_image_dark.uristringImage URI returned with the image information.
store_blueV_label.label_image_dark.url_listarrayAvailable URLs returned for the image.
store_blueV_label.label_image_dark.url_list[]stringOne URL returned for the image.
shop_logoobjectShop logo image information.
shop_logo.heightintegerReported image height.
shop_logo.widthintegerReported image width.
shop_logo.uristringImage URI returned with the image information.
shop_logo.url_listarrayAvailable URLs returned for the image.
shop_logo.url_list[]stringOne URL returned for the image.
Product images12 fields

data.data.products[]

FieldTypeDescription
imageobjectMain image information returned for the product.
image.heightintegerReported image height.
image.widthintegerReported image width.
image.uristringImage URI returned with the image information.
image.url_listarrayAvailable URLs returned for the image.
image.url_list[]stringOne URL returned for the image.
transparent_imageobjectTransparent image information returned for the product.
transparent_image.heightintegerReported image height.
transparent_image.widthintegerReported image width.
transparent_image.uristringImage URI returned with the image information.
transparent_image.url_listarrayAvailable URLs returned for the image.
transparent_image.url_list[]stringOne URL returned for the image.
Marketing labels11 fields

data.data.products[]

FieldTypeDescription
product_marketing_infoobjectMarketing display information returned with the product.
product_marketing_info.placement_labels_uiobjectDisplay groups for product marketing labels.
product_marketing_info.placement_labels_ui.ui_listarrayProduct marketing label groups returned for display.
product_marketing_info.placement_labels_ui.ui_list[]objectOne marketing label group in the result.
product_marketing_info.placement_labels_ui.ui_list[].placementintegerPlacement code reported for the marketing label group.
product_marketing_info.placement_labels_ui.ui_list[].labelsarrayMarketing labels returned for this display group.
product_marketing_info.placement_labels_ui.ui_list[].labels[]objectOne marketing label in the display group.
product_marketing_info.placement_labels_ui.ui_list[].labels[].metaobjectMetadata returned for the marketing label.
product_marketing_info.placement_labels_ui.ui_list[].labels[].meta.label_typestringType label reported for the marketing label.
product_marketing_info.placement_labels_ui.ui_list[].labels[].lomobjectDisplay content returned for the marketing label.
product_marketing_info.placement_labels_ui.ui_list[].labels[].lom.valuestringDisplay value returned for the marketing label.
Filter sections22 fields

data.data

FieldTypeDescription
filter_sectionsarrayFilter sections described in the search results, when provided.
filter_sections[]objectOne filter section in the search results.
filter_sections[].idstringIdentifier of the filter section.
filter_sections[].titlestringDisplay title of the filter section.
filter_sections[].filterGroupTypeintegerType code reported for the filter section.
filter_sections[].typestringType label reported for the filter section.
filter_sections[].optionsobjectFilter option identifiers keyed by their display labels.
filter_sections[].options.{key}stringFilter option identifier for the display label used as the key.
filter_sections[].hasAllOptionbooleanWhether the section is marked as having an all-options choice.
filter_sections[].isColorSectionbooleanWhether the section is marked as a color filter.
filter_sections[].optionGroupsarrayGroups of filter options within this section, when provided.
filter_sections[].optionGroups[]objectOne group of filter options.
filter_sections[].optionGroups[].titlestringDisplay title of the filter option group.
filter_sections[].optionGroups[].optionsobjectFilter option identifiers keyed by their display labels.
filter_sections[].optionGroups[].options.{key}stringFilter option identifier for the display label used as the key.
filter_sections[].optionGroups[].hasAllOptionbooleanWhether the option group is marked as having an all-options choice.
filter_sections[].isPriceRangebooleanWhether the section is marked as a price range filter.
filter_sections[].showCustomPriceInputbooleanWhether the price filter is marked to show a custom input.
filter_sections[].priceRangeInputInfoobjectDisplayed bounds and currency for the price range filter.
filter_sections[].priceRangeInputInfo.minDisplaystringMinimum price bound returned as display text.
filter_sections[].priceRangeInputInfo.maxDisplaystringMaximum price bound returned as display text.
filter_sections[].priceRangeInputInfo.currencystringCurrency returned for the price range filter.
Quick filters6 fields

data.data

FieldTypeDescription
filter_quick_optionsarrayQuick filter options reported in the response, when available.
filter_quick_options[]objectOne quick filter option.
filter_quick_options[].displayNamestringDisplay name of the quick filter option.
filter_quick_options[].sectionTitlestringDisplay title of the section associated with the quick option.
filter_quick_options[].filterOptionIdstringIdentifier of the quick filter option.
filter_quick_options[].filterGroupTypeintegerFilter group type code reported for the quick option.

Response Example ​

Loading the response example...