TikTok Post Search API (V1)
Searches TikTok posts by keyword with offset pagination plus sorting, publish-time, and region controls. Use it to support regional content discovery, topic research, or monitoring keyword-related videos.
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
token | query | string | Yes | - | Security token for API access. |
keyword | query | string | Yes | - | Search keywords. |
offset | query | integer | No | 0 | Pagination offset, starting from 0 and stepping by 20. |
sortType | query | string | No | RELEVANCE | Sorting criteria for search results. Available Values: - RELEVANCE: Relevance (Default)- MOST_LIKED: Most Liked |
publishTime | query | string | No | ALL | Filter posts by publishing time. Available Values: - ALL: All Time- ONE_DAY: Last 24 Hours- ONE_WEEK: Last 7 Days- ONE_MONTH: Last 30 Days- THREE_MONTHS: Last 90 Days- HALF_YEAR: Last 180 Days |
region | query | string | No | US | ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB'). |
Code Samples
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE'I want to use the "Post Search (V1)" API from JustOneAPI.
Base URL: https://api.justoneapi.com.
API Path: /api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE
API Endpoint: BASE_URL + /api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE
HTTP Method: GET
Authentication: Append the "token" query parameter to the URL.
OpenAPI Definition: https://docs.justoneapi.com/openapi/tiktok/post-search-v1-en.json
Parameters:
- token (query): Security token for API access. (Required)
- keyword (query): Search keywords. (Required)
- offset (query): Pagination offset, starting from 0 and stepping by 20.
- sortType (query): Sorting criteria for search results.
Available Values:
- `RELEVANCE`: Relevance (Default)
- `MOST_LIKED`: Most Liked
- publishTime (query): Filter posts by publishing time.
Available Values:
- `ALL`: All Time
- `ONE_DAY`: Last 24 Hours
- `ONE_WEEK`: Last 7 Days
- `ONE_MONTH`: Last 30 Days
- `THREE_MONTHS`: Last 90 Days
- `HALF_YEAR`: Last 180 Days
- region (query): ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB').
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.import requests
BASE_URL = "https://api.justoneapi.com" # Provided by OpenAPI servers
url = BASE_URL + "/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE"
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")const BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
const url = BASE_URL + "/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE";
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`);
}
}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/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE";
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");
}
}
}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/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE"
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
$BASE_URL = 'https://api.justoneapi.com'; // Provided by OpenAPI servers
$url = $BASE_URL . '/api/tiktok/search-post/v1?token=YOUR_API_KEY&keyword=VALUE';
$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).
Search results and pagination6 fields
data
One page of TikTok post search results and pagination information.
| Field | Type | Description |
|---|---|---|
status_code | integer | Numeric status reported by TikTok for the search response. |
has_more | integer | Pagination flag. A value of 1 indicates more results are available, and 0 indicates the end of the results. |
cursor | integer | Pagination cursor. If has_more indicates more results, pass this cursor as offset in the next request. |
aweme_list | array | null | Additional post list returned by TikTok. This field can be empty or null. Search entries are available in search_item_list. |
search_item_list | array | null | Search entries on the current page. This field can be null at the end. Posts can recur between pages. Use each entry's aweme_info.aweme_id to deduplicate them. |
search_item_list[] | object | One search result entry. |
Post content23 fields
data.search_item_list[].aweme_info
Post data for the search entry, including content, author, and available media metadata.
| Field | Type | Description |
|---|---|---|
aweme_id | string | TikTok post ID represented as text. |
aweme_type | integer | Numeric post type code reported by TikTok. |
author_user_id | integer | Numeric TikTok author ID. For exact IDs in JavaScript use the text field author.uid. |
create_time | integer | Post publication time as a Unix timestamp in seconds. |
desc | string | Post caption supplied by TikTok. |
desc_language | string | Language code reported for the post caption. |
content_desc | string | Additional description text supplied for the post. |
search_desc | string | Description text returned for display in search results. |
share_url | string | Share URL for the post. |
region | string | Region code returned for the post. |
group_id | string | Content group identifier represented as text. |
is_ads | boolean | Whether TikTok marks the post as advertising. |
is_paid_content | boolean | Whether TikTok marks the post as paid content. |
is_close_friends_only | boolean | Whether the post is marked for close friends only. |
is_top | integer | Numeric pinned-post flag returned for this post. |
is_vr | boolean | Whether the post is marked as VR content. |
has_danmaku | boolean | Whether the post is marked as having a danmaku overlay. |
is_description_translatable | boolean | Whether TikTok marks the description as translatable. |
is_text_sticker_translatable | boolean | Whether TikTok marks the text stickers as translatable. |
is_title_translatable | boolean | Whether TikTok marks the title as translatable. |
prevent_download | boolean | Whether download prevention is marked for the post. |
music_begin_time_in_ms | integer | Music start position for the post in milliseconds. |
no_selected_music | boolean | Whether TikTok indicates the post has no selected music. |
Author15 fields
data.search_item_list[].aweme_info.author
TikTok account that published the post.
| Field | Type | Description |
|---|---|---|
uid | string | TikTok author ID represented as text. Use this field to preserve exact digits. |
unique_id | string | Public TikTok username or handle. |
nickname | string | Author display name. |
short_id | string | Short identifier field returned for the author. |
custom_verify | string | Custom verification label returned for the account. |
enterprise_verify_reason | string | Business verification text returned for the account. |
verification_type | integer | Numeric verification code returned for the account. |
follower_count | integer | Follower count reported for the author. |
following_count | integer | Number of accounts the author follows. |
total_favorited | integer | Like total reported for the author's posts. |
aweme_count | integer | Post count reported for the author. |
with_commerce_entry | boolean | Whether a commerce entry is marked for the account. |
with_shop_entry | boolean | Whether a shop entry is marked for the account. |
search_user_desc | string | Description text returned for the author in search results. |
search_user_name | string | Name text returned for the author in search results. |
Author avatars35 fields
data.search_item_list[].aweme_info.author
| Field | Type | Description |
|---|---|---|
avatar_168x168 | object | Author avatar in the 168x168 representation. |
avatar_168x168.uri | string | Media identifier or URI supplied by TikTok. |
avatar_168x168.url_list | array | Media URLs returned for this representation. |
avatar_168x168.url_list[] | string | One media URL for this representation. |
avatar_168x168.width | integer | Media width in pixels when reported. |
avatar_168x168.height | integer | Media height in pixels when reported. |
avatar_168x168.data_size | integer | Data size value reported for this representation. |
avatar_300x300 | object | Author avatar in the 300x300 representation. |
avatar_300x300.uri | string | Media identifier or URI supplied by TikTok. |
avatar_300x300.url_list | array | Media URLs returned for this representation. |
avatar_300x300.url_list[] | string | One media URL for this representation. |
avatar_300x300.width | integer | Media width in pixels when reported. |
avatar_300x300.height | integer | Media height in pixels when reported. |
avatar_300x300.data_size | integer | Data size value reported for this representation. |
avatar_larger | object | Larger author avatar representation. |
avatar_larger.uri | string | Media identifier or URI supplied by TikTok. |
avatar_larger.url_list | array | Media URLs returned for this representation. |
avatar_larger.url_list[] | string | One media URL for this representation. |
avatar_larger.width | integer | Media width in pixels when reported. |
avatar_larger.height | integer | Media height in pixels when reported. |
avatar_larger.data_size | integer | Data size value reported for this representation. |
avatar_medium | object | Medium author avatar representation. |
avatar_medium.uri | string | Media identifier or URI supplied by TikTok. |
avatar_medium.url_list | array | Media URLs returned for this representation. |
avatar_medium.url_list[] | string | One media URL for this representation. |
avatar_medium.width | integer | Media width in pixels when reported. |
avatar_medium.height | integer | Media height in pixels when reported. |
avatar_medium.data_size | integer | Data size value reported for this representation. |
avatar_thumb | object | Thumbnail author avatar representation. |
avatar_thumb.uri | string | Media identifier or URI supplied by TikTok. |
avatar_thumb.url_list | array | Media URLs returned for this representation. |
avatar_thumb.url_list[] | string | One media URL for this representation. |
avatar_thumb.width | integer | Media width in pixels when reported. |
avatar_thumb.height | integer | Media height in pixels when reported. |
avatar_thumb.data_size | integer | Data size value reported for this representation. |
Engagement10 fields
data.search_item_list[].aweme_info.statistics
Engagement metrics returned for the post.
| Field | Type | Description |
|---|---|---|
aweme_id | string | TikTok post ID for these statistics, represented as text. |
play_count | integer | View or play count reported for the post. |
digg_count | integer | Like count reported for the post. |
comment_count | integer | Comment count reported for the post. |
share_count | integer | Share count reported for the post. |
collect_count | integer | Save count reported for the post. |
download_count | integer | Download count reported for the post. |
repost_count | integer | Repost count reported for the post. |
forward_count | integer | Forward count reported separately for the post. |
whatsapp_share_count | integer | Share count reported for WhatsApp. |
Video and covers41 fields
data.search_item_list[].aweme_info.video
Video metadata and media representations, when supplied.
| Field | Type | Description |
|---|---|---|
duration | integer | Video duration in milliseconds. |
width | integer | Video width in pixels. |
height | integer | Video height in pixels. |
ratio | string | Video resolution or ratio label returned by TikTok. |
has_watermark | boolean | Whether the video is marked as having a watermark. |
cover_is_custom | boolean | Whether the video is marked as using a custom cover. |
big_thumbs | array | Thumbnail sprite metadata for the video, when available. |
big_thumbs[] | object | One thumbnail sprite entry. |
big_thumbs[].img_num | integer | Number of thumbnails reported for the sprite entry. |
big_thumbs[].img_url | string | URL for the thumbnail sprite. |
big_thumbs[].img_x_len | integer | Number of thumbnail columns reported for the sprite. |
big_thumbs[].img_y_len | integer | Number of thumbnail rows reported for the sprite. |
big_thumbs[].img_x_size | integer | Width of one thumbnail in pixels. |
big_thumbs[].img_y_size | integer | Height of one thumbnail in pixels. |
big_thumbs[].img_urls | array | Thumbnail sprite URLs returned for this entry. |
big_thumbs[].img_urls[] | string | One thumbnail sprite URL. |
cover | object | Video cover image. |
cover.uri | string | Media identifier or URI supplied by TikTok. |
cover.url_list | array | Media URLs returned for this representation. |
cover.url_list[] | string | One media URL for this representation. |
cover.width | integer | Media width in pixels when reported. |
cover.height | integer | Media height in pixels when reported. |
cover.data_size | integer | Data size value reported for this representation. |
origin_cover | object | Original cover representation returned for the video. |
origin_cover.uri | string | Media identifier or URI supplied by TikTok. |
origin_cover.url_list | array | Media URLs returned for this representation. |
origin_cover.url_list[] | string | One media URL for this representation. |
origin_cover.width | integer | Media width in pixels when reported. |
origin_cover.height | integer | Media height in pixels when reported. |
origin_cover.data_size | integer | Data size value reported for this representation. |
dynamic_cover | object | Dynamic cover representation for the video. |
dynamic_cover.uri | string | Media identifier or URI supplied by TikTok. |
dynamic_cover.url_list | array | Media URLs returned for this representation. |
dynamic_cover.url_list[] | string | One media URL for this representation. |
dynamic_cover.width | integer | Media width in pixels when reported. |
dynamic_cover.height | integer | Media height in pixels when reported. |
dynamic_cover.data_size | integer | Data size value reported for this representation. |
animated_cover | object | Animated cover representation for the video. |
animated_cover.uri | string | Media identifier or URI supplied by TikTok. |
animated_cover.url_list | array | Media URLs returned for this representation. |
animated_cover.url_list[] | string | One media URL for this representation. |
Playback and download addresses50 fields
data.search_item_list[].aweme_info.video
| Field | Type | Description |
|---|---|---|
bit_rate | array | Available video playback variants and associated encoding metadata. |
bit_rate[] | object | One video playback variant. |
bit_rate[].bit_rate | integer | Bitrate reported for the playback variant. |
bit_rate[].fps | integer | Frames per second reported for the playback variant. |
bit_rate[].gear_name | string | Quality tier label for the playback variant. |
bit_rate[].quality_type | integer | Numeric quality code reported for the playback variant. |
bit_rate[].HDR_type | string | HDR type label reported for the playback variant. |
bit_rate[].HDR_bit | string | HDR bit-depth label returned for the playback variant. |
bit_rate[].play_addr | object | Playback address metadata for this variant. |
bit_rate[].play_addr.uri | string | Media identifier or URI supplied by TikTok. |
bit_rate[].play_addr.url_list | array | Media URLs returned for this representation. |
bit_rate[].play_addr.url_list[] | string | One media URL for this representation. |
bit_rate[].play_addr.width | integer | Media width in pixels when reported. |
bit_rate[].play_addr.height | integer | Media height in pixels when reported. |
bit_rate[].play_addr.data_size | integer | Data size value reported for this representation. |
play_addr | object | Playback media representation for the video. |
play_addr.uri | string | Media identifier or URI supplied by TikTok. |
play_addr.url_list | array | Media URLs returned for this representation. |
play_addr.url_list[] | string | One media URL for this representation. |
play_addr.width | integer | Media width in pixels when reported. |
play_addr.height | integer | Media height in pixels when reported. |
play_addr.data_size | integer | Data size value reported for this representation. |
play_addr_h264 | object | H.264 playback media representation. |
play_addr_h264.uri | string | Media identifier or URI supplied by TikTok. |
play_addr_h264.url_list | array | Media URLs returned for this representation. |
play_addr_h264.url_list[] | string | One media URL for this representation. |
play_addr_h264.width | integer | Media width in pixels when reported. |
play_addr_h264.height | integer | Media height in pixels when reported. |
play_addr_h264.data_size | integer | Data size value reported for this representation. |
play_addr_bytevc1 | object | ByteVC1 playback media representation. |
play_addr_bytevc1.uri | string | Media identifier or URI supplied by TikTok. |
play_addr_bytevc1.url_list | array | Media URLs returned for this representation. |
play_addr_bytevc1.url_list[] | string | One media URL for this representation. |
play_addr_bytevc1.width | integer | Media width in pixels when reported. |
play_addr_bytevc1.height | integer | Media height in pixels when reported. |
play_addr_bytevc1.data_size | integer | Data size value reported for this representation. |
download_addr | object | Download media representation supplied for the video. |
download_addr.uri | string | Media identifier or URI supplied by TikTok. |
download_addr.url_list | array | Media URLs returned for this representation. |
download_addr.url_list[] | string | One media URL for this representation. |
download_addr.width | integer | Media width in pixels when reported. |
download_addr.height | integer | Media height in pixels when reported. |
download_addr.data_size | integer | Data size value reported for this representation. |
download_no_watermark_addr | object | Download representation identified as watermark-free. |
download_no_watermark_addr.uri | string | Media identifier or URI supplied by TikTok. |
download_no_watermark_addr.url_list | array | Media URLs returned for this representation. |
download_no_watermark_addr.url_list[] | string | One media URL for this representation. |
download_no_watermark_addr.width | integer | Media width in pixels when reported. |
download_no_watermark_addr.height | integer | Media height in pixels when reported. |
download_no_watermark_addr.data_size | integer | Data size value reported for this representation. |
Music details48 fields
data.search_item_list[].aweme_info.music
Music or sound metadata associated with the post.
| Field | Type | Description |
|---|---|---|
id | integer | Numeric music or sound ID. Use id_str for exact digits in JavaScript. |
id_str | string | Music or sound ID represented as text. |
mid | string | Music identifier field returned as text. |
title | string | Music or sound title. |
author | string | Display name for the music or sound author. |
album | string | Album name returned for the track. |
duration | integer | Music or sound duration in seconds. |
audition_duration | integer | Preview duration reported for the music. |
shoot_duration | integer | Recording duration reported for use of the music. |
video_duration | integer | Video duration value supplied in the music metadata. |
create_time | integer | Music or sound creation time as a Unix timestamp in seconds when supplied. |
user_count | integer | Number of users reported for use of the music. |
language | string | Language code returned for the music. |
owner_id | string | Sound owner's TikTok user ID represented as text. |
owner_handle | string | Sound owner's public TikTok username. |
owner_nickname | string | Display name of the sound owner. |
is_original_sound | boolean | Whether the item is marked as an original sound. |
is_commerce_music | boolean | Whether the music is marked as commercial music. |
is_author_artist | boolean | Whether the music author is marked as an artist. |
can_not_reuse | boolean | Whether the sound is marked as unavailable for reuse. |
has_human_voice | boolean | Whether this sound is marked as containing a human voice. |
duration_high_precision | object | Higher-precision duration figures returned for the music. |
duration_high_precision.duration_precision | number | Higher-precision duration value for the sound. |
duration_high_precision.audition_duration_precision | number | Higher-precision preview duration value. |
duration_high_precision.shoot_duration_precision | number | Higher-precision recording duration value. |
duration_high_precision.video_duration_precision | number | Higher-precision video duration value in the music metadata. |
matched_song | object | Matched song details for the sound, when supplied. |
matched_song.id | string | Matched song ID represented as text. |
matched_song.title | string | Matched song title. |
matched_song.author | string | Matched song author display name. |
matched_song.full_duration | integer | Full duration value reported for the matched song. |
matched_song.cover_medium | object | Cover representation for the matched song. |
matched_song.cover_medium.uri | string | Media identifier or URI supplied by TikTok. |
matched_song.cover_medium.url_list | array | Media URLs returned for this representation. |
matched_song.cover_medium.url_list[] | string | One media URL for this representation. |
matched_song.cover_medium.width | integer | Media width in pixels when reported. |
matched_song.cover_medium.height | integer | Media height in pixels when reported. |
matched_pgc_sound | object | Matched published sound details, when supplied. |
matched_pgc_sound.title | string | Matched published sound title. |
matched_pgc_sound.author | string | Matched published sound author display name. |
matched_pgc_sound.cover_medium | object | Cover representation for the matched published sound. |
matched_pgc_sound.cover_medium.uri | string | Media identifier or URI supplied by TikTok. |
matched_pgc_sound.cover_medium.url_list | array | Media URLs returned for this representation. |
matched_pgc_sound.cover_medium.url_list[] | string | One media URL for this representation. |
matched_pgc_sound.cover_medium.width | integer | Media width in pixels when reported. |
matched_pgc_sound.cover_medium.height | integer | Media height in pixels when reported. |
music_release_info | object | Release metadata associated with the track. |
music_release_info.is_new_release_song | boolean | Whether the song is marked as a new release. |
Music artists and media38 fields
data.search_item_list[].aweme_info.music
| Field | Type | Description |
|---|---|---|
artists | array | Artists associated with the music, when available. |
artists[] | object | One artist associated with the music. |
artists[].uid | string | TikTok artist account ID represented as text. |
artists[].handle | string | Public TikTok username of the artist. |
artists[].nick_name | string | Artist display name. |
artists[].is_verified | boolean | Whether the artist account is marked as verified. |
artists[].avatar | object | Avatar representation for the artist. |
artists[].avatar.uri | string | Media identifier or URI supplied by TikTok. |
artists[].avatar.url_list | array | Media URLs returned for this representation. |
artists[].avatar.url_list[] | string | One media URL for this representation. |
play_url | object | Playback representation for the sound. |
play_url.uri | string | Media identifier or URI supplied by TikTok. |
play_url.url_list | array | Media URLs returned for this representation. |
play_url.url_list[] | string | One media URL for this representation. |
play_url.width | integer | Media width in pixels when reported. |
play_url.height | integer | Media height in pixels when reported. |
play_url.data_size | integer | Data size value reported for this representation. |
cover_large | object | Large music cover representation. |
cover_large.uri | string | Media identifier or URI supplied by TikTok. |
cover_large.url_list | array | Media URLs returned for this representation. |
cover_large.url_list[] | string | One media URL for this representation. |
cover_large.width | integer | Media width in pixels when reported. |
cover_large.height | integer | Media height in pixels when reported. |
cover_large.data_size | integer | Data size value reported for this representation. |
cover_medium | object | Medium music cover representation. |
cover_medium.uri | string | Media identifier or URI supplied by TikTok. |
cover_medium.url_list | array | Media URLs returned for this representation. |
cover_medium.url_list[] | string | One media URL for this representation. |
cover_medium.width | integer | Media width in pixels when reported. |
cover_medium.height | integer | Media height in pixels when reported. |
cover_medium.data_size | integer | Data size value reported for this representation. |
cover_thumb | object | Thumbnail music cover representation. |
cover_thumb.uri | string | Media identifier or URI supplied by TikTok. |
cover_thumb.url_list | array | Media URLs returned for this representation. |
cover_thumb.url_list[] | string | One media URL for this representation. |
cover_thumb.width | integer | Media width in pixels when reported. |
cover_thumb.height | integer | Media height in pixels when reported. |
cover_thumb.data_size | integer | Data size value reported for this representation. |
Added sound details48 fields
data.search_item_list[].aweme_info.added_sound_music_info
Metadata for an added sound, when supplied.
| Field | Type | Description |
|---|---|---|
id | integer | Numeric music or sound ID. Use id_str for exact digits in JavaScript. |
id_str | string | Music or sound ID represented as text. |
mid | string | Music identifier field returned as text. |
title | string | Music or sound title. |
author | string | Display name for the music or sound author. |
album | string | Album name returned for the track. |
duration | integer | Music or sound duration in seconds. |
audition_duration | integer | Preview duration reported for the music. |
shoot_duration | integer | Recording duration reported for use of the music. |
video_duration | integer | Video duration value supplied in the music metadata. |
create_time | integer | Music or sound creation time as a Unix timestamp in seconds when supplied. |
user_count | integer | Number of users reported for use of the music. |
language | string | Language code returned for the music. |
owner_id | string | Sound owner's TikTok user ID represented as text. |
owner_handle | string | Sound owner's public TikTok username. |
owner_nickname | string | Display name of the sound owner. |
is_original_sound | boolean | Whether the item is marked as an original sound. |
is_commerce_music | boolean | Whether the music is marked as commercial music. |
is_author_artist | boolean | Whether the music author is marked as an artist. |
can_not_reuse | boolean | Whether the sound is marked as unavailable for reuse. |
has_human_voice | boolean | Whether this sound is marked as containing a human voice. |
duration_high_precision | object | Higher-precision duration figures returned for the music. |
duration_high_precision.duration_precision | number | Higher-precision duration value for the sound. |
duration_high_precision.audition_duration_precision | number | Higher-precision preview duration value. |
duration_high_precision.shoot_duration_precision | number | Higher-precision recording duration value. |
duration_high_precision.video_duration_precision | number | Higher-precision video duration value in the music metadata. |
matched_song | object | Matched song details for the sound, when supplied. |
matched_song.id | string | Matched song ID represented as text. |
matched_song.title | string | Matched song title. |
matched_song.author | string | Matched song author display name. |
matched_song.full_duration | integer | Full duration value reported for the matched song. |
matched_song.cover_medium | object | Cover representation for the matched song. |
matched_song.cover_medium.uri | string | Media identifier or URI supplied by TikTok. |
matched_song.cover_medium.url_list | array | Media URLs returned for this representation. |
matched_song.cover_medium.url_list[] | string | One media URL for this representation. |
matched_song.cover_medium.width | integer | Media width in pixels when reported. |
matched_song.cover_medium.height | integer | Media height in pixels when reported. |
matched_pgc_sound | object | Matched published sound details, when supplied. |
matched_pgc_sound.title | string | Matched published sound title. |
matched_pgc_sound.author | string | Matched published sound author display name. |
matched_pgc_sound.cover_medium | object | Cover representation for the matched published sound. |
matched_pgc_sound.cover_medium.uri | string | Media identifier or URI supplied by TikTok. |
matched_pgc_sound.cover_medium.url_list | array | Media URLs returned for this representation. |
matched_pgc_sound.cover_medium.url_list[] | string | One media URL for this representation. |
matched_pgc_sound.cover_medium.width | integer | Media width in pixels when reported. |
matched_pgc_sound.cover_medium.height | integer | Media height in pixels when reported. |
music_release_info | object | Release metadata associated with the track. |
music_release_info.is_new_release_song | boolean | Whether the song is marked as a new release. |
Added sound artists and media38 fields
data.search_item_list[].aweme_info.added_sound_music_info
| Field | Type | Description |
|---|---|---|
artists | array | Artists associated with the music, when available. |
artists[] | object | One artist associated with the music. |
artists[].uid | string | TikTok artist account ID represented as text. |
artists[].handle | string | Public TikTok username of the artist. |
artists[].nick_name | string | Artist display name. |
artists[].is_verified | boolean | Whether the artist account is marked as verified. |
artists[].avatar | object | Avatar representation for the artist. |
artists[].avatar.uri | string | Media identifier or URI supplied by TikTok. |
artists[].avatar.url_list | array | Media URLs returned for this representation. |
artists[].avatar.url_list[] | string | One media URL for this representation. |
play_url | object | Playback representation for the sound. |
play_url.uri | string | Media identifier or URI supplied by TikTok. |
play_url.url_list | array | Media URLs returned for this representation. |
play_url.url_list[] | string | One media URL for this representation. |
play_url.width | integer | Media width in pixels when reported. |
play_url.height | integer | Media height in pixels when reported. |
play_url.data_size | integer | Data size value reported for this representation. |
cover_large | object | Large music cover representation. |
cover_large.uri | string | Media identifier or URI supplied by TikTok. |
cover_large.url_list | array | Media URLs returned for this representation. |
cover_large.url_list[] | string | One media URL for this representation. |
cover_large.width | integer | Media width in pixels when reported. |
cover_large.height | integer | Media height in pixels when reported. |
cover_large.data_size | integer | Data size value reported for this representation. |
cover_medium | object | Medium music cover representation. |
cover_medium.uri | string | Media identifier or URI supplied by TikTok. |
cover_medium.url_list | array | Media URLs returned for this representation. |
cover_medium.url_list[] | string | One media URL for this representation. |
cover_medium.width | integer | Media width in pixels when reported. |
cover_medium.height | integer | Media height in pixels when reported. |
cover_medium.data_size | integer | Data size value reported for this representation. |
cover_thumb | object | Thumbnail music cover representation. |
cover_thumb.uri | string | Media identifier or URI supplied by TikTok. |
cover_thumb.url_list | array | Media URLs returned for this representation. |
cover_thumb.url_list[] | string | One media URL for this representation. |
cover_thumb.width | integer | Media width in pixels when reported. |
cover_thumb.height | integer | Media height in pixels when reported. |
cover_thumb.data_size | integer | Data size value reported for this representation. |
Hashtags, mentions, and search highlights37 fields
data.search_item_list[].aweme_info
| Field | Type | Description |
|---|---|---|
cha_list | array | null | Hashtag or challenge entries associated with the post, when provided. |
cha_list[] | object | One hashtag or challenge attached to the post. |
cha_list[].cid | string | Hashtag or challenge ID represented as text. |
cha_list[].cha_name | string | Hashtag or challenge name. |
cha_list[].desc | string | Hashtag or challenge description. |
cha_list[].type | integer | Numeric tag or challenge type reported by TikTok. |
cha_list[].use_count | integer | Usage count reported for the hashtag or challenge. |
cha_list[].user_count | integer | User count reported for the hashtag or challenge. |
cha_list[].view_count | integer | View count reported for the hashtag or challenge. |
cha_list[].is_commerce | boolean | Whether the hashtag or challenge is marked as commercial. |
search_highlight | array | Text highlight information supplied for search results. |
search_highlight[] | object | One set of highlights for a search text field. |
search_highlight[].field | string | Name of the search text field to highlight. |
search_highlight[].positions | array | Ranges to highlight in this text field. |
search_highlight[].positions[] | object | One highlight range in this text field. |
search_highlight[].positions[].begin | integer | Beginning position of the highlight range. |
search_highlight[].positions[].end | integer | Ending position of the highlight range. |
content_desc_extra | array | Annotations for the additional post description, such as hashtags or mentions. |
content_desc_extra[] | object | An annotation in the additional post description. |
content_desc_extra[].start | integer | Start position of the annotation in the corresponding text. |
content_desc_extra[].end | integer | End position of the annotation in the corresponding text. |
content_desc_extra[].hashtag_id | string | TikTok hashtag ID represented as text. |
content_desc_extra[].hashtag_name | string | Hashtag name attached to this annotation. |
content_desc_extra[].user_id | string | TikTok user ID for a mention, represented as text when present. |
content_desc_extra[].type | integer | Numeric annotation type returned by TikTok. |
content_desc_extra[].sub_type | integer | Numeric annotation subtype returned by TikTok. |
content_desc_extra[].is_commerce | boolean | Whether the annotation is marked as commercial. |
text_extra | array | Annotations for the post caption, such as hashtags or mentions. |
text_extra[] | object | An annotation in the post caption. |
text_extra[].start | integer | Start position of the annotation in the corresponding text. |
text_extra[].end | integer | End position of the annotation in the corresponding text. |
text_extra[].hashtag_id | string | TikTok hashtag ID represented as text. |
text_extra[].hashtag_name | string | Hashtag name attached to this annotation. |
text_extra[].user_id | string | TikTok user ID for a mention, represented as text when present. |
text_extra[].type | integer | Numeric annotation type returned by TikTok. |
text_extra[].sub_type | integer | Numeric annotation subtype returned by TikTok. |
text_extra[].is_commerce | boolean | Whether the annotation is marked as commercial. |
Visibility and interaction permissions14 fields
data.search_item_list[].aweme_info
| Field | Type | Description |
|---|---|---|
status | object | Post visibility and interaction status reported by TikTok. |
status.aweme_id | string | TikTok post ID associated with this status information. |
status.allow_comment | boolean | Whether comments are marked as allowed. |
status.allow_share | boolean | Whether sharing is marked as allowed. |
status.download_status | integer | Numeric download status reported for the post. |
status.is_delete | boolean | Whether the post is marked as deleted. |
status.is_prohibited | boolean | Whether the post is marked as restricted. |
status.private_status | integer | Numeric privacy status reported for the post. |
interact_permission | object | Interaction availability and permission flags for the post. |
interact_permission.allow_adding_as_post | object | Whether adding the content as a post is marked as allowed. |
interact_permission.allow_adding_to_story | integer | Whether adding the content to a story is marked as allowed. |
interact_permission.duet | integer | Duet availability flag reported for the post. |
interact_permission.stitch | integer | Stitch availability flag reported for the post. |
interact_permission.allow_create_sticker | object | Whether creating a sticker is marked as allowed. |
Sharing5 fields
data.search_item_list[].aweme_info.share_info
Text and link metadata for sharing the post.
| Field | Type | Description |
|---|---|---|
share_title | string | Title supplied for sharing the post. |
share_desc | string | Description supplied for sharing the post. |
share_link_desc | string | Display description for the post share link. |
share_quote | string | Quote text supplied for sharing. |
share_url | string | Share URL for the post. |
Places and paid content26 fields
data.search_item_list[].aweme_info
| Field | Type | Description |
|---|---|---|
poi_data | object | Public place information attached to the post, when provided. |
poi_data.poi_id | string | Place ID represented as text. |
poi_data.poi_name | string | Public place name. |
poi_data.location_desc | string | Display text describing the place location. |
poi_data.poi_type | string | Place type reported by TikTok. |
poi_data.video_count | integer | Video count reported for the place. |
poi_data.address_info | object | Public address details attached to the place. |
poi_data.address_info.city_name | string | City name reported for the place. |
poi_data.address_info.region_code | string | Region code reported for the place. |
poi_data.address_info.address | string | Public address text for the place. |
poi_data.thumbnail | object | Thumbnail attached to the public place. |
poi_data.thumbnail.uri | string | Media identifier or URI supplied by TikTok. |
poi_data.thumbnail.url_list | array | Media URLs returned for this representation. |
poi_data.thumbnail.url_list[] | string | One media URL for this representation. |
poi_data.thumbnail.width | integer | Media width in pixels when reported. |
poi_data.thumbnail.height | integer | Media height in pixels when reported. |
paid_content_info | object | Paid-content display metadata, when present. |
paid_content_info.collection_name | string | Display name of the paid collection. |
paid_content_info.episode_num | integer | Episode number reported for the content. |
paid_content_info.is_limited_free | boolean | Whether the content is marked as free for a limited time. |
paid_content_info.cover_url | object | Cover image metadata for the paid content. |
paid_content_info.cover_url.uri | string | Media identifier or URI supplied by TikTok. |
paid_content_info.cover_url.url_list | array | Media URLs returned for this representation. |
paid_content_info.cover_url.url_list[] | string | One media URL for this representation. |
paid_content_info.cover_url.width | integer | Media width in pixels when reported. |
paid_content_info.cover_url.height | integer | Media height in pixels when reported. |