Live Stream Rankings - TikTok Live Rankings

Introduction

Retrieve TikTok live stream rankings data, with the following features:

• Supports filtering parameters
• Supports custom result sorting

API Endpoint

    POST /live/v1/rank/topLive

Request Body

Field	Type	Required	Description
filter	object	No	Filter parameters
orderby	object	No	Sorting parameters
page	integer	No	Page number, default: 1
pagesize	integer	No	Items per page, default: 10

filter Optional Values

Field	Type	Required	Description
region	string	No	Country/Region, e.g., ['US', 'GB', 'MX', 'ES', 'ID', 'VN', 'MY', 'TH', 'PH']
creator_category_id	integer	No	Creator category
product_category_id	integer	No	Product category (Level 1)
live_type	integer	No	Live type: 1 (Shop live), 2 (Creator live)

orderby Optional Values

Field	Required	Description
start_time	No	Start time (descending)
total_viewer_count	No	Total viewer count (descending)
peak_viewer_count	No	Peak viewer count (descending)
total_units_sold	No	Sales volume (descending)
total_gmv	No	Revenue (descending)

Request Example

curl 'https://openapi.test.fastmoss.com/live/v1/rank/topLive?client_id=XXX&timestamp=XXX&access_token=XXX&sign=XXX' \
--header 'Content-Type: application/json' \
{
    "filter": {
        "region": "US",
        "product_category_id": 1,
    },
     "orderby": [
      {
        "field": "start_time",
        "order": "desc",
      }
    ],
    "page": 1,
    "pagesize": 10
}

Response Body

data.total

• Type: integer
• Description: Total number of results

data.list

Field	Type	Description
room_id	string	Live room ID
title	string	Live room title
cover	string	Live room cover URL
start_time	timestamp[integer]	Start time (timestamp)
end_time	timestamp[integer]	End time (timestamp)
duration	integer	Duration (seconds)
product_count	integer	Number of products listed
total_viewer_count	integer	Total viewer count
total_units_sold	integer	Live room sales volume
total_gmv	integer	Live room revenue
currency	string	Currency
uv_value	integer	UV value
creator	object	Creator information

data.list.creator

Field	Type	Description
uid	string	Creator ID
nickname	string	Nickname
unique_id	string	Creator unique ID
avatar	string	Avatar URL
follower_count	integer	Follower count
region	string	Country/Region

Response Example

{
    "code":0,
    "msg":"success", 
    "data":{
        "total":152,
        "list":[
                {
                    "uid":"123456",
                    "unique_id":"hello",
                    "nickname":"hello",
                     "follower_count":123,
                     "creator_region":"US",
                     "room_id":"12341234",
                     "title":"welcome",
                     "cover":"cover url",
                     "start_time":123412341,
                     "end_time":1234123412,
                     "duration":12342,
                     "product_count":12,
                     "total_viewer_count":1234,
                     "total_units_sold":123,
                     "total_gmv":1234,
                     "currency":"USD",
                     "uv_value":1234,
                     "creator":{    
                         "uid":"123456",
                         "unique_id":"hello",
                         "nickname":"hello",
                         "follower_count":123,
                         "region":"US",
                         "avatar":"avatar url"
                     }
                }
            ]
        }
}