Skip to content

Douyin Index Creation Guide API (V1) ​

GET
API health status
Healthy Available Limited Mostly unavailable No data
Loading health status...

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 ​

NameInTypeRequiredDefaultDescription
tokenquerystringYes-Authentication token for this API service.
analysisTypequerystringYes-Creation Guide analysis tab.


Available Values:

- CREATIVITY: Creative insights and rankings

- PRODUCTION: Content production analysis

- CONSUMPTION: Content consumption analysis
dataTypequerystringYes-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
verticalquerystringNo-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
periodquerystringNo-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
startDatequerystringNo-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.
endDatequerystringNo-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

FieldTypeDescription
daystringLatest published day for content reports and keyword or topic rankings, in YYYYMMDD format.
weekstringEnd date of the latest published week for content reports and keyword or topic rankings, in YYYYMMDD format.
monthstringEnd date of the latest published month for content reports, in YYYYMMDD format.
earliest_weekstringEnd date of the earliest available content reporting week, in YYYYMMDD format.
latest_daystringLatest published day for popular video rankings, in YYYYMMDD format.
start_weekstringEnd date of the earliest available video ranking week, in YYYYMMDD format.
end_weekstringEnd date of the latest available video ranking week, in YYYYMMDD format.
Popular keywords7 fields

data

FieldTypeDescription
keyword_listarrayPopular keywords for the selected vertical and period.
keyword_list[]objectOne popular keyword.
keyword_list[].keywordstringKeyword text.
keyword_list[].cntstringNumber of videos associated with the keyword, expressed as a string.
keyword_list[].is_hotbooleanHot-keyword indicator returned by Douyin.
keyword_list[].indexstringComposite index, expressed as a string.
keyword_list[].search_indexstringSearch index, expressed as a string.
Popular topics9 fields

data

FieldTypeDescription
topic_listarrayPopular topics for the selected vertical and period.
topic_list[]objectOne popular topic.
topic_list[].idstringDouyin topic identifier.
topic_list[].namestringTopic name.
topic_list[].indexstringTopic index, expressed as a string.
topic_list[].item_cntstringSubmission count, expressed as a string.
topic_list[].vvstringView count, expressed as a string.
topic_list[].digg_cntstringLike count, expressed as a string.
topic_list[].item_listarrayRelated entries, when present.
Popular videos18 fields

data

FieldTypeDescription
video_infosarrayPopular videos for the selected vertical and period.
video_infos[]objectOne video in the ranking.
video_infos[].item_idstringDouyin video identifier.
video_infos[].author_fansstringCreator follower count, expressed as a string.
video_infos[].indexstringVideo index, expressed as a string.
video_infos[].like_cntstringLike count, expressed as a string.
video_infos[].seqstringPosition in the ranking, expressed as a string.
video_infos[].video_titlestringVideo title.
video_infos[].authorstringCreator display name.
video_infos[].comment_cntstringComment count, expressed as a string.
video_infos[].forward_cntstringShare count, expressed as a string.
video_infos[].thumbnailstringVideo thumbnail URL.
video_infos[].avatar_urlstringCreator avatar URL.
video_infos[].statusstringVideo status value.
video_infos[].play_cntstringView count, expressed as a string.
video_infos[].author_idstringDouyin creator identifier.
page_respobjectRanking result count.
page_resp.total_numstringTotal reported for the video ranking, expressed as a string.
Content production12 fields

data

FieldTypeDescription
author_listarrayTrend series for content creators.
author_list[]objectOne day in the trend.
author_list[].datestringReporting date in YYYYMMDD format.
author_list[].ratenumberValue of this trend point.
item_listarrayTrend series for published content.
item_list[]objectOne day in the trend.
item_list[].datestringReporting date in YYYYMMDD format.
item_list[].ratenumberValue of this trend point.
dataarrayCreator profile distributions for the selected vertical and period.
data[]objectOne attribute in the audience or creator profile.
data[].name_enstringIdentifier for the profile attribute.
data[].label_listarrayDistribution entries for this attribute.
Content consumption20 fields

data

FieldTypeDescription
supply_trendarrayTrend series for content supply.
supply_trend[]objectOne day in the trend.
supply_trend[].datestringReporting date in YYYYMMDD format.
supply_trend[].ratenumberValue of this trend point.
consume_trendobjectContent consumption trend and associated top entries.
consume_trend.rate_listarrayTime series returned for the selected period.
consume_trend.rate_list[]objectOne reported observation.
consume_trend.top_listarrayTop entries returned with the trend.
interact_trendobjectContent engagement trend and associated top entries.
interact_trend.rate_listarrayTime series returned for the selected period.
interact_trend.rate_list[]objectOne reported observation.
interact_trend.top_listarrayTop entries returned with the trend.
play_dataarrayAudience profile distributions for video viewing.
play_data[]objectOne attribute in the audience or creator profile.
play_data[].name_enstringIdentifier for the profile attribute.
play_data[].label_listarrayDistribution entries for this attribute.
interaction_dataarrayAudience profile distributions for video engagement.
interaction_data[]objectOne attribute in the audience or creator profile.
interaction_data[].name_enstringIdentifier for the profile attribute.
interaction_data[].label_listarrayDistribution entries for this attribute.
Video duration breakdown7 fields

data

FieldTypeDescription
rate_listarrayStatistics grouped by video duration.
rate_list[]objectOne video duration group.
rate_list[].durationstringLabel of the video duration group.
rate_list[].content_ratenumberShare of content in this duration group.
rate_list[].interaction_ratenumberEngagement rate for videos in this duration group.
rate_list[].finish_ratenumberCompletion rate for videos in this duration group.
rate_list[].top_items_listarrayTop video groups for this duration, when present.

Response Example ​

Loading the response example...