TikTok Shop Product Research API: Search and Regional Rejection
Inspect one TikTok Shop keyword page or selected product response; validate regional rejection, preserve price strings, and keep historical evidence separate.

A TikTok Shop search can complete with an empty product list. A different request can complete with a regional rejection and no product data at all. Treating both as an empty dictionary hides the distinction that matters to your application. This TikTok Shop product research API guide starts with one chosen keyword page, or one deliberately selected product and market, and validates the provider result before interpreting it.
This November 8, 2026 repair uses public schemas, retained examples and offline tests. It did not execute a new business request. The current saved search is a Vietnamese-market result; the current saved detail example is a GB rejection. The older October 1 US workflow remains dated history, not proof that detail works today in every listed market.
Key takeaway
- Search requires
search_word; choose the market explicitly and start with offset 0 and an empty page token.- Detail requires a string
product_id. Its region has no schema default; select the product’s market instead of assuming US.- Check
region_supported: falsebefore requiring a success code or nested data. The saved GB rejection has neither.- Preserve IDs, currencies and raw counts. One returned sample does not establish a niche’s size, revenue or best seller.
The retained cover illustrates the older product/review/catalog workflow. Its “niche verdict”, five stars and connecting pipes are conceptual, not new API results or a promise that this revision runs that chain.
Choose one TikTok Shop product research API task
| Task | Reference | Selected request |
|---|---|---|
| Inspect keyword listing cards | Search products list | search_word, explicit region, offset 0, empty page_token |
| Inspect a known product response | Product detail V2 | Exact string product_id and chosen region |
These are separate decisions. A search result does not authorize automatically selecting the largest sold count, querying its reviews or crawling its seller. The detail schema also accepts optional seller_id; this first request omits it. Search declares no limit, page-size, sorting or filter-object input, even when a returned page contains filter suggestions.
The search schema defaults region to US, whereas the detail schema does not specify a default. Both describe US/GB/SG/MY/PH/TH/VN/ID, but that prose is not an enforced enum or measured availability matrix. The code’s uppercase two-letter check is a local input guard, not proof that a particular market works. Keep product, seller and SKU identifiers separate and retain exact strings; a long product ID should never pass through JavaScript Number.
Historical TikTok catalog with Creator Search Insights selected, 145 listed endpoints, GET navigation paths and an API Free Week banner. It is not a Shop response or today’s pricing evidence; the promotion shown has ended.
Give your agent a bounded first task
For an existing project, keep its local SANDBASE_API_KEY configuration and install requests if it is not already a dependency. Do not replace an existing secret store or paste the key into chat. For an already connected agent, provide the exact keyword and market, and say whether you want search or a separately selected product response.
A new project can start from the setup skill and Markdown quickstart. For example: “Implement one VN search for áo khoác zip bé using my local key. Validate the completed envelope, preserve product IDs and VND price strings, and stop after the first response. Test regional rejection without retrying, switching markets or querying a product automatically.” A later detail request needs its own chosen ID and market.
The November 8 inspection lists each selected endpoint at $0.001 per call, eligible for the organization-shared daily allowance of 100 eligible calls resetting at 00:00 UTC. Eligibility does not reveal your remaining allowance. Two intentionally selected calls list at $0.002 before applicable quota; this is arithmetic, not a request plan or a measured charge. No promise about billing failed calls is established here.
Python: distinguish rejection from an empty result
Install the dependency with python -m pip install requests, set the key locally, and save this code in your project. It uses Model API POST /v1/api/<model> with operation parameters in the body, not the catalog’s GET navigation path. It sends one request and does not retry.
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"]))For a known-product task, replace both lines inside the final if __name__ == "__main__": block with these lines, preserving their indentation. Substitute an actual decimal ID and two-letter market. The placeholders deliberately fail validation; do not append this as a second request after the search demo.
result = first_request("detail", "YOUR_SELECTED_PRODUCT_ID", "YOUR_MARKET")
print("Detail response matched the historical layout")The detail output does not read a search-only products array or claim that the product identity was verified. An UnsupportedRegion exception retains the exact provider object in its payload attribute for local diagnosis, while its message avoids printing that object or credentials.
Search validation is backed by a complete saved example. The optional detail validator recognizes only the data.components_map layout described by the historical October 1 experiment. Its positive unit test is a synthetic shape fixture, not a newly captured successful product. An unrecognized detail layout fails explicitly; do not convert it into an empty product or infer availability from a completed outer envelope. The code returns raw provider values and does not extract a title, price or identity from that historical layout.
Historical search-products-list reference showing the POST route, required search_word, optional offset/token/region and a generated envelope whose data object is empty. It documents the request surface, not a successful product response.
Two saved responses, two different meanings
The search capture 4ac99e1c-df10-49d8-9f89-2ff007551b3b, dated October 7 at 17:37:34.382 UTC, used áo khoác zip bé, VN, offset 0 and an empty token. It contains 20 products, has_more: false and load-more metadata with offset 0 and an empty token. Twenty is the observed sample count; no input requested a guaranteed twenty-item page.
This exact projection of its first card preserves the stored numeric representations:
{
"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 decimal text 403009 and display text 403.009 must not become USD403.009. The display separator is formatting, not a universal decimal convention. A review count may be a string while a sold count is numeric. Keep missing values unknown, and keep raw currency and observation time alongside any later normalized value. Brand and seller shop names differ in this sample; either name alone does not verify ownership or authenticity.
The detail capture de2e3154-e9a3-4cdd-bfb4-6da5d2ec8e44, dated October 7 at 17:37:27.639 UTC, requested product 1731581114818794403 in GB. Its complete provider object is:
{
"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"
]
}There is no code, data or product object to unwrap. The schema description includes GB, while this saved response excludes GB and includes JP/MX. Both sources remain intact because the disagreement is unresolved. This historical rejection does not establish a permanent ban, and its alternative-region list does not establish that the same product exists in those markets. Stop on the actual rejection instead of silently trying each region.
Pagination and commercial interpretation stop here
The current VN saved page has no more results according to its own flag. A separate undated US/coffee README shows has_more: true, offset 30 and a nonempty token; it is not the VN capture. If you later implement continuation, it needs actual has_more: true plus valid returned load_more_params.offset and page_token, with the same keyword and region. Do not add 30 locally, send returned api_source as a new input or reuse a token across market changes. No continuation was executed in this repair.
A valid empty products array means this request returned an empty sample. It does not measure zero demand, and this example does not retry automatically. Likewise, ranking a few returned cards by sold_count ranks that sample only. It cannot establish daily sales, revenue, full-catalog coverage or a marketplace winner. The observed product and rating fields are useful context when kept with their source; they are not a sourcing recommendation.
What remains from the October 1 experiment
The complete original English article and code archive preserves all six original Python blocks, the JSON below and thirteen historical run IDs. The older helper’s top-level output fallback, automatic retries and missing-value coercion are retained as history, not recommended code. In particular, str(None) is not a product ID and a missing sold count is not measured zero.
The original experiment covered two US niches and a few SG/MY searches. It recorded intermittent empty US search pages; empty nested search-v2 output and a SG upstream 400; incomplete v1 detail; successful US v2 detail; repeated v3/category failures; US-only detail/review success within that limited test; and seller-catalog continuation. These observations neither certify current success nor permanently disqualify other variants.
The old two-page search recorded 30+30 nonoverlapping listings. The seven-call research report described 60 listings, 27% zero-sales share, a $24.95 coffee card with 219,808 reported sold and score 4.7. Its larger shop sample included a collagen product with 1,377,502 reported sold. Those were dated sample observations; the old inferred niche and authenticity conclusions are not verified market research. The preserved code’s treatment of missing sold counts can distort that zero-sales percentage.
The original JSON is unchanged:
{
"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"}
}
]
}The old detail run described category breadcrumbs, 25,363 five-star and 1,195 one-star entries, review_count 29017 versus 28866 on a different card, and a response above 1 MB for another product. Counts observed in different calls are not synchronized. The layout omitted its own title/price in those runs; that is not a universal property of every future response.
Historical product-reviews-v2 parameter reference with page_start and filters; its generated data is empty. Review mining belongs to the archived workflow and was not revalidated or executed by this repair.
The archive also retains two review pages, an inconclusive star-filter attempt, two seller-catalog pages and a full-link resolver observation; short links were not tested. These extra operations require separate contract and budget review before being restored to an application. A returned reviewer flag does not require storing reviewer names or avatars for product research.
Historical seller-products-list reference with seller_id and search_params. The empty generated response does not demonstrate a current catalog or continuation. This separate endpoint is outside the new first-request code.
FAQ
Does a completed response mean detail succeeded? No. Read the provider object and handle regional rejection before attempting success parsing. A transport-level completion and a usable product are different outcomes.
Can the agent retry an empty search? The example stops. A later retry policy needs an explicit budget and reason; an old intermittent failure observation is not permission for an unbounded loop.
Are GB, JP or MX supported now? This repair does not resolve the conflict between schema prose and the saved negative response. Inspect the actual selected response without guessing coverage or switching markets automatically.
Can I reuse the old niche report? Its code and observations remain archived for audit. Revalidate reviews, catalogs, identity selection and missing-value treatment before using that multi-request design.
For neighboring capabilities, use the TikTok API hub or creator research guide. Begin with the chosen product task and keep its market and evidence date attached to the result.
For 2026 listed prices on the live SandBase TikTok hub, see Best TikTok API in 2026: Pricing Compared.
Found this useful? Share it