Skip to content

Commit 4fd661b

Browse files
denisneufdenisneuf
authored
Merge pull request #236 from GJim/feat/add-api-sb-themes-v3
Add api sb themes v3
2 parents 7b7fbc7 + e79dcbc commit 4fd661b

File tree

4 files changed

+189
-1
lines changed

4 files changed

+189
-1
lines changed

‎ad_api/api/sb/__init__.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
from .reports import Reports
2222
from .snapshots import Snapshots
2323
from .benchmarks import Benchmarks
24+
from .themes import Themes
2425

2526
__all__ = [
2627
"Brands",
@@ -45,5 +46,6 @@
4546
"Media",
4647
"Reports",
4748
"Snapshots",
48-
"Benchmarks"
49+
"Benchmarks",
50+
"Themes"
4951
]

‎ad_api/api/sb/themes.py‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
2+
3+
4+
class Themes(Client):
5+
"""
6+
Amazon Ads API - Sponsored Brands - Theme Targeting
7+
8+
Theme targeting automatically targets keywords related to your brand or landing pages.
9+
"""
10+
11+
@sp_endpoint('/sb/themes/list', method='POST')
12+
def list_themes(self, **kwargs) -> ApiResponse:
13+
r"""
14+
Gets a list of theme targets associated with the client identifier, filtered by specified criteria.
15+
16+
Request Body
17+
| '**nextToken**': *string*, {'description': 'Token for pagination. Operations that return paginated results include a pagination token in this field.'}
18+
| '**maxResults**': *number*, {'description': 'Maximum number of results to return. Defaults to API maximum.'}
19+
| '**campaignIdFilter**': *object*, {'description': 'List of campaign identifiers to filter by (max 100).'}
20+
| '**adGroupIdFilter**': *object*, {'description': 'List of ad group identifiers to filter by (max 100).'}
21+
| '**themeIdFilter**': *object*, {'description': 'List of theme target identifiers to filter by (max 100).'}
22+
| '**stateFilter**': *object*, {'description': 'List of theme target states to filter by. Valid values: enabled, paused, archived. Default: enabled, paused.'}
23+
| '**themeTypeFilter**': *object*, {'description': 'List of theme types to filter by. Valid values: KEYWORDS_RELATED_TO_YOUR_BRAND, KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES.'}
24+
25+
Returns:
26+
| ApiResponse
27+
"""
28+
headers = {'Accept': 'application/vnd.sbthemeslistresponse.v3+json'}
29+
body = Utils.convert_body(kwargs.pop('body'), wrap=False)
30+
return self._request(kwargs.pop('path'), data=body, params=kwargs, headers=headers)
31+
32+
@sp_endpoint('/sb/themes', method='POST')
33+
def create_themes(self, **kwargs) -> ApiResponse:
34+
r"""
35+
Create one or more theme targets.
36+
37+
Note that theme targets can be created on multi-adGroup campaigns where campaign serving status is not archived, terminated, rejected, or ended.
38+
Note that ad group state must not be archived.
39+
Note that only one target can be created for each themeType per adGroup.
40+
Note that this operation supports a maximum list size of 100 theme targets.
41+
42+
Request Body
43+
| '**themes**': *array*, {'description': 'List of theme targets to create (max 100).'}
44+
| '**adGroupId**': *string*, {'description': 'The identifier of the ad group'}
45+
| '**campaignId**': *string*, {'description': 'The identifier of the campaign'}
46+
| '**themeType**': *string*, {'description': 'Theme type', 'Enum': 'KEYWORDS_RELATED_TO_YOUR_BRAND, KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES'}
47+
| '**bid**': *number*, {'description': 'The bid amount'}
48+
49+
Returns:
50+
| ApiResponse
51+
"""
52+
headers = {'Accept': 'application/vnd.sbthemescreateresponse.v3+json'}
53+
body = Utils.convert_body(kwargs.pop('body'), wrap=False)
54+
return self._request(kwargs.pop('path'), data=body, params=kwargs, headers=headers)
55+
56+
@sp_endpoint('/sb/themes', method='PUT')
57+
def update_themes(self, **kwargs) -> ApiResponse:
58+
r"""
59+
Updates one or more theme targets.
60+
61+
Note that theme targets can be updated on multi-adGroup campaigns where campaign serving status is not archived, terminated, rejected, or ended.
62+
Note that ad group state must not be archived.
63+
Note that this operation supports a maximum list size of 100 theme targets.
64+
Note that bid is only mutable when the corresponding campaign does not have any enabled optimization rule.
65+
66+
Request Body
67+
| '**themes**': *array*, {'description': 'List of theme targets to update (max 100).'}
68+
| '**themeId**': *string*, {'description': 'The identifier of the theme target'}
69+
| '**adGroupId**': *string*, {'description': 'The identifier of the ad group'}
70+
| '**campaignId**': *string*, {'description': 'The identifier of the campaign'}
71+
| '**state**': *string*, {'description': 'Theme target state', 'Enum': 'enabled, paused, archived'}
72+
| '**bid**': *number*, {'description': 'The bid amount'}
73+
74+
Returns:
75+
| ApiResponse
76+
"""
77+
headers = {'Accept': 'application/vnd.sbthemesupdateresponse.v3+json'}
78+
body = Utils.convert_body(kwargs.pop('body'), wrap=False)
79+
return self._request(kwargs.pop('path'), data=body, params=kwargs, headers=headers)

‎docs/sb/themes.rst‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
Themes
2+
======
3+
4+
.. autoclass:: ad_api.api.sb.Themes
5+
6+
.. autofunction:: ad_api.api.sb.Themes.list_themes
7+
8+
### Example Python
9+
10+
.. code-block:: python
11+
12+
from ad_api.api.sb.themes import Themes
13+
14+
result = Themes().list_themes()
15+
print(result)
16+
17+
.. autofunction:: ad_api.api.sb.Themes.create_themes
18+
19+
### Example Python
20+
21+
.. code-block:: python
22+
23+
from ad_api.api.sb.themes import Themes
24+
import json
25+
26+
# Example data for themes
27+
themes_to_create = [
28+
{
29+
"adGroupId": "YOUR_ADGROUP_ID",
30+
"campaignId": "YOUR_CAMPAIGN_ID",
31+
"themeType": "KEYWORDS_RELATED_TO_YOUR_BRAND",
32+
"bid": 0.75
33+
}
34+
# Add more theme objects as needed, up to 100
35+
]
36+
37+
# For a real scenario, you might read this from a file like in your Keywords example
38+
# file = open("create_themes.json")
39+
# data = file.read()
40+
# file.close()
41+
# result = Themes().create_themes(body=data)
42+
43+
result = Themes().create_themes(themes=themes_to_create)
44+
print(result)
45+
46+
### Example JSON (for request body)
47+
48+
.. code-block:: json
49+
50+
{
51+
"themes": [
52+
{
53+
"adGroupId": "string",
54+
"campaignId": "string",
55+
"themeType": "KEYWORDS_RELATED_TO_YOUR_BRAND|KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES",
56+
"bid": 0.75
57+
}
58+
]
59+
}
60+
61+
62+
.. autofunction:: ad_api.api.sb.Themes.update_themes
63+
64+
### Example Python
65+
66+
.. code-block:: python
67+
68+
from ad_api.api.sb.themes import Themes
69+
import json
70+
71+
# Example data for themes to update
72+
themes_to_update = [
73+
{
74+
"themeId": "YOUR_THEME_ID",
75+
"adGroupId": "YOUR_ADGROUP_ID",
76+
"campaignId": "YOUR_CAMPAIGN_ID",
77+
"state": "paused", # or "enabled", "archived"
78+
"bid": 0.80 # Optional, if updating bid
79+
}
80+
# Add more theme objects as needed, up to 100
81+
]
82+
83+
# For a real scenario, you might read this from a file
84+
# file = open("update_themes.json")
85+
# data = file.read()
86+
# file.close()
87+
# result = Themes().update_themes(body=data)
88+
89+
result = Themes().update_themes(themes=themes_to_update)
90+
print(result)
91+
92+
### Example JSON (for request body)
93+
94+
.. code-block:: json
95+
96+
{
97+
"themes": [
98+
{
99+
"themeId": "string",
100+
"adGroupId": "string",
101+
"campaignId": "string",
102+
"state": "enabled|paused|archived",
103+
"bid": 0.80
104+
}
105+
]
106+
}

‎docs/sb_v3.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,5 @@
1919
sb/moderation
2020
sb/reports
2121
sb/snapshots
22+
sb/themes
2223

0 commit comments

Comments
 (0)