# LiveStreamer

> A streamer's live figures over a period, as a live board or a creator marketplace shows them: rank, sessions, viewers and sales bands.

Canonical page: https://okdata.online/docs/objects/live_streamer/

The same shape on every platform. A field a platform does not have is null, and meta.unavailable says why. Use fields= to keep only what you need.

| Field | Type | Description |
|---|---|---|
| `id` | string | The streamer's ID on the board's source: the Xingtu creator ID on Douyin (what douyin.live.streamers.metrics takes), the user ID on TikTok. |
| `url` | string \| null | The streamer's page, where there is one. |
| `username` | string \| null | Handle, where the board gives one. |
| `name` | string \| null | Display name; null where the source gives none (douyin.live.streamers.metrics). |
| `avatar_url` | string \| null | Avatar image URL. |
| `followers` | integer \| null | Followers. |
| `rank` | integer \| null | Place on the board, from 1; null outside boards. |
| `score` | number \| null | The board's score: TikTok's points, or Xingtu's score from 0 to 1. |
| `category` | string \| null | Content or product category, in the platform's words. |
| `room_id` | string \| null | The room the streamer is live in now, where the board gives it. |
| `days` | integer \| null | Days the figures cover; null when the board does not say. |
| `sessions` | integer \| null | Live sessions in the period. |
| `avg_views` | integer \| null | Average views a session. |
| `avg_unique_viewers` | integer \| null | Average people who watched a session. |
| `avg_viewers` | integer \| null | Average people watching at once. |
| `peak_viewers` | integer \| null | Most people watching at once. |
| `avg_watch_seconds` | integer \| null | Average seconds a viewer stayed. |
| `new_followers` | integer \| null | Followers gained live in the period. |
| `engagement_rate` | Band \| null | Engagement rate as the platform works it out, 0 to 1, as a band. |
| `gmv` | Band \| null | Sales over the period, in yuan, as a band. |
| `avg_gmv` | Band \| null | Average sales a session, in yuan, as a band. |
| `gpm` | Band \| null | Sales per thousand views (GPM), in yuan, as a band. |
| `avg_price` | Band \| null | Average price of the products sold, in yuan, as a band. |
| `products` | integer \| null | Products sold live in the period. |
| `ext` | object | Platform-specific extras. Only returned with view=full. |

### Band

| Field | Type | Description |
|---|---|---|
| `min` | number \| null | Low end of the band; null when open-ended ("< 400"). |
| `max` | number \| null | High end of the band; null when open-ended ("> 0.95"). |

## Endpoints that return a LiveStreamer

- [TikTok LIVE shopping ranking](https://okdata.online/apis/tiktok/live/streamers/trending/) (`tiktok.live.streamers.trending`): $0.002 per call · about 99 results per page
- [Douyin live streamer boards](https://okdata.online/apis/douyin/live/streamers/trending/) (`douyin.live.streamers.trending`): $0.006 per call · about 100 results per page
- [Douyin streamer live figures](https://okdata.online/apis/douyin/live/streamers/metrics/) (`douyin.live.streamers.metrics`): $0.04 per call

## Fields by view

Each view includes the fields of the views above it. `view=compact` is the smallest; `full` adds platform extras under `ext`.

- compact: `id`, `url`, `username`, `name`, `followers`, `rank`, `category`, `days`, `sessions`, `avg_views`, `avg_viewers`, `new_followers`, `gmv`, `avg_gmv`, `products`
- standard: `avatar_url`, `score`, `room_id`, `avg_unique_viewers`, `peak_viewers`, `avg_watch_seconds`, `engagement_rate`, `gpm`, `avg_price`
- full: `ext`
