| Name | TikTok-Business-API JSON |
| Version |
1.8
JSON |
| download |
| home_page | https://github.com/Sharashchandra/TikTok-Business-API |
| Summary | Minimal api wrapper for the TikTok Business API |
| upload_time | 2024-07-17 14:42:59 |
| maintainer | None |
| docs_url | None |
| author | Sharashchandra Desai |
| requires_python | >=3.11 |
| license | MIT License Copyright (c) 2022 Sharashchandra Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
tiktok
business
api
wrapper
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TikTok Business API Wrapper
This is a minimal api wrapper to interface with the Tiktok business API
# Installation
``` console
pip install TikTok-Business-API
```
The current version of this package only covers the Tiktok Business API. Tiktok Developer API support will be added in a later version.
# Getting Started
To get started, get an Access Token from the app detail page in the [TikTok for Business Developers page](https://ads.tiktok.com/marketing_api/apps/).
You can also use the access token from the sandbox account to make test calls to the sandbox account.
# Authorization
Obtaining an access_token is simple. Visit the authorization url mentioned in the app detail page. Once you login and grant authorization, it will redirect you to the callback url mentioned while creating the app. The auth_code can be gotten from url after the callback.
By default, the access token will be written to `~/.tiktok/access_token.json`
``` python
from tiktok.business.oauth2 import OAuth2
access_token = OAuth2.get_access_token(
app_id='YOUR_APP_ID',
secret='YOUR_APP_SECRET',
auth_code='AUTH_CODE FROM CALLBACK',
write_to_file=True,
file_path="access_token.json"
)
```
# Initializing a client
This api wrapper makes it easy to switch between the main app and the sandbox account. This client will automatically include the advertiser id to every request if not specified otherwise.The Access Token is included in the header for all the api calls made.
You can initialize a new `Client` by making use of the `access_token.json` file generated in the previous step. The access tokens will be loaded in from `~/.tiktok/access_token.json` if path is not mentioned. Advertiser Id can also added to the `access_token.json`.
``` python
from tiktok.business.client import TikTokBusinessClient
client = TikTokBusinessClient.from_json_file(
json_file_path="/path/to/file",
sandbox=True
)
```
You can initialize a new `Client` with just the Access Token and Advertiser Id to get started.
``` python
from tiktok.business.client import TikTokBusinessClient
client = TikTokBusinessClient(
access_token='YOUR_ACCESS_TOKEN',
advertiser_id='AD_ADVERTISER_ID'
)
```
You can also create a new `Client` for the sandbox account in the same way
``` python
from tiktok.business.client import TikTokBusinessClient
client = TikTokBusinessClient(
access_token='SANDBOX_ACCESS_TOKEN',
advertiser_id='SANDBOX_ADVERTISER_ID',
sandbox=True
)
```
The actual function calls remain the same with the only difference being in the url. URLs:
* SANDBOX_URL = https://sandbox-ads.tiktok.com/open_api
* BUSINESS_URL = https://business-api.tiktok.com/open_api
# Endpoints
All the functionality of the modules can be accessed as attributes of the client object. The functions for each module differs and follows the [TikTok Business API Documentation](https://ads.tiktok.com/marketing_api/docs)
Follow the steps outlined here to [create a client object](#Initializing-a-client)
All of the GET/LIST functions take the same parameters `params` and all the POST methods take `data` as mentioned in the official documentation unless specified.
The client object keeps a track of the advertiser id and passes it along with each request. There is no need to explicitly pass it in the params.
## Campaign
``` python
# Get campaigns (page_size set to 1000 by default)
client.campaign.get_campaigns(params)
# Create campaign
client.campaign.create_campaigns(data)
# Update campaign
client.campaign.update_campaign(data)
# Enable campaigns (max allowed 100 campaign ids in a single request)
client.campaign.enable_campaigns(campaigns_ids: List[str])
# Disable campaigns (max allowed 100 campaign ids in a single request)
client.campaign.disable_campaigns(campaigns_ids: List[str])
# Delete campaigns (max allowed 100 campaign ids in a single request)
client.campaign.delete_campaigns(campaigns_ids: List[str])
```
## Ad Group
``` python
# Get ad groups (page_size set to 1000 by default)
client.ad_group.get_ad_groups(params)
# Create ad group
client.ad_group.create_ad_group(data)
# Update ad group
client.ad_group.update_ad_group(data)
# Update ad group budget
client.ad_group.update_ad_group_budget(data)
# Enable ad groups (max allowed 100 adgroup_ids in a single request)
client.ad_group.enable_adgroups(adgroups_ids: List[str])
# Disable adgroups (max allowed 100 adgroup_ids in a single request)
client.ad_group.disable_adgroups(adgroups_ids: List[str])
# Delete adgroups (max allowed 100 adgroup_ids in a single request)
client.ad_group.delete_adgroups(adgroups_ids: List[str])
```
## Ad
``` python
# Get ads (page_size set to 1000 by default)
client.ad.get_ads(params)
# Create ad
client.ad.create_ad(data)
# Update ad
client.ad.update_ad(data)
# Enable ads (max allowed 100 ad_ids in a single request)
client.ad.enable_ads(ads_ids: List[str])
# Disable ads (max allowed 100 ad_ids in a single request)
client.ad.disable_ads(ads_ids: List[str])
# Delete ads (max allowed 100 ad_ids in a single request)
client.ad.delete_ads(ads_ids: List[str])
```
## Creative
### Image
``` python
# Upload image file
client.creative.image.upload_file(file_path: str, file_name: Optional[str])
# Upload file by url
client.creative.image.upload_file_by_url(url: str, file_name: Optional[str])
# Upload file by file id
client.creative.image.upload_file_by_file_id(file_id: str, file_name: Optional[str])
```
### Video
``` python
# Upload video file
client.creative.video.upload_file(file_path: str, file_name: Optional[str])
# Upload file by url
client.creative.video.upload_file_by_url(url: str, file_name: Optional[str])
# Upload file by file id
client.creative.video.upload_file_by_file_id(file_id: str, file_name: Optional[str])
```
### Music
``` python
# Upload music file
client.creative.music.upload_file(file_path: str, file_name: Optional[str])
# Upload file by url
client.creative.music.upload_file_by_url(url: str, file_name: Optional[str])
# Upload file by file id
client.creative.music.upload_file_by_file_id(file_id: str, file_name: Optional[str])
```
## Audience
``` python
# Get all audiences (page_size set to 1000 by default)
client.audience.get_all_audiences(params)
# Get audience details (max allowed 100 custom_audience_ids in a single request)
client.audience.get_audience_details(custom_audience_ids: List[str])
# Upload audience (each file needs to be less 50 mb. will add functionality to handle bigger file sizes in future release)
client.audience.upload_audience(file_path: str, calculate_type: str)
# Create custom audience by tiktok file paths
client.audience.create_audience_by_file(data)
# Create custom audience by rules
client.audience.create_audience_by_rule(data)
# Create lookalike audience by file_ids
client.audience.create_lookalike_audience(data)
# Update custom audience
client.audience.update_audience(data)
# Delete custom audience (max allowed 100 custom_audience_ids in a single request)
client.audience.delete_audience(custom_audience_ids: List[str])
# Share custom audience with advertiser accounts
client.audience.share_audience(data)
# Cancel audience sharing (currently an allowlist-only feature)
client.audience.cancel_audience_sharing(data)
# Get audience share log (currently an allowlist-only feature)
client.audience.get_audience_sharing_log(custom_audience_id: str)
```
## Reports
``` python
# Get synchronous report (page_size set to 1000 by default)
client.reports.get_synchronous_report(params)
# Create asynchronous report task (page_size set to 1000 by default) (currently an allowlist-only feature)
client.reports.create_asynchronous_report_task(data)
# Check asynchronous report task
client.reports.check_asynchronous_report_task(task_id: str)
# Download asynchronous report
client.reports.download_asynchronous_report(task_id: str, file_path: str)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Sharashchandra/TikTok-Business-API",
"name": "TikTok-Business-API",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "tiktok, business, api, wrapper",
"author": "Sharashchandra Desai",
"author_email": "Sharashchandra Desai <sharashchandra.desai@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f7/16/2d6aa715baa4dce3c13ffadd64aa9571e2f76c281040ef012638d746cb7b/tiktok_business_api-1.8.tar.gz",
"platform": null,
"description": "# TikTok Business API Wrapper\n\nThis is a minimal api wrapper to interface with the Tiktok business API\n\n# Installation\n\n``` console\npip install TikTok-Business-API\n```\n\nThe current version of this package only covers the Tiktok Business API. Tiktok Developer API support will be added in a later version.\n\n# Getting Started\n\nTo get started, get an Access Token from the app detail page in the [TikTok for Business Developers page](https://ads.tiktok.com/marketing_api/apps/).\nYou can also use the access token from the sandbox account to make test calls to the sandbox account.\n\n# Authorization\n\nObtaining an access_token is simple. Visit the authorization url mentioned in the app detail page. Once you login and grant authorization, it will redirect you to the callback url mentioned while creating the app. The auth_code can be gotten from url after the callback.\n\nBy default, the access token will be written to `~/.tiktok/access_token.json`\n\n``` python\nfrom tiktok.business.oauth2 import OAuth2\n\naccess_token = OAuth2.get_access_token(\n app_id='YOUR_APP_ID',\n secret='YOUR_APP_SECRET',\n auth_code='AUTH_CODE FROM CALLBACK',\n write_to_file=True,\n file_path=\"access_token.json\"\n)\n```\n# Initializing a client\n\nThis api wrapper makes it easy to switch between the main app and the sandbox account. This client will automatically include the advertiser id to every request if not specified otherwise.The Access Token is included in the header for all the api calls made.\n\nYou can initialize a new `Client` by making use of the `access_token.json` file generated in the previous step. The access tokens will be loaded in from `~/.tiktok/access_token.json` if path is not mentioned. Advertiser Id can also added to the `access_token.json`.\n\n``` python\nfrom tiktok.business.client import TikTokBusinessClient\n\nclient = TikTokBusinessClient.from_json_file(\n json_file_path=\"/path/to/file\",\n sandbox=True\n)\n```\n\nYou can initialize a new `Client` with just the Access Token and Advertiser Id to get started.\n\n``` python\nfrom tiktok.business.client import TikTokBusinessClient\n\nclient = TikTokBusinessClient(\n access_token='YOUR_ACCESS_TOKEN',\n advertiser_id='AD_ADVERTISER_ID'\n)\n```\n\nYou can also create a new `Client` for the sandbox account in the same way\n\n``` python\nfrom tiktok.business.client import TikTokBusinessClient\n\nclient = TikTokBusinessClient(\n access_token='SANDBOX_ACCESS_TOKEN',\n advertiser_id='SANDBOX_ADVERTISER_ID',\n sandbox=True\n)\n```\n\nThe actual function calls remain the same with the only difference being in the url. URLs:\n\n* SANDBOX_URL = https://sandbox-ads.tiktok.com/open_api\n* BUSINESS_URL = https://business-api.tiktok.com/open_api\n\n# Endpoints\n\nAll the functionality of the modules can be accessed as attributes of the client object. The functions for each module differs and follows the [TikTok Business API Documentation](https://ads.tiktok.com/marketing_api/docs)\n\nFollow the steps outlined here to [create a client object](#Initializing-a-client)\n\nAll of the GET/LIST functions take the same parameters `params` and all the POST methods take `data` as mentioned in the official documentation unless specified.\n\nThe client object keeps a track of the advertiser id and passes it along with each request. There is no need to explicitly pass it in the params.\n\n## Campaign\n``` python\n# Get campaigns (page_size set to 1000 by default)\nclient.campaign.get_campaigns(params)\n\n# Create campaign\nclient.campaign.create_campaigns(data)\n\n# Update campaign\nclient.campaign.update_campaign(data)\n\n# Enable campaigns (max allowed 100 campaign ids in a single request)\nclient.campaign.enable_campaigns(campaigns_ids: List[str])\n\n# Disable campaigns (max allowed 100 campaign ids in a single request)\nclient.campaign.disable_campaigns(campaigns_ids: List[str])\n\n# Delete campaigns (max allowed 100 campaign ids in a single request)\nclient.campaign.delete_campaigns(campaigns_ids: List[str])\n```\n\n## Ad Group\n``` python\n# Get ad groups (page_size set to 1000 by default)\nclient.ad_group.get_ad_groups(params)\n\n# Create ad group\nclient.ad_group.create_ad_group(data)\n\n# Update ad group\nclient.ad_group.update_ad_group(data)\n\n# Update ad group budget\nclient.ad_group.update_ad_group_budget(data)\n\n# Enable ad groups (max allowed 100 adgroup_ids in a single request)\nclient.ad_group.enable_adgroups(adgroups_ids: List[str])\n\n# Disable adgroups (max allowed 100 adgroup_ids in a single request)\nclient.ad_group.disable_adgroups(adgroups_ids: List[str])\n\n# Delete adgroups (max allowed 100 adgroup_ids in a single request)\nclient.ad_group.delete_adgroups(adgroups_ids: List[str])\n```\n\n## Ad\n``` python\n# Get ads (page_size set to 1000 by default)\nclient.ad.get_ads(params)\n\n# Create ad\nclient.ad.create_ad(data)\n\n# Update ad\nclient.ad.update_ad(data)\n\n# Enable ads (max allowed 100 ad_ids in a single request)\nclient.ad.enable_ads(ads_ids: List[str])\n\n# Disable ads (max allowed 100 ad_ids in a single request)\nclient.ad.disable_ads(ads_ids: List[str])\n\n# Delete ads (max allowed 100 ad_ids in a single request)\nclient.ad.delete_ads(ads_ids: List[str])\n```\n\n## Creative\n### Image\n``` python\n# Upload image file\nclient.creative.image.upload_file(file_path: str, file_name: Optional[str])\n\n# Upload file by url\nclient.creative.image.upload_file_by_url(url: str, file_name: Optional[str])\n\n# Upload file by file id\nclient.creative.image.upload_file_by_file_id(file_id: str, file_name: Optional[str])\n```\n\n### Video\n``` python\n# Upload video file\nclient.creative.video.upload_file(file_path: str, file_name: Optional[str])\n\n# Upload file by url\nclient.creative.video.upload_file_by_url(url: str, file_name: Optional[str])\n\n# Upload file by file id\nclient.creative.video.upload_file_by_file_id(file_id: str, file_name: Optional[str])\n```\n\n### Music\n``` python\n# Upload music file\nclient.creative.music.upload_file(file_path: str, file_name: Optional[str])\n\n# Upload file by url\nclient.creative.music.upload_file_by_url(url: str, file_name: Optional[str])\n\n# Upload file by file id\nclient.creative.music.upload_file_by_file_id(file_id: str, file_name: Optional[str])\n```\n\n## Audience\n``` python\n# Get all audiences (page_size set to 1000 by default)\nclient.audience.get_all_audiences(params)\n\n# Get audience details (max allowed 100 custom_audience_ids in a single request)\nclient.audience.get_audience_details(custom_audience_ids: List[str])\n\n# Upload audience (each file needs to be less 50 mb. will add functionality to handle bigger file sizes in future release)\nclient.audience.upload_audience(file_path: str, calculate_type: str)\n\n# Create custom audience by tiktok file paths\nclient.audience.create_audience_by_file(data)\n\n# Create custom audience by rules\nclient.audience.create_audience_by_rule(data)\n\n# Create lookalike audience by file_ids\nclient.audience.create_lookalike_audience(data)\n\n# Update custom audience\nclient.audience.update_audience(data)\n\n# Delete custom audience (max allowed 100 custom_audience_ids in a single request)\nclient.audience.delete_audience(custom_audience_ids: List[str])\n\n# Share custom audience with advertiser accounts\nclient.audience.share_audience(data)\n\n# Cancel audience sharing (currently an allowlist-only feature)\nclient.audience.cancel_audience_sharing(data)\n\n# Get audience share log (currently an allowlist-only feature)\nclient.audience.get_audience_sharing_log(custom_audience_id: str)\n```\n\n## Reports\n``` python\n# Get synchronous report (page_size set to 1000 by default)\nclient.reports.get_synchronous_report(params)\n\n# Create asynchronous report task (page_size set to 1000 by default) (currently an allowlist-only feature)\nclient.reports.create_asynchronous_report_task(data)\n\n# Check asynchronous report task\nclient.reports.check_asynchronous_report_task(task_id: str)\n\n# Download asynchronous report\nclient.reports.download_asynchronous_report(task_id: str, file_path: str)\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022 Sharashchandra Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Minimal api wrapper for the TikTok Business API",
"version": "1.8",
"project_urls": {
"Bug Tracker": "https://github.com/Sharashchandra/TikTok-Business-API/issues",
"Homepage": "https://github.com/Sharashchandra/TikTok-Business-API"
},
"split_keywords": [
"tiktok",
" business",
" api",
" wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "802c7c88360cd09f75594263a31864da38fec628746dd7e616424a32f299ec89",
"md5": "d9bf63b37c081ac77d91d30f7366c6b1",
"sha256": "68af074c72033652953a6204ad37c56a13bb07034afeafe9fd42c0478e573436"
},
"downloads": -1,
"filename": "TikTok_Business_API-1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d9bf63b37c081ac77d91d30f7366c6b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 23239,
"upload_time": "2024-07-17T14:42:57",
"upload_time_iso_8601": "2024-07-17T14:42:57.883146Z",
"url": "https://files.pythonhosted.org/packages/80/2c/7c88360cd09f75594263a31864da38fec628746dd7e616424a32f299ec89/TikTok_Business_API-1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f7162d6aa715baa4dce3c13ffadd64aa9571e2f76c281040ef012638d746cb7b",
"md5": "54a7095481585d6047e3b9abb3aff366",
"sha256": "116270da1cec81f52636d4a3ea6daf60845c0b477886d3c95ea258bbc551c6ec"
},
"downloads": -1,
"filename": "tiktok_business_api-1.8.tar.gz",
"has_sig": false,
"md5_digest": "54a7095481585d6047e3b9abb3aff366",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 11394,
"upload_time": "2024-07-17T14:42:59",
"upload_time_iso_8601": "2024-07-17T14:42:59.581854Z",
"url": "https://files.pythonhosted.org/packages/f7/16/2d6aa715baa4dce3c13ffadd64aa9571e2f76c281040ef012638d746cb7b/tiktok_business_api-1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-17 14:42:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Sharashchandra",
"github_project": "TikTok-Business-API",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "tiktok-business-api"
}
