Estimate audience size
POST/ad/audience_size/estimate/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/
Description
Use this endpoint to get the estimated audience size. The parameters for this endpoint are similar to the ones for creating an ad group.
> Note
Due to data security requirements, an estimated audience size does not include audiences under 18 years of age. Ad delivery as permitted by applicable laws will not be affected.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/
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 | Sample | Description |
|---|---|---|---|---|---|
| placement_type | body | string | No | Placement type.
Enum values:
- PLACEMENT_TYPE_AUTOMATIC (Automatic placement)
- PLACEMENT_TYPE_NORMAL (Select placement). Default value: PLACEMENT_TYPE_NORMAL. | |
| placements | body | string[] | No | The apps where you want to deliver your ads. Required when placement_type is PLACEMENT_TYPE_NORMAL, and ignored when placement_type is PLACEMENT_TYPE_AUTOMATIC.
Currently, we support PLACEMENT_TIKTOK, PLACEMENT_PANGLE and PLACEMENT_GLOBAL_APP_BUNDLE. For a full list of enum values, see Enumeration - Placement.
Note:
- The available locations you can target with the Global App Bundle placement (PLACEMENT_GLOBAL_APP_BUNDLE) are: Brazil, Indonesia, Vietnam, the Philippines, Thailand, Malaysia, Mexico, Saudi Arabia, and Japan.
- The Global App Bundle placement (PLACEMENT_GLOBAL_APP_BUNDLE) does not support the optimization goal Landing Page View (optimization_goal=TRAFFIC_LANDING_PAGE_VIEW). To learn about the optimization goal, refer to the section Enumerations-Optimization goal.
- For Product Sales campaigns (objective_type = PRODUCT_SALES), only TikTok placement (PLACEMENT_TIKTOK) is supported. | |
| pixel_id | body | string | No | Pixel ID. Only application for landing pages. It needs to be passed in with the external_action field. Use /pixel/list/ endpoint to get all Pixel IDs. | |
| ios14_targeting | body | string | No | The iOS devices that you want to target.
Note: When campaign_type of the campaign is set as IOS14_CAMPAIGN, ios14_targeting is required and must be specified as IOS14_PLUS.
Enum values:
- UNSET: The default value for ad groups that were created before the introduction of this field.
- IOS14_MINUS: Devices with iOS 14.4 or earlier versions, which are not affected by the iOS 14 privacy update. This is the default value for ad groups that are created after the introduction of this field.
- IOS14_PLUS: Devices with iOS 14.5 and above. The iOS 14 privacy update has been enforced in this group of devices. Specify this value if you want to create an iOS 14 campaign. Each iOS 14 campaign can have up to 2 active ad groups. If IOS14_PLUS is specified, this field cannot be updated. If IOS14_PLUS is specified for this field, the system will verify if related fields meet the requirements for an iOS 14 campaign. The following fields will be checked.
- app_id: It must not be an ID of an Android app.
- operating_systems: It must not be ANDROID or PC.
- min_ios_version: You must specify a value for this field, and the the value must not contradict with the selection for ios14_targeting.
- min_android_version: Must not be specified.
- optimization_goal: Can only be set to CLICK, INSTALL, IN_APP_EVENT or VALUE.
- shopping_ads_retargeting_type: Must not be specified.
- shopping_ads_retargeting_actions_days: Must not be specified.
- conversion_window: Must not be specified.
- On the Ad level, deeplink_type must not be set to DEFERRED_DEEPLINK. | |
| objective_type | body | string | Yes | Your objective type. For enum values, see Enumeration - Advertising Objective. | |
| optimization_goal | body | string | Yes | Optimization goal. For enum values, see Enumeration - Optimization Goal. | |
| promotion_type | body | string | No | Required when objective_type = PRODUCT_SALES. Promotion type and you can decide where you'd like to promote your products using this field.
For enum values, see Enumeration - Promotion Type. | |
| product_source | body | string | No | Required when objective_type = PRODUCT_SALES. Product source where you want to get products for promotion.
Enum values: UNSET, CATALOG (Catalog), STORE (TikTok Shop). | |
| catalog_id | body | string | No | Required when objective_type=PRODUCT_SALES. Catalog ID. | |
| product_set_id | body | string | No | ProductSet ID of the catalog. 0 means selecting all product sets. The default value is 0. | |
| catalog_authorized_bc_id | body | string | No | For catalogs in Business Center, you must specify the ID of the Business Center that a catalog belongs to. | |
| shopping_ads_retargeting_type | body | string | No | Valid when the campaign objective_type is PRODUCT_SALES. The retargeting type of shopping ads. Enum values:
- LAB1: Retargeting audiences who viewed products or added products to cart but didn't purchase products.
- LAB2: Retargeting audiences who added products to cart but didn't purchase products.
- LAB3: Retargeting audiences using custom combination.
- OFF: No retargeting. | |
| shopping_ads_retargeting_actions_days | body | number | No | Required when shopping_ads_retargeting_type is LAB1 or LAB2.
The valid time range for the specified audience action. Audiences who have completed the specified action within the time range will be retargeted by the shopping ads.
Value range: 1, 2, 3, 7, 14, 30, 60, 90, 180. | |
| included_custom_actions | body | object[] | No | When shopping_ads_retargeting_type is LAB3, you need to pass in either included_custom_actions or excluded_custom_actions.
The custom action that you want to use as "Include" conditions for filtering out the shopping ads audiences to be retargeted. | |
| excluded_custom_actions | body | object[] | No | When shopping_ads_retargeting_type is LAB3, you need to pass in either included_custom_actions or excluded_custom_actions.
The custom action that you want to use as "Exclude" conditions for filtering out the shopping ads audiences to be retargeted. | |
| audience_ids | body | string[] | No | List of audience IDs. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint. | |
| excluded_audience_ids | body | string[] | No | A list of audience ID to be excluded. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint. | |
| audience_rule | body | object | No | Audience rule, valid if objective_type is TRAFFIC or WEB_CONVERSIONS. For details, see Audience Rules | |
| audience_type | body | string | No | App retargeting audience type. For enum values, see Enumeration - App Retargeting Audience Type | |
| location_ids | body | string[] | No | IDs of the locations that you want to target.
You need to set location_ids or zipcode_ids or both.
Max size: 3,000. If you provide both location_ids and zipcode_ids, the combined total of location IDs, zip code IDs, and postal code IDs cannot exceed 3,000 per ad group.
To get the available locations and corresponding IDs based on your placement and objective, use the /tool/region/ or /tool/targeting/search/ endpoint.
For enum values, see Location IDs.
Note:
- Overlapping targeted locations are not supported. For instance, you cannot target the U.S. and the state of California at the same time. | |
| zipcode_ids | body | string[] | No | Zip code IDs or postal code IDs that you want to use to target locations.
You need to set location_ids or zipcode_ids or both.
Max size: 3,000. If you provide both location_ids and zipcode_ids, the combined total of location IDs, zip code IDs, and postal code IDs cannot exceed 3,000 per ad group.
You can get the available zip code IDs or postal code IDs based on your placement, objective and keyword via geo_id (when geo_type = ZIP_CODE) returned from the /tool/targeting/search/ endpoint.
Note:
- Zip code targeting is currently only supported for the US and postal code targeting is currently only supported for Canada, Brazil, Indonesia, Thailand, and Vietnam.
- Targeting postal code areas in Brazil, Indonesia, Thailand, and Vietnam is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
- You can only use zip code targeting or postal code targeting on TikTok placement. Therefore, the placements value needs to include PLACEMENT_TIKTOK.
- Overlapping targeted locations are not supported. For instance, you cannot target the U.S. and the state of California at the same time.
- To get information about zip code IDs or postal code IDs, you can only use /tool/targeting/info/. | |
| isp_ids | body | string[] | No | IDs of the Internet service providers (ISP) that you want to target.
Valid only when you specify a valid location ID at the country or region level via location_ids at the same time.
You can use /tool/targeting/list/ to get the ISP IDs that you can target for a location ID.
Note: When you pass in isp_ids, you cannot set the placement as Global App Bundle only (placements =PLACEMENT_GLOBAL_APP_BUNDLE). | |
| gender | body | string | No | Gender that you want to target. Enum: GENDER_FEMALE,GENDER_MALE,GENDER_UNLIMITED | |
| age_groups | body | string[] | No | Age groups you want to target. For enum values, see Enumeration - Targeting Age Group. | |
| languages | body | string[] | No | Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code. You can get language codes via /tool/language/, and if you don't want to limit the languages you target, assign an empty value to this field or do not pass in this field. | |
| interest_category_ids | body | string[] | No | IDs of general interest categories that you want to use to target audiences. - To search for or list general interest category IDs, use /targeting/search/ (recommended) or /tool/interest_category/. - To get recommended interest category IDs based on your industry, use /tool/targeting_category/recommend/. | |
| interest_keyword_ids | body | string[] | No | IDs of additional interest categories that you want to use to target audience. To search for additional interest categories, use /targeting/search/ (recommended) or /tool/interest_keyword/recommend/. | |
| purchase_intention_keyword_ids | body | string[] | No | IDs of purchase intention categories that you want to use to target audiences with an interest in purchases related to a content category.
To search for or list purchase intention category IDs, use /targeting/search/.
Note:
- Do not pass in purchase_intention_keyword_ids and interest_keyword_ids at the same time. Otherwise, keyword conflict will occur.
- purchase_intention_keyword_ids only supports Auction ads with theobjective_type as APP_PROMOTION,WEB_CONVERSIONS,LEAD_GENERATION, TRAFFIC, or PRODUCT_SALES with product_source as CATALOG, and the placement setting should include TikTok (PLACEMENT_TIKTOK) or Pangle (PLACEMENT_PANGLE). | |
| actions | body | object[] | No | A list of targeting behavioral category objects. | |
| operating_systems | body | string[] | No | Device operating systems that you want to target.
Only one value is allowed.
Enum values: ANDROID, IOS.
This field is required in two scenarios:
- objective_type is APP_PROMOTION
- objective_type is TRAFFIC and promotion_type is APP_IOS or APP_ANDROID | |
| min_ios_version | body | string | No | Minimum iOS version. For enum values, see Enumeration - Minimum iOS Version. | |
| min_android_version | body | string | No | Minimum device Android version. For enum values, see Enumeration - Minimum Android Version. | |
| device_model_ids | body | string[] | No | IDs of the device models that you want to target. Use /tool/device_model/ to get the complete list of device model IDs and their statuses, and only active devices (is_active = True in the response of /tool/device_model/) can be used to create ads.
Note: Device model (device_model_ids) and device price (device_price_ranges) cannot be set at the same time. | |
| network_types | body | string[] | No | Device connection types that you want to target. Default: unlimited. For enum values, see Enumeration - Connection Type. | |
| household_income | body | string[] | No | Household income that you want to target. Enum values: TOP5(Top 5% of ZIP codes), TOP10(Top 10% of ZIP codes), TOP10_25(Top 10% -25% of ZIP codes), TOP25_50(Top 25% - 50% of ZIP codes).
Note:
- It only supports the ad objectives for Auction ads. See Advertising objectives for details.
- It is only applicable to the TikTok Placement in the US.
- If you have specified special_industries at the campaign level, then you cannot use the field here. | |
| spending_power | body | string | No | Spending power that you want to target.
Enum values: ALL, HIGH.
If it is set to HIGH, you can target high spending users who typically spend more on purchases on TikTok ads than average users.
Note: :
- This field does not support the advertising objectives PRODUCT_SALES and RF_REACH at the campaign level. See Advertising objectives for details.
- This field supports Automatic Placement and Select Placement with TikTok included. Therefore, you need to set placement_type to PLACEMENT_TYPE_AUTOMATIC, or include PLACEMENT_TIKTOK in the value of placements. Note that if you specify Pangle as a placement, the spending power targeting won't take effect on Pangle.
- It cannot be used with special industries targeting at the same time. If you have specified special_industries at the campaign level, then you cannot use the field here.
- When auto_targeting_enabled is true at the ad group level, then spending_power will be automatically set to ALL. | |
| device_price_ranges | body | number[] | No | Targeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: The upper limit you set will be added by 50 and the resulting new number will be used as the actual upper limit for device targeting. The actual upper limit is shown in the ad group settings in TikTok Ads Manager. If you set and get the price range of [0, 250], it actually means [0, 300]. | |
| carrier_ids | body | string[] | No | Carriers that you want to target. A carrier is valid only when the in_use field for the carrier is true. The carriers must be consistent with the location(s) that you want to target. Use /tool/carrier/ endpoint to get the enum values. | |
| included_pangle_audience_package_ids | body | string[] | No | IDs of the Pangle audiences that you want to include. Valid only for Pangle placement. You can get audience IDs (package_id) by using the /pangle_audience_package/get/ endpoint. You need to set bind_type to INCLUDE. Do not specify this field and excluded_pangle_audience_package_ids at the same time. | |
| excluded_pangle_audience_package_ids | body | string[] | No | IDs of the Pangle audiences that you want to exclude. Valid only for Pangle placement. You can get audience IDs (package_id) by using the /pangle_audience_package/get/ endpoint. You need to set bind_type to EXCLUDE. Do not specify this field and included_pangle_audience_package_ids at the same time. | |
| blocked_pangle_app_ids | body | string[] | No | Pangle app block list ID. You can get an ID via the app_package_id field returned by Get Pangle block list. It only takes effect when Pangle placement is selected. | |
| targeting_expansion | body | object | No | Settings about targeting expansion | |
| auto_targeting_enabled | body | boolean | No | Whether to enable automated targeting. Enum values: True, False. | |
| contextual_tag_ids | body | string[] | No | Contextual tag IDs. You can use /tool/contextual_tag/get/ to get available contextual tags. See Contextual targeting to learn more about how to use Contextual targeting.
Note:
- This is an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
- Only supports REACH and VIDEO_VIEWS as objectives (objective_type) at the campaign level.
- Not supported when brand_safety_type is set to THIRD_PARTY. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"objective_type":"","optimization_goal":"","included_custom_actions":[{}],"excluded_custom_actions":[{}],"actions":[{}],"targeting_expansion":{}}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/",
params={},
json={
"objective_type": "",
"optimization_goal": "",
"included_custom_actions": [
{}
],
"excluded_custom_actions": [
{}
],
"actions": [
{}
],
"targeting_expansion": {}
},
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/ad/audience_size/estimate/');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({"objective_type":"","optimization_goal":"","included_custom_actions":[{}],"excluded_custom_actions":[{}],"actions":[{}],"targeting_expansion":{}}),
});
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/ad/audience_size/estimate/' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"objective_type":"","optimization_goal":"","included_custom_actions":[{}],"excluded_custom_actions":[{}],"actions":[{}],"targeting_expansion":{}}');
$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 | Sample | Description |
|---|---|---|---|
| code | number | Response code. For the complete list of response codes and descriptions, see Appendix - Return Codes. | |
| message | string | Response message. For details, see Appendix - Return Codes. | |
| data | object | Return data | |
| user_count_stage | number | Evaluation of the estimated audience size. Enum: - `1`: Too Narrow. The estimated audience size is less than 10,000, and accounts for less then 20% of possible audience size in the selected locations on the selected placements. - `2`: Narrow. The estimated audience size is equal to or larger than 10,000, but still accounts for less than 20% of possible audience size in the selected locations on the selected placements. - `3`: Balanced. The estimated audience size accounts for 20% or more but less than 80% of possible audience size in the selected locations on the selected placements. - `4`: Fairly Broad: The estimated audience size accounts for 80% or more of the possible audience size in the selected locations on the selected placements | |
| user_count | object | Estimated audience sizes | |
| lower_end | number | Lower-end of the estimated audience size range | |
| upper_end | number | Upper-end of the estimated audience size range | |
| purchase_intention_keyword_ids | string[] | IDs of purchase intention keywords that you want to use to target audiences with an interest in purchases related to a content category. | |
| request_id | string | The log id of the request, which uniquely identifies a request |
Response sample
HTTPS/1.1 200 OK
{
"message": "OK",
"code": 0,
"data": {
"user_count": {
"lower_end": 107229000,
"upper_end": 131059000
}
},
"request_id": "2021090909090909024510008412345678"
}
(/code);
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