Douyin Index Creation Guide API (V1)
GET
API health status
24h health
24h avg latency
Last checked
Healthy Available Limited Mostly unavailable No data
Healthy
Loading health status...
24h trend
30d trend
Retrieves a selected ranking, production report, consumption report, or publication calendar from the Douyin Creator Center Creation Guide. Use content verticals and published reporting dates to research popular keywords, topics, videos, and audience trends.
Highlights
Guidance
Select one dataType per request. Use CONTENT_DATES or VIDEO_DATES in a separate request to look up published dates. Each ranking or report request requires an explicit endDate.
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
token | query | string | Yes | - | Authentication token for this API service. |
analysisType | query | string | Yes | - | Creation Guide analysis tab. Available Values: - CREATIVITY: Creative insights and rankings- PRODUCTION: Content production analysis- CONSUMPTION: Content consumption analysis |
dataType | query | string | Yes | - | One data set within the selected tab. Choose KEYWORDS, TOPICS, or VIDEOS for creative insight rankings. Available Values: - CONTENT_DATES: Publication calendar for keyword and topic rankings and for production and consumption reports- VIDEO_DATES: Publication calendar for popular video rankings. Use with CREATIVITY- KEYWORDS: Popular keywords. Use with CREATIVITY- TOPICS: Popular topics. Use with CREATIVITY- VIDEOS: Popular videos. Use with CREATIVITY- PUBLISH_TREND: Content publishing trend. Use with PRODUCTION- AUTHOR_PORTRAIT: Creator profile distribution. Use with PRODUCTION- VIDEO_DURATION: Content share, engagement, and completion by video duration. Use with PRODUCTION or CONSUMPTION- CONSUME_TREND: Content supply and consumption trends. Use with CONSUMPTION- INTERACT_TREND: Content engagement trend. Use with CONSUMPTION- CONSUMER_PORTRAIT: Audience distributions for viewing and engagement. Use with CONSUMPTION |
vertical | query | string | No | - | Content vertical. Required for rankings and reports. Omit for publication calendars. Available Values: - DRAMA: Scripted stories and drama- CELEBRITIES: Celebrities- MUSIC: Music- ANIME_COMICS: Anime, comics, and related fan culture- GAMING: Gaming- CURRENT_AFFAIRS: Society and current affairs- DANCE: Dance- RURAL_LIFE: Agriculture, rural areas, and rural life- TECHNOLOGY: Science and technology- FINANCE: Business and finance- PARENTING: Maternity and parenting- LIFESTYLE_HOME: Lifestyle and home- HEALTH: Medicine and health- RELATIONSHIPS: Relationships and emotional well-being- CULTURE: Culture- CAREERS: Careers and the workplace- EDUCATION: Education and campus life- PHOTOGRAPHY: Photography and videography- FOOD: Food and cooking- TRAVEL: Travel- FASHION: Fashion- SPORTS: Sports- ENTERTAINMENT: Leisure and entertainment- AUTOMOTIVE: Cars and the automotive industry |
period | query | string | No | - | ONE_DAY, THREE_DAYS, or WEEK for rankings. WEEK or MONTH for profile and video duration reports. Omit for trend reports and publication calendars. Available Values: - ONE_DAY: One published day. Rankings only- THREE_DAYS: Three days ending on the specified published day. Rankings only- WEEK: A reporting week ending on Sunday- MONTH: A calendar month. Profile and video duration reports only |
startDate | query | string | No | - | Inclusive first day in China time (UTC+8), in YYYY-MM-DD format. Required for publishing, supply and consumption, and engagement trends. Omit for other data types. |
endDate | query | string | No | - | Inclusive last day in China time (UTC+8), in YYYY-MM-DD format. Required for rankings and reports. Use a published Sunday for WEEK or a published month end for MONTH. Omit for publication calendars. |
Code Samples
bash
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/douyin-index/get-creation-guide/v1?token=YOUR_API_KEY&analysisType=CREATIVITY&dataType=CONTENT_DATES'text
I want to use the "Creation Guide (V1)" API from JustOneAPI.
Base URL: https://api.justoneapi.com.
API Path: /api/douyin-index/get-creation-guide/v1?token=YOUR_API_KEY&analysisType=CREATIVITY&dataType=CONTENT_DATES
API Endpoint: BASE_URL + /api/douyin-index/get-creation-guide/v1?token=YOUR_API_KEY&analysisType=CREATIVITY&dataType=CONTENT_DATES
HTTP Method: GET
Authentication: Append the "token" query parameter to the URL.
OpenAPI Definition: https://docs.justoneapi.com/openapi/douyin-index/creation-guide-v1-en.json
Parameters:
- token (query): Authentication token for this API service. (Required)
- analysisType (query): Creation Guide analysis tab.
Available Values:
- `CREATIVITY`: Creative insights and rankings
- `PRODUCTION`: Content production analysis
- `CONSUMPTION`: Content consumption analysis (Required)
- dataType (query): One data set within the selected tab. Choose KEYWORDS, TOPICS, or VIDEOS for creative insight rankings.
Available Values:
- `CONTENT_DATES`: Publication calendar for keyword and topic rankings and for production and consumption reports
- `VIDEO_DATES`: Publication calendar for popular video rankings. Use with CREATIVITY
- `KEYWORDS`: Popular keywords. Use with CREATIVITY
- `TOPICS`: Popular topics. Use with CREATIVITY
- `VIDEOS`: Popular videos. Use with CREATIVITY
- `PUBLISH_TREND`: Content publishing trend. Use with PRODUCTION
- `AUTHOR_PORTRAIT`: Creator profile distribution. Use with PRODUCTION
- `VIDEO_DURATION`: Content share, engagement, and completion by video duration. Use with PRODUCTION or CONSUMPTION
- `CONSUME_TREND`: Content supply and consumption trends. Use with CONSUMPTION
- `INTERACT_TREND`: Content engagement trend. Use with CONSUMPTION
- `CONSUMER_PORTRAIT`: Audience distributions for viewing and engagement. Use with CONSUMPTION (Required)
- vertical (query): Content vertical. Required for rankings and reports. Omit for publication calendars.
Available Values:
- `DRAMA`: Scripted stories and drama
- `CELEBRITIES`: Celebrities
- `MUSIC`: Music
- `ANIME_COMICS`: Anime, comics, and related fan culture
- `GAMING`: Gaming
- `CURRENT_AFFAIRS`: Society and current affairs
- `DANCE`: Dance
- `RURAL_LIFE`: Agriculture, rural areas, and rural life
- `TECHNOLOGY`: Science and technology
- `FINANCE`: Business and finance
- `PARENTING`: Maternity and parenting
- `LIFESTYLE_HOME`: Lifestyle and home
- `HEALTH`: Medicine and health
- `RELATIONSHIPS`: Relationships and emotional well-being
- `CULTURE`: Culture
- `CAREERS`: Careers and the workplace
- `EDUCATION`: Education and campus life
- `PHOTOGRAPHY`: Photography and videography
- `FOOD`: Food and cooking
- `TRAVEL`: Travel
- `FASHION`: Fashion
- `SPORTS`: Sports
- `ENTERTAINMENT`: Leisure and entertainment
- `AUTOMOTIVE`: Cars and the automotive industry
- period (query): ONE_DAY, THREE_DAYS, or WEEK for rankings. WEEK or MONTH for profile and video duration reports. Omit for trend reports and publication calendars.
Available Values:
- `ONE_DAY`: One published day. Rankings only
- `THREE_DAYS`: Three days ending on the specified published day. Rankings only
- `WEEK`: A reporting week ending on Sunday
- `MONTH`: A calendar month. Profile and video duration reports only
- startDate (query): Inclusive first day in China time (UTC+8), in YYYY-MM-DD format. Required for publishing, supply and consumption, and engagement trends. Omit for other data types.
- endDate (query): Inclusive last day in China time (UTC+8), in YYYY-MM-DD format. Required for rankings and reports. Use a published Sunday for WEEK or a published month end for MONTH. Omit for publication calendars.
Return format: safely handle JSON or text according to the actual Content-Type.
Response Handling & Error Codes:
1. Business results should be determined by the "code" field in the response body (code 0 means success).
2. Timeout Recommendation: Set the request timeout to 120 seconds. If 120 seconds is too long for your use case, use at least 60 seconds, but a small number of requests may time out before receiving a result.
3. Business Code Reference:
- 0: Success
- 100: Invalid or Inactive Token
- 301: Collection Failed. Please Retry.
- 302: Rate Limit Exceeded
- 303: Daily Quota Exceeded
- 400: Invalid Parameters
- 500: Internal Server Error
- 600: Permission Denied
- 601: Insufficient Balance
- 602: Token Budget Exceeded
4. Code 601 means the shared account balance is insufficient. Code 602 means the current API token's own cumulative budget limit has been reached. Token budget limits do not transfer funds out of the shared account balance.
Please help me write a script in my preferred programming language to call this API and handle the response.python
import requests
BASE_URL = "https://api.justoneapi.com" # Provided by OpenAPI servers
url = BASE_URL + "/api/douyin-index/get-creation-guide/v1?token=YOUR_API_KEY&analysisType=CREATIVITY&dataType=CONTENT_DATES"
response = requests.get(url, timeout=120)
print(response.status_code)
if response.content:
content_type = response.headers.get("content-type", "").lower()
if "json" in content_type:
try:
print(response.json())
except ValueError:
print(response.text)
elif content_type.startswith("text/") or "xml" in content_type or content_type.split(";", 1)[0].strip() in {"application/javascript", "application/x-www-form-urlencoded", "application/graphql"}:
print(response.text)
else:
with open("response.bin", "wb") as output:
output.write(response.content)
print(f"Saved {len(response.content)} bytes to response.bin")js
const BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
const url = BASE_URL + "/api/douyin-index/get-creation-guide/v1?token=YOUR_API_KEY&analysisType=CREATIVITY&dataType=CONTENT_DATES";
const response = await fetch(url, {
method: "GET",
signal: AbortSignal.timeout(120000)
});
console.log(response.status);
const responseBytes = await response.arrayBuffer();
if (responseBytes.byteLength) {
const contentType = (response.headers.get("content-type") || "").toLowerCase();
const mediaType = contentType.split(";", 1)[0].trim();
const textual = contentType.startsWith("text/") || contentType.includes("json") || contentType.includes("xml") || ["application/javascript", "application/x-www-form-urlencoded", "application/graphql"].includes(mediaType);
if (textual) {
const responseText = new TextDecoder().decode(responseBytes);
let data = responseText;
if (contentType.includes("json")) {
try { data = JSON.parse(responseText); } catch { /* Keep the raw body. */ }
}
console.log(data);
} else {
console.log(`Received ${responseBytes.byteLength} binary bytes`);
}
}java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
public class Main {
public static void main(String[] args) throws Exception {
final String BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
final String url = BASE_URL + "/api/douyin-index/get-creation-guide/v1?token=YOUR_API_KEY&analysisType=CREATIVITY&dataType=CONTENT_DATES";
HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(120)).build();
HttpRequest.Builder builder = HttpRequest.newBuilder()
.uri(URI.create(url))
.timeout(Duration.ofSeconds(120))
.method("GET", HttpRequest.BodyPublishers.noBody());
HttpRequest request = builder.build();
HttpResponse<byte[]> response = client.send(request, HttpResponse.BodyHandlers.ofByteArray());
System.out.println(response.statusCode());
String contentType = response.headers().firstValue("content-type").orElse("").toLowerCase();
String mediaType = contentType.split(";", 2)[0].trim();
if (contentType.startsWith("text/") || contentType.contains("json") || contentType.contains("xml") || mediaType.equals("application/javascript") || mediaType.equals("application/x-www-form-urlencoded") || mediaType.equals("application/graphql")) {
System.out.println(new String(response.body(), StandardCharsets.UTF_8));
} else {
Files.write(Path.of("response.bin"), response.body());
System.out.println("Saved " + response.body().length + " bytes to response.bin");
}
}
}go
package main
import (
"fmt"
"io"
"os"
"strings"
"net/http"
"time"
)
const BASE_URL = "https://api.justoneapi.com" // Provided by OpenAPI servers
func main() {
client := &http.Client{Timeout: 120 * time.Second}
url := BASE_URL + "/api/douyin-index/get-creation-guide/v1?token=YOUR_API_KEY&analysisType=CREATIVITY&dataType=CONTENT_DATES"
req, _ := http.NewRequest("GET", url, nil)
resp, _ := client.Do(req)
defer resp.Body.Close()
fmt.Println(resp.StatusCode)
bodyBytes, _ := io.ReadAll(resp.Body)
contentType := strings.ToLower(resp.Header.Get("Content-Type"))
mediaType := strings.TrimSpace(strings.SplitN(contentType, ";", 2)[0])
if strings.HasPrefix(contentType, "text/") || strings.Contains(contentType, "json") || strings.Contains(contentType, "xml") || mediaType == "application/javascript" || mediaType == "application/x-www-form-urlencoded" || mediaType == "application/graphql" {
fmt.Println(string(bodyBytes))
} else {
os.WriteFile("response.bin", bodyBytes, 0600)
fmt.Printf("Saved %d bytes to response.bin\n", len(bodyBytes))
}
}php
<?php
$BASE_URL = 'https://api.justoneapi.com'; // Provided by OpenAPI servers
$url = $BASE_URL . '/api/douyin-index/get-creation-guide/v1?token=YOUR_API_KEY&analysisType=CREATIVITY&dataType=CONTENT_DATES';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$contentType = strtolower((string) curl_getinfo($ch, CURLINFO_CONTENT_TYPE));
curl_close($ch);
echo $status . PHP_EOL;
$mediaType = trim(explode(';', $contentType, 2)[0]);
if (str_starts_with($contentType, 'text/') || str_contains($contentType, 'json') || str_contains($contentType, 'xml') || in_array($mediaType, ['application/javascript', 'application/x-www-form-urlencoded', 'application/graphql'], true)) {
echo $response;
} else {
file_put_contents('response.bin', $response);
echo 'Saved ' . strlen($response) . ' bytes to response.bin' . PHP_EOL;
}Response Fields
Key fields in a successful response (code = 0).
Available reporting dates7 fields
data
| Field | Type | Description |
|---|---|---|
day | string | Latest published day for content reports and keyword or topic rankings, in YYYYMMDD format. |
week | string | End date of the latest published week for content reports and keyword or topic rankings, in YYYYMMDD format. |
month | string | End date of the latest published month for content reports, in YYYYMMDD format. |
earliest_week | string | End date of the earliest available content reporting week, in YYYYMMDD format. |
latest_day | string | Latest published day for popular video rankings, in YYYYMMDD format. |
start_week | string | End date of the earliest available video ranking week, in YYYYMMDD format. |
end_week | string | End date of the latest available video ranking week, in YYYYMMDD format. |
Popular keywords7 fields
data
| Field | Type | Description |
|---|---|---|
keyword_list | array | Popular keywords for the selected vertical and period. |
keyword_list[] | object | One popular keyword. |
keyword_list[].keyword | string | Keyword text. |
keyword_list[].cnt | string | Number of videos associated with the keyword, expressed as a string. |
keyword_list[].is_hot | boolean | Hot-keyword indicator returned by Douyin. |
keyword_list[].index | string | Composite index, expressed as a string. |
keyword_list[].search_index | string | Search index, expressed as a string. |
Popular topics9 fields
data
| Field | Type | Description |
|---|---|---|
topic_list | array | Popular topics for the selected vertical and period. |
topic_list[] | object | One popular topic. |
topic_list[].id | string | Douyin topic identifier. |
topic_list[].name | string | Topic name. |
topic_list[].index | string | Topic index, expressed as a string. |
topic_list[].item_cnt | string | Submission count, expressed as a string. |
topic_list[].vv | string | View count, expressed as a string. |
topic_list[].digg_cnt | string | Like count, expressed as a string. |
topic_list[].item_list | array | Related entries, when present. |
Popular videos18 fields
data
| Field | Type | Description |
|---|---|---|
video_infos | array | Popular videos for the selected vertical and period. |
video_infos[] | object | One video in the ranking. |
video_infos[].item_id | string | Douyin video identifier. |
video_infos[].author_fans | string | Creator follower count, expressed as a string. |
video_infos[].index | string | Video index, expressed as a string. |
video_infos[].like_cnt | string | Like count, expressed as a string. |
video_infos[].seq | string | Position in the ranking, expressed as a string. |
video_infos[].video_title | string | Video title. |
video_infos[].author | string | Creator display name. |
video_infos[].comment_cnt | string | Comment count, expressed as a string. |
video_infos[].forward_cnt | string | Share count, expressed as a string. |
video_infos[].thumbnail | string | Video thumbnail URL. |
video_infos[].avatar_url | string | Creator avatar URL. |
video_infos[].status | string | Video status value. |
video_infos[].play_cnt | string | View count, expressed as a string. |
video_infos[].author_id | string | Douyin creator identifier. |
page_resp | object | Ranking result count. |
page_resp.total_num | string | Total reported for the video ranking, expressed as a string. |
Content production12 fields
data
| Field | Type | Description |
|---|---|---|
author_list | array | Trend series for content creators. |
author_list[] | object | One day in the trend. |
author_list[].date | string | Reporting date in YYYYMMDD format. |
author_list[].rate | number | Value of this trend point. |
item_list | array | Trend series for published content. |
item_list[] | object | One day in the trend. |
item_list[].date | string | Reporting date in YYYYMMDD format. |
item_list[].rate | number | Value of this trend point. |
data | array | Creator profile distributions for the selected vertical and period. |
data[] | object | One attribute in the audience or creator profile. |
data[].name_en | string | Identifier for the profile attribute. |
data[].label_list | array | Distribution entries for this attribute. |
Content consumption20 fields
data
| Field | Type | Description |
|---|---|---|
supply_trend | array | Trend series for content supply. |
supply_trend[] | object | One day in the trend. |
supply_trend[].date | string | Reporting date in YYYYMMDD format. |
supply_trend[].rate | number | Value of this trend point. |
consume_trend | object | Content consumption trend and associated top entries. |
consume_trend.rate_list | array | Time series returned for the selected period. |
consume_trend.rate_list[] | object | One reported observation. |
consume_trend.top_list | array | Top entries returned with the trend. |
interact_trend | object | Content engagement trend and associated top entries. |
interact_trend.rate_list | array | Time series returned for the selected period. |
interact_trend.rate_list[] | object | One reported observation. |
interact_trend.top_list | array | Top entries returned with the trend. |
play_data | array | Audience profile distributions for video viewing. |
play_data[] | object | One attribute in the audience or creator profile. |
play_data[].name_en | string | Identifier for the profile attribute. |
play_data[].label_list | array | Distribution entries for this attribute. |
interaction_data | array | Audience profile distributions for video engagement. |
interaction_data[] | object | One attribute in the audience or creator profile. |
interaction_data[].name_en | string | Identifier for the profile attribute. |
interaction_data[].label_list | array | Distribution entries for this attribute. |
Video duration breakdown7 fields
data
| Field | Type | Description |
|---|---|---|
rate_list | array | Statistics grouped by video duration. |
rate_list[] | object | One video duration group. |
rate_list[].duration | string | Label of the video duration group. |
rate_list[].content_rate | number | Share of content in this duration group. |
rate_list[].interaction_rate | number | Engagement rate for videos in this duration group. |
rate_list[].finish_rate | number | Completion rate for videos in this duration group. |
rate_list[].top_items_list | array | Top video groups for this duration, when present. |
Response Example
Loading the response example...