Developer resources

Get available locations by different settings — TikTok Business API

Get available locations by different settings · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

Open in the API index TikTok Business platform page

Get available locations by different settings

GET/tool/region/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/tool/region/

Description

Use this endpoint to get codes of locations that your ads can be delivered to based on your objectives, placements, and optionally targeting operating systems, and brand safety settings.

If you want to get available locations that your ads can be delivered to based on your advertiser IDs, use the /search/region/ endpoint.

> Note

Targeting the newly available countries or regions (Azerbaijan, Bulgaria, Bolivia, Cyprus, Algeria, Estonia, Croatia, Kenya, Sri Lanka, Lithuania, Latvia, Nigeria, Puerto Rico, Paraguay, Serbia, Slovenia, Slovakia) using the advertising objective TRAFFIC, LEAD_GENERATION, APP_PROMOTION, or WEB_CONVERSIONS and the TikTok placement are currently separate allowlist-only features. If you would like to access them, contact your TikTok representative. You need to apply for a separate allowlist for each newly available country or region.
Targeting the newly available countries or regions (Azerbaijan, Bulgaria, Bolivia, Cyprus, Algeria, Estonia, Croatia, Kenya, Sri Lanka, Lithuania, Latvia, Puerto Rico, Paraguay, Serbia, Slovenia, Slovakia) using the advertising objective REACH, VIDEO_VIEWS, or ENGAGEMENT and the TikTik placement are currently separate allowlist-only features. If you would like to access them, contact your TikTok representative. You need to apply for a separate allowlist for each newly available country or region.
When you target these countries or regions using the advertising objective REACH, VIDEO_VIEWS, or ENGAGEMENT, pre-bid third-party Brand Safety solutions are not supported. Therefore, you cannot set brand_safety_type to THIRD_PARTY.

The level of locations is shown in the diagram below. Province, DMA(Designated Market Area), and Metropolitan are at the same level. Province, City, and District are administrative areas, so area_type for them is ADMIN. For DMA and Metropolitan, area_type is METROPOLITAN_OR_DMA.

Request

Endpoint

GET https://partner.quantri360.com/v1/tiktok_business/tool/region/

Authentication & shop

Name	In	Type	Sample	Description
Authorization	header	header	Bearer q360_live_ab12cd34_…	Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_id	query	string	7000000000000000001	Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Request parameters

Name	In	Type	Required	Description
placements	query	string[]	Yes	The apps where you want to deliver your ads. For enum values, see Enumeration - Placement
objective_type	query	string	Yes	Your objective type. For enum values and descriptions, see Objectives.
search_campaign_enabled	query	boolean	No	Whether to create a Search Ads Campaign. With Search Ads Campaigns, you set up your campaign to target ads in TikTok search results. Search Ads Campaigns reach those in your audience actively looking for products or information related to your brand. You'll use relevant keywords and search terms to help guide audiences to your ads. Supported values: `true`, `false`. Default value: `false`. To learn more about how to create Search Ads Campaigns, see Create Upgraded Smart+ Search Ads Campaigns.
app_promotion_type	query	string	No	Required when `objective_type` is `APP_PROMOTION`. App promotion type. Enum value: - `APP_INSTALL`: App install. Get new users to install your app. - `APP_RETARGETING`: App retargeting. Re-engage existing app users to take action in your app. - `APP_PREREGISTRATION`: App pre-registration. Get new users to pre-register before your app launches. To learn about how to create Manual App Pre-registration ads, refer to here. - `MINIS`: TikTok Minis or Series. Promote your Series, mini series, or mini game by optimizing for organic and ads traffic. - To learn more about the campaign type where this setting is supported, see Create an Upgraded Smart+ Upgraded Smart+ TikTok Growth Max: Mini Dramas campaign and Create an Upgraded Smart+ TikTok Growth Max: Drama Series campaign.
level_range	query	string	No	Location level you want to get. Enum values: - `ALL`: all levels - `TO_COUNTRY`: only country or region level - `TO_PROVINCE`: country and province level; DMA and Metropolitan are at province level. - `TO_CITY`: country, province, and city levels - `TO_DISTRICT`: country, province, city, and district levels.
language	query	string	No	The language of the returned location name (`name`). Default value: `en` (English). To find out the allowed values, see List of values for `language`. Note: - If the specified language is not supported, it will be ignored and the default value `en` will be used. - If a supported non-English language is specified, the names of locations outside the native country or region associated with that language might not be translated. For example, if you set `language` to `ja` (Japanese), the names of locations outside Japan might not be translated.
shopping_ads_type	query	string	No	Valid only when `objective_type` is `PRODUCT_SALES`. Shopping ads type. Enum values: - `VIDEO`: Video Shopping Ads. - `LIVE`: Live Shopping Ads. - `PRODUCT_SHOPPING_ADS`: Product Shopping Ads. To find out the introduction to different Shopping Ads types and the steps of creating Video Shopping Ads, Live Shopping Ads, and Product Shopping Ads, see Create Shopping Ads.
promotion_type	query	string	No	Promotion type (Optimization location). For enum values, see Enumeration - Promotion Type.
promotion_target_type	query	string	No	Valid when `objective_type` is `LEAD_GENERATION`. The promotion type for Lead Generation objective. Enum values: - `INSTANT_PAGE`：Instant Form. To create a fast-loading in-app TikTok Instant Form to collect more leads. - `EXTERNAL_WEBSITE`：Website Form. To use a landing page that has the Website Form or the TikTok Instant Page that redirects to the website with the Website Form to collect more leads.
operating_system	query	string	No	Operating systems that you want to target. Enum values: `ANDROID`, `IOS`.
brand_safety_type	query	string	No	Brand safety type. Valid only when `placements` is set as `PLACEMENT_TIKTOK`. Default value: `NO_BRAND_SAFETY`. Enum values: - `NO_BRAND_SAFETY`: To not use any brand safety solution. Full inventory, which means your ads may appear next to some content featuring mature themes. - `EXPANDED_INVENTORY`: Use TikTok's brand safety solution. Expanded inventory means that your ads will appear next to content where most inappropriate content has been removed, and that does not contain mature themes. In the next API version, `EXPANDED_INVENTORY` will replace `NO_BRAND_SAFETY` and will be the default brand safety option. - `STANDARD_INVENTORY`: Use TikTok's brand safety solution. Standard inventory means that ads will appear next to content that is appropriate for most brands. - `LIMITED_INVENTORY`: Use TikTok's brand safety solution. Limited inventory means that your ads will not appear next to content that contains mature themes. - `THIRD_PARTY`: Use a third-party brand safety solution. You also need to pass in a value to the `brand_safety_partner` field. Note: - Pre-bid first-party Brand Safety solutions for `APP_PROMOTION`, `WEB_CONVERSIONS`, `TRAFFIC`, `LEAD_GENERATION` objectives in Auction ads, and pre-bid third-party brand safety solutions are currently allowlist-only features. If you would like to access them, please contact your TikTok representative. - See Brand safety to learn about the supported advertising objectives for pre-bid Brand Safety filtering.
brand_safety_partner	query	string	No	Brand safety partner. Required when `brand_safety_type` is `THIRD_PARTY`, and `placements` needs to be set as `PLACEMENT_TIKTOK`. Enum values: `IAS`, `OPEN_SLATE`(The partner is named DoubleVerify on TikTok Ads Manager because the partner has been acquired by DoubleVerify). Note: - Pre-bid third-party brand safety solutions are currently allowlist-only features. If you would like to access them, please contact your TikTok representative.
rf_campaign_type	query	string	No	When `objective_type` is specified as `RF_REACH`, use this field to set the campaign as a TikTok Pulse campaign, then you can get available premium contextual tags. Enum values: `STANDARD` (Reach & Frequency campaign), `PULSE` (TikTok Pulse campaign). If you set this field as `PULSE`, only one location ID (`location_id`) will be returned. Note: - Do not pass in this field when `objective_type` is not specified as `RF_REACH`. - You need to pass the `location_id` value returned in this endpoint to `location_ids` when you use /adgroup/rf/create/ to create a TikTok Pulse ad group.

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/tool/region/?placements=%5B%5D&objective_type=" \
  -H "Authorization: Bearer $KEY"

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/tiktok_business/tool/region/",
    params={
        "placements": [],
        "objective_type": ""
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())

Node.js

const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/tool/region/');
for (const [k, v] of Object.entries({"placements":[],"objective_type":""})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
console.log(r.status, await r.json());

PHP

<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/tool/region/' . '?' . http_build_query(['placements' => '[]', 'objective_type' => '']);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Business)

Name	Type	Description
code	number	The response code. For the complete list of response codes and descriptions, see Appendix - Return Codes.
message	string	The response message. For details, see Appendix - Return Codes.
data	object	Returned data.
region_list	string[]	List of country or region codes
region_info	object[]	Information about the available locations
location_id	string	Location ID
name	string	Location name
parent_id	string	ID of the parent location. Returns 0 if no parents
region_code	string	Country or region code. For example, "DE".
next_level_ids	string[]	List of children locations.
area_type	string	Location type. Enum values: `ADMIN`, `METROPOLITAN_OR_DMA`.
level	string	Location level. Enum values: `COUNTRY`(country or region level), `PROVINCE`, `CITY`(city or county level), `DISTRICT`(district or city level). DMA and metropolitans are at the province level.
support_below_18	boolean	Whether the location supports ads to be delivered to people under 18 years of age.
request_id	string	The log ID of a request, which uniquely identifies the request.

Response sample

{
    "code": 0,
    "message": "OK",
    "request_id": "2022070115265201024524610404180ECA",
    "data": {
        "region_info": [
            {
                "next_level_ids": [],
                "area_type": "ADMIN",
                "level": "COUNTRY",
                "region_code": "PE",
                "location_id": "3932488",
                "name": "Peru",
                "parent_id": "0",
                "support_below_18": true
            },
            {
                "next_level_ids": [
                    "662",
                    "525",
                    "532",
                    ...
                ],
                "area_type": "ADMIN",
                "level": "COUNTRY",
                "region_code": "US",
                "location_id": "6252001",
                "name": "United States",
                "parent_id": "0",
                "support_below_18": true
            },
            ...
        ],
        "region_list": [
            "PE",
            "US",
            "CL",
            "MX",
            "BY",
            "VN",
            ...
        ]
    }
}

Get started

Sign up for Partner
Enable a data type of the Ads (Marketing API) group on the platform page
Create an API key (tick the TikTok Business channel)
Call it as in the examples above