TikTok Shop Store Rank

12 credits/call
ae_tiktok_shop_store_rank

Retrieve TikTok Shop shop rankings for a selected country and date range, with optional keyword, category, shop type, revenue, and average-price filters. Results include shop rank and metrics such as revenue, sales volume, average price, and available category or image information. TikTok Shop data is provided by Kalodata. `date_range` supports `lastDay`, `last7Day`, `last30Day`, a custom `yyyy-MM-dd~yyyy-MM-dd` span of up to 30 days, or a natural month in `yyyy-MM` format. The 30-day limit applies to custom date spans, not natural-month input. Select `region` using one of the country codes allowed by the schema. Use the `sort_field` object to specify a supported sort field and `ASC` or `DESC` direction.

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 paired with `rank_field`. Default false (DESC).—
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 whose TikTok Shop data to query. Choose a country code from the schema's allowed values.—
keywordstringNoKeyword for shop search—
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
shop_typeenum (BRAND | RETAILER)NoShop type filter. BRAND = brand-owned store, RETAILER = retailer store.—
date_rangestringYesRanking date range. This endpoint supports `lastDay`, `last7Day`, `last30Day`, a custom `yyyy-MM-dd~yyyy-MM-dd` date span of up to 30 days, or a natural month in `yyyy-MM` format. The 30-day limit applies to custom date spans, not natural-month input.—
need_imageintegerNoWhether to include a main image URL: 0 = do not request an image URL, 1 = request the official URL, 2 = request a Kalodata image URL.—
rank_fieldstringNoLegacy shortcut for the sort field name; prefer `sort_field`. Ignored when `sort_field` is set.—
sort_fieldobjectYesSort specification object. Set `field` to a supported sort field and `type` to `ASC` or `DESC`. The documented default is `revenue` in `DESC` order.—
sort_field.typeenum (ASC | DESC)NoSort direction.—
sort_field.fieldstringNoSort field name. Any numeric field returned by the endpoint is supported (e.g. revenue, sales_volumn, revenue_growth_rate).—
page_numberintegerNoPage number, starting at 1. 1
category_idsarrayNoRestrict results to shops that sell in the given category IDs.—
need_categoryintegerNoWhether category information is needed (0 = not needed, 1 = needed)—
revenue_rangestringNoShop revenue range filter, in the same currency as the request `currency`. Also supports `<100` / `>1000` forms.—
unit_price_rangestringNoShop product avg price range—

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_store_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": 5,
    "region": "US",
    "sort_field": {
      "field": "revenue",
      "type": "DESC"
    }
  }
}'
Response exampleresponse.json
JSONPartial content
{
  "cached": null,
  "code": null,
  "data": [
    {
      "affiliate_revenue": 9840913.48,
      "category_id_list": null,
      "category_info_list": [],
      "category_list": null,
      "image_url": null,
      "on_sell_product_count": 164
    }
  ],
  "message": null,
  "success": true
}

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