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 (may take a day or two), it will look like this. Click the App Name to see the App Detail screen.
    tiktokads-appname
  6. You’ll now see your App ID and Secret. Keep those handy, we’ll need them shortly.
    tiktokads-credentials

Part 2: Get Your Auth Code

  1. Still in the Basic Information page, copy the entire Advertiser authorization URL to your clipboard
    tiktokads-authurl
  2. Paste this URL into a web browser
    tiktok-ads-img9
  3. 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
  4. 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
  5. 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:
tiktokads-gettokenresponse

Note the value in the data.access_token field. Congrats, that’s your token. Finally! This is what we’ll use for getting ad data.

Part 4: Get TikTok Ad Data in Sheets

To create a request, include your full request URL in the request URL field, and include your access token in the Headers section, where Key = Access-Token and Value = your token.

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
  • Run untilchoose when to stop fetching data
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

15 thoughts on “Import TikTok Ads Data to Google Sheets”

  1. This does not work for me, as I only get an empty result []. When redoing the first steps I realise there are no authorised accounts (although I use the TikTok Ads account I run all the campaigns with). Could this be the problem? How do I authorise accounts?

    Reply
    • Sorry, I’m not sure how to authorize accounts either. On my side, I created the app and then plugged in my advertiser account ID, I didn’t authorize an account. Which request is returning []?

      Reply
  2. Hi Ana, I’ve followed all of the steps above but after running it I’m getting a code 40007 saying that The advertiser [my App ID] doesn’t exist or has been deleted. Please help!

    Reply
  3. Hello Ana, thanks for sharing the information on Tiktok API.

    I am a researcher and I have a question. I have identified over 200 doctors on tiktok (creating tiktok doctor yellow page ). Since their numbers of followers are constantly changing, is there a way to track & update their followers using API?

    Reply
  4. Hi Ana, great article! Is there any way to set the call to always return yesterday’s data rather than a fixed date in start_date and end_date?

    Reply
    • Sure, you can create a sheet containing a dynamic date in yyyy-mm-dd format, e.g. =text(today()-1,"yyyy-mm-dd").
      Then you can reference that cell in your request like &start_date=+++Sheet1!A1+++. Please check this article for more info, the section on dynamic dates has an example of how it works.

      Reply
      • Thank you! That works like a charm!

        One thing I don’t quite understand though – the order in which the results appear changes every time I run the API. One time it will be request_id – page_info – campaign_id – time_day – spend – campaign_name and the next it will start with spend or with the time, even when the API hasn’t changed at all. I don’t understand why it does that or how I can extract meaningful data from that without manually looking up what is to be found in which column each day. Any ideas?

      • Hey Arian, some APIs change the order in which they send back data. To address, please click Edit Fields before running your report. That will open the visual field editor where you can select fields and “lock” them in place, regardless of how the API sends back data.

    • I believe there’s a one year limit as their documentation says “A query timespan must be set with the start_date and end_date request fields. Timespan for reports cannot exceed 365 days.” I’m not sure why you’re only getting 30 days, could it be related to pagination? By default they only return 10 rows unless you set a page_size=1000 parameter. Do you get an error when you request more than 30 days data, or you just don’t get as much data as you expect?

      Reply

Leave a Comment

Table of Contents