TikTok Shop Category Rank

12 credits/call
ae_tiktok_shop_category_rank

Retrieve TikTok Shop category rankings using data provided by Kalodata. Select `region` for the country to query; the tool is not limited to the US. Filter by category IDs (including their sub-categories), category level, and revenue range, and set the currency and response language as needed. Results include category rank, sales and revenue metrics. `date_range` supports only `last7Day`, `last30Day`, `last90Day`, `last180Day`, or `last365Day`; natural months, custom date ranges, and `lastDay` are not supported. Use `sort_field` to choose the sort field and direction, and `page_number`/`page_size` to paginate results.

Social
12 credits/call

Pricing

12 credits/call
ConditionCharge
Each call12 credits/call

Parameters

Optional parameters use the platform defaults when omitted.

ParameterTypeRequiredDescriptionDefault
ascbooleanNoLegacy ascending flag. Use `sort_field` to set sort direction; when `sort_field` is provided, this legacy field is not used.—
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)YesCountry code for the TikTok Shop data to query. Choose one of the country codes in this field's allowed values; the data is not limited to the US.—
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.—
page_sizeintegerNoPage size. Maximum 100 records per query. Default 10.10
date_rangeenum (last7Day | last30Day | last90Day | last180Day | last365Day)YesCategory queries support only last7Day, last30Day, last90Day, last180Day or last365Day. Custom date ranges, natural months and lastDay are not supported.—
rank_fieldstringNoLegacy sort-field shortcut. Prefer `sort_field` for sorting; when `sort_field` is provided, this field is ignored.—
sort_fieldobjectYesSort spec. `field` accepts any numeric field from the response; `type` is ASC or DESC. Defaults to `{"field":"revenue","type":"DESC"}`.—
sort_field.typeenum (ASC | DESC)NoSort direction.—
sort_field.fieldstringNoName of a numeric field returned by the endpoint to sort by, such as `revenue`, `sale`, `average_revenue`, `revenue_growth_rate`, or `top3_shop_revenue_ratio`.—
page_numberintegerNoPage number, starting at 1. 1
category_idsarrayNoRestrict results to the given category IDs and their sub-categories. When omitted, all categories are included.—
revenue_rangestringNoRevenue range filter within the selected time period, in the same currency as the request `currency`. Also supports open-ended forms like `<100` or `>1000`.—
category_levelenum (1 | 2 | 3)NoCategory level to return. 1 = top level, 2 = mid level, 3 = leaf level.—

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_category_rank' \
  --header "X-Api-Key: $AGENTEARTH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "params": {
    "currency": "USD",
    "date_range": "last7Day",
    "language": "en-US",
    "page_number": 1,
    "page_size": 1,
    "region": "US",
    "sort_field": {
      "field": "revenue",
      "type": "DESC"
    }
  }
}'
Response exampleresponse.json
JSONPartial content
{
  "cached": null,
  "code": null,
  "data": [
    {
      "average_revenue": 6737.16,
      "category_id": "601450",
      "category_name": "Beauty & Personal Care",
      "rank": 1,
      "revenue": 116074560.79,
      "revenue_growth_rate": -2.91
    }
  ],
  "message": null,
  "success": true
}

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