SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-chuhaijiang-tiktok-product

linkfox-chuhaijiang-tiktok-product

Data & analytics

View repository

Updated 10-16 00:00

About this skill

TikTok Product Market Intelligence

Use this skill to research public TikTok Shop product markets: discover products, inspect one product, trace its creators/lives/videos/reviews, browse three rankings, or find visually similar products.

Core Concepts

  • Monetary fields are usually objects such as { "unit": "US", "value": 31 }, but some ranking fields can be plain numbers. Inspect the runtime type before reading and preserve unit when an object is returned.
  • Normal product endpoints require a lowercase marketplace code. Image search accepts an uppercase two-letter code and defaults to US.
  • Search and relationship endpoints return at most 10 records per page; ranking endpoints return at most 20.
  • Each endpoint call is billed independently. Do not repeat the same endpoint and parameters unless the user explicitly asks; successful responses use a 24-hour local cache keyed by endpoint, gateway, API Key fingerprint, and parameters.

Data Fields

Field Meaning
data.total_count Total matching records
data.items Product or relationship records
data.core.items Optional product core metrics when detail include contains core
data.channel.items Optional channel-split sales metrics when detail include contains channel
id / product_id Product or related-entity identifier
product_name Product title
floor_price / ceiling_price Current price range
product_sold_count* Total or windowed sales
product_gmv* / interval_gmv Total or windowed GMV
product_rating / review_count Rating and review volume
product_images Main and thumbnail images
shop_name / seller_id Store identity

Relationship responses use endpoint-specific prefixed fields. Read references/api.md for the complete request definitions, response paths, key fields, and production-validated structure. Do not assume one shared schema.

Endpoints

Intent Endpoint Script Points/call
Filter and discover products /chuhaijiang/products/search chuhaijiang_product_search.py 18
Inspect one product /chuhaijiang/products/detail chuhaijiang_product_detail.py 9
Find promoting creators /chuhaijiang/products/related-creators chuhaijiang_product_related_creators.py 18
Find associated livestreams /chuhaijiang/products/related-lives chuhaijiang_product_related_lives.py 18
Read product reviews /chuhaijiang/products/reviews chuhaijiang_product_reviews.py 18
Find promoting videos /chuhaijiang/products/related-videos chuhaijiang_product_related_videos.py 18
Browse most-promoted ranking /chuhaijiang/products/rankings/most-promoted chuhaijiang_product_rank_most_promoted.py 18
Browse new-arrival ranking /chuhaijiang/products/rankings/new-arrivals chuhaijiang_product_rank_new_arrivals.py 18
Browse top-selling ranking /chuhaijiang/products/rankings/top-selling chuhaijiang_product_rank_top_selling.py 18
Search by an uploaded image /chuhaijiang/products/image-search chuhaijiang_product_image_search.py 30
Upload helper for image search /chuhaijiang/upload/presigned-url upload_image.py 0

Call only the endpoint required by the user's current question. Ask before making additional paid drill-down calls that the user did not request.

Parameter Guide

  • country: one of br,de,es,fr,gb,id,it,jp,mx,my,ph,sg,th,us,vn for normal endpoints.
  • id: required for detail and relationship endpoints. Reuse a product id from search or ranking results.
  • page: starts at 1. pageSize is optional.
  • Search supports keyword, category, sellerType, price/rating/sales ranges, freeShipping, and sort (field:asc or field:desc).
  • Most-promoted and top-selling rankings require date (YYYYMMDD) and granularity (daily, weekly, monthly, 0, 1, or 2).
  • New arrivals optionally supports listedFrom, listedTo, and productStatus.
  • Use camelCase request names shown in references/api.md; do not send upstream snake_case names.

How to call

  • API endpoint: All 11 LinkFox gateway capabilities use POST; for the full request URL, parameters, responses, and error codes, see references/api.md. Local image search will also send to the presigned returned data.url one external HTTP PUT that does not carry the LinkFox API Key.
  • Python script：python scripts/<entry>.py '<JSON 参数>' [--inline]
  • Cost constraints: The 10 product business entry scripts by default cache only successful responses for 24 hours; business-successful empty results can also be cached; the cache is isolated by the current working directory, calling identity, gateway, endpoint, and complete request parameters. When the same combination hits, output Cache hit, and no new paid request will be made. HTTP or business failures are not cached;--inline does not bypass the cache;--no-cache will force a real request and may consume compute again, and is used only when the user explicitly agrees to additional consumption or during debugging. Upload presigning and PUT do not use response caching.

Output strategy (10 product business scripts)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-chuhaijiang-tiktok-product-<timestamp>.json；<cwd> as the current working directory when the script is executed; if the current directory is not writable, exit with an error and do not fall back to the user directory or system temporary directory.
  • Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout outputs the request parameters, top-level status,data.total_count, the length of each business list, and the first 3 samples of the first non-empty business list
  • Add --inline to force full printing to stdout (also written to disk)
  • upload_image.py is an upload helper script: it outputs only safe metadata and does not save presigned responses containing data.url or data.signed_url .

Data reading suggestions: First look at the summary to judge whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, avoiding putting the entire JSON into the context.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide resolution:

Abnormal situations

  • API Key not configured: The environment variable is not configured with LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
  • is also not configured. Response 401 or 402 status code
  • Response indicates insufficient compute or balance: The message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

Image Search Workflow

For a local JPG, JPEG, or PNG, upload it first:

python scripts/upload_image.py /path/to/product.jpg

The helper calls the accelerated presign endpoint, uploads the bytes with HTTP PUT to the returned url, and prints only safe metadata such as osKey, osBucket, file metadata, upload status, and requestId. The returned signed_url is a temporary read URL, not an upload fallback, and must not be printed or persisted. Then call:

python scripts/chuhaijiang_product_image_search.py '{"osKey":"returned-key","country":"US"}'

If the user already provides a valid osKey, skip the upload step.

Usage Examples

python scripts/chuhaijiang_product_search.py '{"country":"us","keyword":"beauty","minRating":4,"freeShipping":true,"pageSize":5}'
python scripts/chuhaijiang_product_detail.py '{"country":"us","id":"1732052189676081387"}'
python scripts/chuhaijiang_product_rank_top_selling.py '{"country":"us","date":"20260824","granularity":"daily","pageSize":10}'
python scripts/chuhaijiang_product_reviews.py '{"country":"us","id":"1732052189676081387","pageSize":10}'

Display Rules

  1. State the marketplace, total count, current page, filters, and ranking window used.
  2. For product lists, show image, title, price range, sales/GMV window, rating, store, and product ID when available.
  3. Keep response currency units; do not silently label unit: US as another currency.
  4. For reviews, show rating, content, publish time, SKU specification, and media availability.
  5. For creators, lives, and videos, display the relationship metrics returned by that endpoint and retain the related entity ID for optional drill-down.
  6. Never expose API keys, signed upload URLs, or raw image bytes.

Important Limitations

  1. Data is real-time market intelligence and cannot be treated as the user's private TikTok Shop account data.
  2. This skill does not manage orders, inventory, listings, fulfillment, affiliate invitations, or ad campaigns.
  3. Do not invent unsupported filters or compensate by repeatedly calling other endpoints.
  4. Search and rankings can change over time; report the request date/window with results.
  5. Image search requires a valid uploaded object key; local paths cannot be passed directly to the image-search endpoint.

User Expression & Scenario Quick Reference

Applicable:

  • Product discovery and details: "Use Chuhaijiang to filter US TikTok beauty products", "Use Chuhaijiang to view this product's details".
  • Associated data: "Use Chuhaijiang to check which creators are promoting this product", "Find the associated livestreams for this TikTok product", "Use Chuhaijiang to view this product's comments", "Use Chuhaijiang to check videos promoting this product".
  • Product rankings: "Use Chuhaijiang to view the US TikTok product hot-push ranking", "Use Chuhaijiang to view the beauty new-product ranking", "Use Chuhaijiang to check the TikTok product sales ranking".
  • Image and combined drill-down: "Use this image to find the TikTok equivalent," "and simultaneously analyze this product's creators, livestreams, videos, and comments."

Adjacent: General TikTok product ranking or selection requests without a source should use linkfox-kalodata-tiktok-product. A public product URL or 19-digit product ID lookup should use linkfox-tiktok-shop-product-detail. Seller-side product operations should use linkfox-tiktok-shop-product. If the user asks for FastMoss, EchoTik, Kalodata, or another named source, use that source instead.

Not applicable: order handling, stock changes, listing publication, campaign creation, video downloading, or image generation/editing.

Compute consumption rules

Billed separately by endpoint: upload presign 0 compute/request; product details 9 compute/request; product search, related creators, related livestreams, product comments, related videos, and product rankings 18 compute/request; image search 30 compute/request.

Users pay for compute consumption. Before high-frequency calls or multi-endpoint drill-downs, first explain the estimated number of calls and compute consumption.

Feedback: Use the Feedback API in references/api.md only when the user explicitly asks to submit feedback or explicitly authorizes submission after an issue is identified. Summarize and sanitize the content; never include API keys, signed URLs, phone numbers, raw user messages, or unrelated task context.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.