Douyin Related Keywords & Trend Index (by Keyword and Week)

{
  "type": "object",
  "required": [
    "end_date",
    "keyword",
    "start_date"
  ],
  "properties": {
    "keyword": {
      "type": "string",
      "description": "Keyword"
    },
    "app_name": {
      "enum": [
        "aweme",
        "toutiao"
      ],
      "type": "string",
      "default": "aweme",
      "description": "Platform app to query: aweme (Douyin short-video app) or toutiao (Toutiao news app). Defaults to aweme."
    },
    "end_date": {
      "type": "string",
      "description": "End date (must be Sunday) YYYYMMDD"
    },
    "start_date": {
      "type": "string",
      "description": "Start date (Monday) YYYYMMDD"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "word": {
      "type": "string",
      "description": "The queried keyword echoed back exactly as submitted. Present only when the keyword has Douyin presence for the week."
    },
    "BaseResp": {
      "type": "object",
      "properties": {
        "StatusCode": {
          "type": "integer",
          "description": "0 (normal completion) on both real calls observed; a non-zero code on an upstream-side error would appear here (never observed)."
        },
        "StatusMessage": {
          "type": "string",
          "description": "Empty string on both real calls observed; an error message would appear here on failure (never observed, so its exact text is unconfirmed)."
        }
      },
      "description": "Status wrapper present on every response.",
      "additionalProperties": true
    },
    "relation_word_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "score_rank": {
            "type": "string",
            "description": "Rank of this related keyword by relatedness (lower = more related), as a digit string (e.g. '2')."
          },
          "score_rate": {
            "type": "string",
            "description": "Week-over-week change in the relation score, e.g. '-0.91%'; the literal '新' marks a keyword newly appearing on the list this week."
          },
          "search_hot": {
            "type": "string",
            "description": "Search heat value for this related keyword; observed as the string '0' on every entry in testing."
          },
          "compos_index": {
            "type": "string",
            "description": "The composite index value for this related keyword, as a digit string (e.g. '1905688')."
          },
          "content_list": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string",
                  "description": "The post's caption/title, in Chinese; may embed @-mentions of public accounts and hashtags."
                },
                "item_id": {
                  "type": "string",
                  "description": "The post's numeric Douyin video id, as a digit string; identifies a public trending post, not an individual."
                }
              },
              "additionalProperties": true
            },
            "description": "Sample trending posts for this related keyword -- three on every entry in testing. Only the post id and title are returned; the post's video-page URL is not (it is reachable as https://www.douyin.com/video/<item_id>)."
          },
          "search_index": {
            "type": "string",
            "description": "The search index value for this related keyword, as a digit string (e.g. '1469717')."
          },
          "search_ratio": {
            "type": "number",
            "description": "Search ratio for this related keyword; observed 0 on every entry in testing."
          },
          "relation_word": {
            "type": "string",
            "description": "The related keyword, in Chinese matching Douyin's own language (e.g. '美味')."
          },
          "relation_score": {
            "type": "number",
            "description": "Relatedness score, higher = more closely related; observed 0.00198-0.01387 in testing."
          },
          "score_rate_rank": {
            "type": "string",
            "description": "Rank of the week-over-week change (lower = bigger gainer), as a digit string (e.g. '83')."
          },
          "correlation_change": {
            "type": "boolean",
            "description": "Whether this related keyword's correlation with the queried word changed for the week; observed true and false."
          }
        },
        "additionalProperties": true
      },
      "description": "Post-side related keywords for the queried word. Each carries nine score/index/rank fields and up to three sample trending posts. ABSENT -- not `null`, not `[]` -- when the queried keyword has no Douyin presence (e.g. a nonsense keyword); check for absence to detect an empty result."
    },
    "search_relation_word_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "query_list": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Example search phrases customers actually search for this related keyword -- five strings on every entry in testing, in the keyword's own language."
          },
          "score_rank": {
            "type": "string",
            "description": "Rank of this related keyword by relatedness, as a digit string."
          },
          "score_rate": {
            "type": "string",
            "description": "Week-over-week change in the relation score, e.g. '5.79%' or '-10.75%'; the literal '新' marks a keyword newly appearing this week."
          },
          "search_hot": {
            "type": "string",
            "description": "Search heat value; observed as the string '0' on every entry in testing."
          },
          "compos_index": {
            "type": "string",
            "description": "The composite index value, as a digit string."
          },
          "search_index": {
            "type": "string",
            "description": "The search index value, as a digit string."
          },
          "search_ratio": {
            "type": "number",
            "description": "Search ratio; observed 0 on every entry in testing."
          },
          "relation_word": {
            "type": "string",
            "description": "The related search keyword, in Chinese (e.g. '蜡笔小新')."
          },
          "relation_score": {
            "type": "number",
            "description": "Relatedness score, higher = more closely related; observed 0.0017-0.0156 in testing."
          },
          "score_rate_rank": {
            "type": "string",
            "description": "Rank of the week-over-week change, as a digit string."
          },
          "correlation_change": {
            "type": "boolean",
            "description": "Whether this related keyword's correlation changed for the week; observed true and false."
          }
        },
        "additionalProperties": true
      },
      "description": "Search-side related keywords: what people actually search around the queried word. Each carries the same nine score/index/rank fields plus a `query_list[]` of example search phrases, and has no sample posts. ABSENT -- not `null`, not `[]` -- when the queried keyword has no Douyin presence, same as `relation_word_list`."
    }
  },
  "description": "The relation-word analysis document: the queried keyword echoed back, a post-side and a search-side list of related keywords each with their index/score/rank fields, and a status wrapper. When the queried keyword has no Douyin presence for the week, only BaseResp is present -- `word` and both lists are left out entirely (e.g. a nonsense keyword).",
  "additionalProperties": true
}