Tools¶

Two lookup endpoints turn the numeric ids that appear in ad group objects into human-readable values: location_ids → countries, and app_id → the game and its store package. Both return small, stable lists; call them once per run and cache the result.

Get regions¶

GET /open_api/v1.3/tool/region/get/

Returns the targetable regions. In these accounts all regions are countries (level = COUNTRY). The location_id values are what ad groups carry in location_ids; region_code is the ISO code used by the country_code dimension in Reporting.

Parameters¶

Name	Type	Required	Description
—			No parameters; the list is the same for every advertiser.

Request¶

curl -s "https://business-api.huydata.com/open_api/v1.3/tool/region/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN"

Response¶

{
  "code": 0,
  "message": "OK",
  "request_id": "09e61a5ac8d4408d8856",
  "data": {
    "region_info": [
      {"location_id": "6252001", "name": "United States", "region_code": "US", "level": "COUNTRY", "parent_id": "0", "support_below_18": false},
      {"location_id": "2635167", "name": "United Kingdom", "region_code": "GB", "level": "COUNTRY", "parent_id": "0", "support_below_18": false},
      {"location_id": "6251999", "name": "Canada", "region_code": "CA", "level": "COUNTRY", "parent_id": "0", "support_below_18": false},
      ...
    ]
  }
}

Field	Type	Description
`location_id`	string	Numeric TikTok region id. Matches `location_ids` in ad group objects.
`name`	string	English name.
`region_code`	string	ISO 3166-1 alpha-2 code. Matches `country_code` in Reporting.
`level`	string	`COUNTRY`.
`parent_id`	string	`"0"` (no parent).
`support_below_18`	boolean	`false`.

Note that the payload key is region_info, not list, and there is no page_info.

The 14 regions Nova Play targets:

`location_id`	`region_code`	`name`	Geo group
6252001	US	United States	T1
2635167	GB	United Kingdom	T1
6251999	CA	Canada	T1
2077456	AU	Australia	T1
2921044	DE	Germany	T1
1562822	VN	Vietnam	SEA
1643084	ID	Indonesia	SEA
1694008	PH	Philippines	SEA
1605651	TH	Thailand	SEA
3469034	BR	Brazil	LATAM
3996063	MX	Mexico	LATAM
1861060	JP	Japan	EA
1835841	KR	South Korea	EA
1668284	TW	Taiwan	EA

The geo group is the GEO segment of the campaign naming convention. Always resolve ids through the endpoint rather than hard-coding this table.

Get app list¶

GET /open_api/v1.3/app/list/

Returns the mobile apps registered in an advertiser account. Because Nova Play has one account per game, each account has exactly one app. Use it to map the numeric app_id found in ad groups to the store package (package_name) of the game.

Parameters¶

Name	Type	Required	Description
`advertiser_id`	string	Yes	Advertiser account id.

Request¶

curl -s -G "https://business-api.huydata.com/open_api/v1.3/app/list/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode "advertiser_id=7643153585721644371"

Response¶

{
  "code": 0,
  "message": "OK",
  "request_id": "1f4edfa9efc64324957a",
  "data": {
    "apps": [
      {
        "app_id": "7642218708447580001",
        "app_name": "Dragon Merge Saga",
        "package_name": "com.novaplay.dragonmerge",
        "platform": "ANDROID",
        "download_url": "https://play.google.com/store/apps/details?id=com.novaplay.dragonmerge",
        "partner": "AppsFlyer",
        "create_time": "2026-01-05 00:00:00"
      }
    ]
  }
}

An iOS account:

{
  "code": 0,
  "message": "OK",
  "request_id": "c9716c471cc14fd3b528",
  "data": {
    "apps": [
      {
        "app_id": "7331171115470878399",
        "app_name": "Puzzle Blast Mania",
        "package_name": "id1600000011",
        "platform": "IOS",
        "download_url": "https://apps.apple.com/app/id1600000011",
        "partner": "AppsFlyer",
        "create_time": "2026-01-05 00:00:00"
      }
    ]
  }
}

Field	Type	Description
`app_id`	string	Numeric TikTok app id. Matches `app_id` in ad group objects. It is not the store identifier.
`app_name`	string	Game name.
`package_name`	string	Store identifier: Android package name (`com.novaplay.*`) or iOS App Store id (`id16000000xx`).
`platform`	string	`ANDROID` or `IOS`.
`download_url`	string	Store URL.
`partner`	string	Measurement partner that reports installs to TikTok.
`create_time`	string	`YYYY-MM-DD HH:MM:SS` UTC.

The payload key is apps, with no page_info. The usual advertiser_id errors apply (40001 when missing, 40002 when not authorized).