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 request URL for an access token

https://business-api.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! Finally! 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 and metrics in the docs. Note that the base domain was recently (September 2021) updated from ads.tiktok.com to business-api.tiktok.com.

As an example, enter a request like this:

https://business-api.tiktok.com/open_api/v1.2/reports/integrated/get/?advertiser_id=1111111111111111&report_type=BASIC&dimensions=["stat_time_day","ad_id"]&data_level=AUCTION_AD&start_date=2021-01-01&end_date=2021-01-31&metrics=["spend","impressions","cpc","cpm","ctr","reach"]&order_field=impressions&page_size=1000
tiktok-ads-img16

You’ll see a few types of parameters in the URL:

  • The “dimensions” parameter indicates how to group the data (the example above groups by day and ad ID)
  • The “metrics” parameter indicates the fields you’d like to include.
  • The “data_level” parameter shows how granular you want your data (by account, campaign, adgroup, or ad)
  • The “order_field” parameter shows which field to order by.
  • The “page_size” parameter shows the number of records to return; see the section called Handle Pagination for some more info on that.

The documentation contains the full list of available metrics (and other parameters).

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 parameters manually or cycle through pages automatically using API Connector’s pagination function (paid feature), like this:
API URLenter your request URL, including &page_size=1000
Pagination typepage parameter
Page parameterpage
Number of pagesenter the number of pages you’d like to fetch

pagination-page-parameter

Part 6: API Documentation

Official API documentation: https://ads.tiktok.com/marketing_api/docs

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

Leave a Comment

Table of Contents