TikTok Shop Product Rank

12 credits/call
ae_tiktok_shop_product_rank

Retrieve Kalodata-provided TikTok Shop product rankings for the country selected by `region`; the data is not limited to the US. Filter by product keyword, shop, creator, category, affiliate status, launch timing, or revenue and price ranges. Ranking date windows are limited to 30 days. Set ranking order with the `sort_field` object. Results include product and seller identifiers, sales and revenue metrics, category information, and other returned ranking fields. The tool returns the result in the response to the call.

Social
12 credits/call

Pricing

12 credits/call
ConditionCharge
Each call12 credits/call

A fixed charge of 12 credits applies to each successful query.

Parameters

Optional parameters use the platform defaults when omitted.

ParameterTypeRequiredDescriptionDefault
ascbooleanNoLegacy ascending-flag field. Use the `sort_field` object to specify the ranking order.—
regionenum (US | BR | MX | ID | JP | MY | PH | SG | TH | VN | GB | ES | DE | FR | IT | PL | NL | BE | CZ | AT | GR | PT | HU | IE)YesSelect the TikTok Shop country/region for the ranking. Choose one of the country codes listed in this parameter's allowed values; the data is not limited to the US.—
keywordstringNoFilter products by a keyword.—
shop_idstringNoRestrict results to the given shop.—
currencyenum (CNY | USD | IDR | VND | THB | MYR | JPY | PHP | GBP | SGD | MXN | EUR | BRL | PLN | CZK | HUF)YesCurrency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL, PLN, CZK, HUF.—
languageenum (zh-CN | en-US | id-ID | th-TH | vi-VN | es-ES | ja-JP | pt-BR | ko-KR | fr-FR | de-DE | pl-PL | nl-NL | cs-CZ | el-GR | hu-HU | pt-PT | it-IT)YesLanguage for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR, de-DE, pl-PL, nl-NL, cs-CZ, el-GR, hu-HU, pt-PT, it-IT.—
need_allbooleanNoIf true, include products that have no sales in the selected period. Default false (sales-only).—
video_idstringNoReturn the products mounted on the given video.—
page_sizeintegerNoPage size. Maximum 100 records per query. Default 10.10
creator_idstringNoFilter for products promoted by this creator. When combined with `shop_id`, returns the creator's products for that shop.—
date_rangestringYesRanking time window; no more than 30 days. Accepts `lastDay`, `last7Day`, or `last30Day`, a `yyyy-MM-dd~yyyy-MM-dd` range spanning no more than 30 days, or `yyyy-MM` (subject to the 30-day limit).—
need_extrabooleanNoWhether to include extra product information such as seller name and SKU quantity.—
need_imageintegerNoWhether main image URL is needed: 0-not needed (default), 1-return official URL, 2-return kalo_data image URL (paid service required)—
rank_fieldstringNoLegacy ranking-field field. Use the `sort_field` object to specify the ranking field and direction.—
sort_fieldobjectYesRanking order, specified as an object with `field` and `type`. Use this field for ranking configuration.—
sort_field.typeenum (ASC | DESC)NoRanking direction: `ASC` for ascending or `DESC` for descending.—
sort_field.fieldstringNoName of the response's numeric field to rank by, such as `revenue`, `sales_volumn`, or `revenue_growth_rate`.—
launch_dateenum (<3 | <7 | >30)NoDays since product launch. <3 = within 3 days, <7 = within 7 days, >30 = older than 30 days.—
page_numberintegerNoPage number, starting at 1. 1
category_idsarrayNoFilter the ranked products by category ID.—
is_affiliateenum (0 | 1)NoAffiliate-program filter. 0 = non-affiliate only, 1 = affiliate only.—
delivery_typeenum (local | global)NoDelivery mode filter. `local` = domestic fulfillment, `global` = cross-border.—
livestream_idstringNoReturn the products mounted in the given live stream.—
revenue_rangestringNoRevenue range filter, in the same currency as the request `currency`. Also supports `<10` / `>1` forms.—
is_tts_productenum (0 | 1)NoTTS (Tiktok fully-managed) product filter. 1 = fully managed only, 0 = self-fulfilled only.—
commission_ratestringNoCommission rate filter for affiliate products. Accepts range (`15-35`), open-ended (`<10`, `>=30`), or a single ratio.—
unit_price_rangestringNoProduct unit-price range filter.—

Invocation example

Copy the request and explore its response example.

POST/agent-api/v1/tool/executeX-Api-Key
Request coderequest.sh
curl --request POST \
  --url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_tiktok_shop_product_rank' \
  --header "X-Api-Key: $AGENTEARTH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "params": {
    "currency": "GBP",
    "date_range": "last30Day",
    "delivery_type": "global",
    "keyword": "phone case",
    "language": "en-US",
    "page_size": 20,
    "region": "GB",
    "sort_field": {
      "field": "revenue",
      "type": "DESC"
    }
  }
}'
Response exampleresponse.json
JSONPartial content
{
  "cached": null,
  "code": null,
  "data": [
    {
      "commission_rate": 8.0,
      "launch_date": "2026-09-12",
      "live_revenue": 0.0,
      "master_image_url": null,
      "pri_category": {
        "category_id": "601739",
        "category_name": "Phones & Electronics"
      },
      "product_id": "1729914352412694833"
    }
  ],
  "message": null,
  "success": true
}

This example shows part of the response. Copied content is valid JSON.