Monitoring Keywords¶

We've already seen how to monitor hashtags, and monitoring keywords is strikingly similar. Just like for hashtags, there are two endpoints for fetching posts based on a keyword. Let's first look at the Keyword Search API.

Keyword Search API¶

API Documentation

Sample Response

Here's how you can find posts for the keyword tesla.

We'll also specify the period to search within, which can be one of 0, 1, 7, 30, 90, 180 days. We use period=180 for this example, and as such, we'll only get posts from the last 180 days.

Python (requests)Python (SDK)Node.js (SDK)

import requests

result = requests.get(
    "https://ensembledata.com/apis/tt/keyword/search",
    params={
        "name": "tesla",
        "period": 180,
        "token": "API_TOKEN",
    }
).json()["data"]

posts = result["data"]
print("Number of posts:", len(posts))

# We'll need this later!
next_cursor = result["nextCursor"]

from ensembledata.api import EDClient

client = EDClient("API_TOKEN")
result = client.tiktok.keyword_search(
    keyword="tesla"
    period="180",
)

posts = result.data["data"]
print("Number of posts:", len(posts))

# We'll need this later!
next_cursor = result.data.get("nextCursor")

const { EDClient } = require("ensembledata");

const client = new EDClient({ token: "API_TOKEN" });
let result = await client.tiktok.keywordSearch({ 
    keyword: "tesla"
    period: "180",
});

let posts = result.data.data;
console.log("Number of posts:", posts.length);

// We'll need this later!
let nextCursor = result.data.nextCursor;

Output:

Number of posts: 20

Great! We've got 20 posts, now let's see how we can get more.

Extra parameters¶

For a complete overview of the available parameters, please refer to the API Documentation for this endpoint.

Specify country¶

TikTok presents different posts for a keyword based on the country the user is in. The country parameter allows you to take advantage of this by specifying which country you would like to do the keyword search for.

The country is specified via the ISO 3166-1 alpha-2 country code. For example, let's search using the keyword tesla in the United States.

Python (requests)Python (SDK)Node.js (SDK)

result = requests.get(
    "https://ensembledata.com/apis/tt/keyword/search",
    params={
        "name": "tesla",
        "period": 180,
        "country": "US",
        "token": "API_TOKEN",
    }
).json()["data"]

result = client.tiktok.keyword_search(
    keyword="tesla", 
    period="180", 
    country="US"
)

const result = await client.tiktok.keywordSearch({
    keyword: "tesla", 
    period: "180", 
    country: "US"
})

Warning

This doesn't necessarily mean that the posts returned will be only from the specified country, but rather that the posts are those shown in that country.

Sort posts¶

You can specify how to sort the posts via the sorting parameter which

0 - Sorts the posts by relevance (default)
1 - Sorts the posts by likes

Python (requests)Python (SDK)Node.js (SDK)

result = requests.get(
    "https://ensembledata.com/apis/tt/keyword/search",
    params={
        "name": "tesla",
        "period": 180,
        "sorting": "1",
        "token": "API_TOKEN",
    }
).json()["data"]

result = client.tiktok.keyword_search(
    keyword="tesla", 
    period="180", 
    sorting="1"
)

const result = await client.tiktok.keywordSearch({
    keyword: "tesla", 
    period: "180", 
    sorting: "1"
})

Fetching more posts¶

To get more posts, we'll join forces with our friend the cursor again. To get the next batch of posts, we'll call the Keyword Search API again but this time with the next cursor value we got from the previous request.

Python (requests)Python (SDK)Node.js (SDK)

result = requests.get(
    "https://ensembledata.com/apis/tt/keyword/search",
    params={
        "name": "tesla",
        "period": 180,
        "cursor": next_cursor,
        "token": "API_TOKEN",
    }
).json()["data"]
posts = result["data"]
next_cursor = result.get("nextCursor", None)

result = client.tiktok.keyword_search(keyword="tesla", cursor=next_cursor)
posts = result.data["data"]
next_cursor = result.data.get("nextCursor")

result = await client.tiktok.keywordSearch({ 
    keyword: "tesla", 
    cursor: nextCursor,
});
posts = result.data.data;
nextCursor = result.data.nextCursor;

You can continue this process until you've fetched all the available posts for this keyword. You'll know you've fetched all the posts once there is no 'nextCursor' in the response.

Cursor handling example¶

Here's an example of how you could manually handle the cursor to fetch posts for a given keyword.

Python (requests)Python (SDK)Node.js (SDK)

posts = list()
cursor = 0

for _ in range(10):
    result = requests.get(
        "https://ensembledata.com/apis/tt/keyword/search",
        params={
            "name": "tesla",
            "period": 180,
            "cursor": cursor,
            "token": "API_TOKEN",
        }
    ).json()["data"]
    posts.extend(result["data"])
    cursor = result.get("nextCursor", None)

    # If there is no next cursor, we've fetched all the available posts
    if cursor is None:
        break

print("Number of posts:", len(posts))

posts = list()
cursor = None

for _ in range(10):
    result = client.tiktok.keyword_search(keyword="tesla", cursor=cursor)
    posts.extend(result.data["data"])
    cursor = result.data.get("nextCursor")

    # If there is no next cursor, we've fetched all the available posts
    if cursor is None:
        break

print("Number of posts:", len(posts))

let posts = [];
let cursor;

for (let i = 0; i < 10; i++) {
    result = await client.tiktok.keywordSearch({ 
        keyword: "tesla",
        cursor,
    });
    posts.push(...result.data.data);
    cursor = result.data.nextCursor;

    // If there is no next cursor, we've fetched all the available posts
    if (cursor === undefined) {
        break;
    }
}

console.log("Number of posts:", posts.length);

Output:

Number of posts: 200

Handling the cursor manually like this is perfectly fine and not all too difficult, however, the next section will show you how you can get the EnsembleData API to do this for you.

Full Keyword Search API¶

API Documentation

Sample Response

Automatic cursor handling¶

The Full Keyword Search API is very similar to the Keyword Search API, but it automatically handles the cursor for you. This means you can fetch all the posts for a keyword without having to worry about the cursor.

Python (requests)Python (SDK)Node.js (SDK)

result = requests.get(
    "https://ensembledata.com/apis/tt/keyword/full-search",
    params={
        "name": "tesla",
        "period": 180,
        "token": "API_TOKEN",
    }
).json()["data"]
posts = result
print("Number of posts:", len(posts))

result = client.tiktok.full_keyword_search(
    keyword="tesla", 
    period="180"
)
posts = result.data["data"]
print("Number of posts:", len(posts))

let result = await client.tiktok.fullKeywordSearch({ 
    keyword: "tesla",
    period: "180",
});
let posts = result.data.data;
console.log("Number of posts:", posts.length);

Output:

Number of posts: 1366

There we go! We've fetched all the posts for the keyword tesla in one API call without having to worry about the cursor.

Warning

The Full Keyword Search API can take quite a long time to respond, due to all the requests it has to send internally. Make sure to set a high enough timeout (> 10 mins) if you are configuring your own HTTP requests. If you are using one of the EnsembleData API packages, this is handled for you!

Extra parameters¶

The Full Keyword Search API supports mostly the same parameters as the Keyword Search API. For a complete overview of the available parameters, please refer to the API Documentation for this endpoint.