Search API Connector Documentation

Print

Import TikTok Ads Data to Google Sheets

In this guide, we’ll walk through how to import TikTok Ads data directly into Google Sheets, using the API Connector add-on for Sheets.

The TikTok Ads API is quite strange in that it uses a non-standard implementation of the OAuth2 standard. Therefore we will get our token through some custom API requests rather than through API Connector’s automatic OAuth2 connection manager.

Contents

Before You Begin

Click here to install the API Connector add-on from the Google Marketplace.

Part 1: Create a TikTok App

  1. Navigate to https://ads.tiktok.com/marketing_api/ and register for a new account.
    tiktok-ads-img1
  2. Once you’re logged in, click on My Apps in the top nav
    tiktok-ads-img2
  3. From the Apps screen, click Create New
    tiktok-ads-img3
  4. Set up your App, choosing the permissions you’d like access to. You can set the Callback address to anything, but https://www.google.com is good as it’s easy to access and doesn’t redirect.
    tiktok-ads-img4
  5. Your app will initially be in Pending status. Once it’s approved (should be a day or two), it will look like this. Click Edit to get your App ID and Secret, we’ll need those later.
    tiktok-ads-img5

Part 2: Get Your Auth Code

  1. Once your app has been approved, click on your app name from the apps dashboard
    tiktok-ads-img7
  2. Scroll down the page until you reach your authorized URL. Copy this to your clipboard.
    tiktok-ads-img8
  3. Paste this entire URL into a web browser
    tiktok-ads-img9
  4. You will see a modal prompting you to log in and accept whatever permissions you selected while creating your app. Click Confirm.
    tiktok-ads-img10
  5. You’ll now be sent to the site you sent as your callback URL (google.com in our example). On this screen you’ll see a URL in your URL bar. We’re looking for the value in the ‘auth_code’ parameter, so grab that and keep it safe. It’s probably easiest to just copy and paste the entire URL into your clipboard so you can extract it from there.
    tiktok-ads-img11
  6. All right, we’re all set with our values. Let’s hop over to API Connector and get our access token.

Part 3: Get Your Access Token

Choose the POST method and enter this the request URL for an access token

https://ads.tiktok.com/open_api/v1.2/oauth2/access_token/

In the POST body, enter all the values we collected above, like this:

{
    "secret": "xxxxx", 
    "app_id": "xxxxx", 
    "auth_code": "xxxxx"
}

Substitute in your secret, app ID, and authorization code. Name your request and click Run . The whole thing should look like this:
tiktok-ads-img12

Congrats, you have your access token! This is what we’ll use for getting ad data.

Part 4: Get TikTok Ad Data in Sheets

You can see a list of available endpoints in the docs.

As an example, choose the following options:

  • Method = GET
  • Request URL = https://ads.tiktok.com/open_api/v1.2/ad/get?advertiser_id=xxxxxxxx
  • Headers = Key: Access-Token, Value = {your access token}

Substitute in your own advertiser ID, as well as the access token from part 3.

The whole thing should look like this:

You can also specify particular fields, like this:

  • Method = GET
  • Request URL = https://ads.tiktok.com/open_api/v1.2/reports/ad/get/?advertiser_id=xxxxxxxxx&start_date=2021-02-01&end_date=2021-02-04&fields=["stat_cost","show_cnt","click_cost","ctr"]&page_size=1000
  • Headers = Key: Access-Token, Value = <your access token>tiktok-ads-img14

If you would like to see your data grouped by campaign name instead of by date, edit your URL to include a group_by=["STAT_GROUP_BY_FIELD_ID"] parameter like this:
https://ads.tiktok.com/open_api/v1.2/reports/ad/get/?advertiser_id=6942300208919281666&start_date=2021-03-15&end_date=2021-03-25&fields=["campaign_name","campaign_id","stat_cost","show_cnt","click_cost","ctr"]&group_by=["STAT_GROUP_BY_FIELD_ID"]&page_size=1000
tiktok-ads-img15

Part 5: Handle Pagination

By default, TikTok will return only 10 rows at a time. To get more you need to use the page and page_size parameters as shown in their API documentation:
tiktok-ads-img17

You can add these manually or cycle through pages automatically using API Connector’s pagination function (paid feature), like this:

  • API URL: enter your request URL as usual, including page_size=1000

  • Pagination type: page parameter

  • Page parameter: page

  • Number of pages: enter the number of pages you’d like to fetch

  • tiktok-ads-img18

    Previous Import TD Ameritrade Data to Sheets
    Next Import Todoist Data to Google Sheets

    Leave a Comment

    Table of Contents