Skip to content

Commit f3b66a1

Browse files
denisneufdenisneuf
committed
Issue enhancement #11 
1 parent 9e21531 commit f3b66a1

File tree

8 files changed

+717
-1
lines changed

8 files changed

+717
-1
lines changed

‎ad_api/api/sd/__init__.py‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,22 @@
11
from .campaigns import Campaigns
22
from .ad_groups import AdGroups
3+
from .product_ads import ProductAds
34
from .reports import Reports
5+
from .snapshots import Snapshots
6+
from .creatives import Creatives
7+
from .product_targeting import Targets
8+
from .negative_product_targeting import NegativeTargets
9+
from .targeting_recommendations import TargetsRecommendations
10+
from .bid_recommendations import BidRecommendations
411

512
__all__ = [
613
"Campaigns",
714
"AdGroups",
8-
"Reports"
15+
"Reports",
16+
"ProductAds",
17+
"Targets",
18+
"NegativeTargets",
19+
"TargetsRecommendations",
20+
"BidRecommendations",
21+
"Creatives"
922
]

‎ad_api/api/sd/bid_recommendations.py‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse
2+
3+
class BidRecommendations(Client):
4+
"""Amazon Advertising API for Sponsored Display
5+
6+
Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#/Bid%20Recommendations
7+
8+
This API enables programmatic access for campaign creation, management, and reporting for Sponsored Display campaigns. For more information on the functionality, see the `Sponsored Display Support Center <https://advertising.amazon.com/help#GTPPHE6RAWC2C4LZ>`_ . For API onboarding information, see the `account setup <https://advertising.amazon.com/API/docs/en-us/setting-up/account-setup>`_ topic.
9+
10+
This specification is available for download from the `Advertising API developer portal <https://d3a0d0y2hgofx6.cloudfront.net/openapi/en-us/sponsored-display/3-0/openapi.yaml>`_.
11+
12+
"""
13+
@sp_endpoint('/sd/targets/bid/recommendations', method='POST')
14+
def list_targets_bid_recommendations(self, **kwargs) -> ApiResponse:
15+
r"""
16+
Provides a list of bid recommendations based on the list of input advertised ASINs and targeting clauses in the same format as the targeting API. For each targeting clause in the request a corresponding bid recommendation will be returned in the response. Currently the API will accept up to 100 targeting clauses.
17+
The recommended bids are derrived from the last 7 days of winning auction bids for the related targeting clause.
18+
19+
body: SDTargetingBidRecommendationsRequestV32 | REQUIRED {'description': 'A list of products to tailor bid recommendations for category and audience based targeting clauses.}'
20+
21+
| '**products**': *SDGoalProduct*, {'description': 'A list of products for which to get targeting recommendations. minItems: 1, maxItems: 10000'}
22+
| '**bidOptimization**': *SDBidOptimizationV32 string*, {'description': 'Determines what the recommended bids will be optimized for. Note that "reach" for bid optimization is not currently supported. This note will be removed when these operations become available.', 'Enum': '[ clicks, conversions, reach ]'}
23+
| '**costType**': *SDCostTypeV31 string*, {'description': 'Determines what performance metric the bid recommendations will be optimized for. Note that "vcpm" for cost type is not currently supported. This note will be removed when these operations become available.', 'Enum': '[ cpc, vcpm ]'}
24+
| '**targetingClauses**': SDTargetingClauseV31
25+
26+
type: object
27+
28+
description: A list of targeting clauses to receive bid recommendations for.
29+
30+
| '**expressionType**': *string*, {'description': 'Tactic T00020 ad groups only allow manual targeting.', 'Enum': '[ manual, auto ]'}
31+
| '**expression**': SDTargetingExpressionV31
32+
33+
type: object
34+
description: The targeting expression to match against.
35+
36+
oneOf->
37+
38+
TargetingPredicate:
39+
40+
type: object
41+
description: A predicate to match against in the Targeting Expression (only applicable to Product targeting - T00020).
42+
43+
* All IDs passed for category and brand-targeting predicates must be valid IDs in the Amazon Advertising browse system.
44+
* Brand, price, and review predicates are optional and may only be specified if category is also specified.
45+
* Review predicates accept numbers between 0 and 5 and are inclusive.
46+
* When using either of the 'between' strings to construct a targeting expression the format of the string is 'double-double' where the first double must be smaller than the second double. Prices are not inclusive.
47+
48+
| '**type**': *string*, {'enum': '[ asinSameAs, asinCategorySameAs, asinBrandSameAs, asinPriceBetween, asinPriceGreaterThan, asinPriceLessThan, asinReviewRatingLessThan, asinReviewRatingGreaterThan, asinReviewRatingBetween, asinIsPrimeShippingEligible, asinAgeRangeSameAs, asinGenreSameAs ]'}
49+
| '**value**': *string*, {'description': 'The value to be targeted. example: B0123456789'}
50+
51+
52+
TargetingPredicateNested:
53+
54+
type: object
55+
description: A behavioral event and list of targeting predicates that represents an Audience to target (only applicable to Audience targeting - T00030).
56+
57+
* For manual ASIN-grain targeting, the value array must contain only, 'exactProduct', 'similarProduct', 'releatedProduct' and 'lookback' TargetingPredicateBase components. The 'lookback' is mandatory and the value should be set to '7', '14', '30', '60', '90', '180' or '365'
58+
* For manual Category-grain targeting, the value array must contain a 'lookback' and 'asinCategorySameAs' TargetingPredicateBase component, which can be further refined with optional brand, price, star-rating and shipping eligibility refinements. The 'lookback' is mandatory and the value should be set to '7', '14', '30', '60', '90', '180' or '365'
59+
* For manual Category-grain targeting, the value array must contain a 'lookback' and 'asinCategorySameAs' TargetingPredicateBase component, which can be further refined with optional brand, price, star-rating and shipping eligibility refinements.
60+
* For Amazon Audiences targeting, the TargetingPredicateNested type should be set to 'audience' and the value array should include one TargetingPredicateBase component with type set to 'audienceSameAs'.
61+
* Future For manual Category-grain targeting, adding a 'negative' TargetingPredicateBase will exclude that TargetingPredicateNested from the overall audience.
62+
63+
| '**type**': *string*, {'enum': '[ views, audience, purchases ]'}
64+
| '**value**': TargetingPredicateBase
65+
66+
type: object
67+
68+
description: A predicate to match against inside the TargetingPredicateNested component (only applicable to Audience targeting - T00030).
69+
70+
* All IDs passed for category and brand-targeting predicates must be valid IDs in the Amazon Advertising browse system.
71+
* Brand, price, and review predicates are optional and may only be specified if category is also specified.
72+
* Review predicates accept numbers between 0 and 5 and are inclusive.
73+
* When using either of the 'between' strings to construct a targeting expression the format of the string is 'double-double' where the first double must be smaller than the second double. Prices are not inclusive.
74+
* The exactProduct, similarProduct, and negative types do not utilize the value field.
75+
* The only type currently applicable to Amazon Audiences targeting is 'audienceSameAs'.
76+
* A 'relatedProduct' TargetingPredicateBase will Target an audience that has purchased a related product in the past 7,14,30,60,90,180, or 365 days.
77+
* **Future** A 'negative' TargetingPredicateBase will exclude that TargetingPredicateNested from the overall audience.
78+
79+
| '**type**': *string*, {'enum': '[ asinCategorySameAs, asinBrandSameAs, asinPriceBetween, asinPriceGreaterThan, asinPriceLessThan, asinReviewRatingLessThan, asinReviewRatingGreaterThan, asinReviewRatingBetween, similarProduct, exactProduct, asinIsPrimeShippingEligible, asinAgeRangeSameAs, asinGenreSameAs, audienceSameAs, lookback ]'}
80+
| '**value**': *string*, {'description': 'The value to be targeted. example: B0123456789'}
81+
82+
Returns:
83+
84+
ApiResponse
85+
86+
"""
87+
contentType = 'application/vnd.sdtargetingrecommendations.v3.2+json'
88+
headers = {'Content-Type': contentType}
89+
return self._request(kwargs.pop('path'), data=kwargs.pop('body'), params=kwargs, headers=headers)

‎ad_api/api/sd/creatives.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse
2+
3+
class Creatives(Client):
4+
5+
@sp_endpoint('/sd/creatives', method='GET')
6+
def list_creatives(self, **kwargs) -> ApiResponse:
7+
return self._request(kwargs.pop('path'), params=kwargs)
8+
9+
@sp_endpoint('/sd/creatives', method='PUT')
10+
def edit_creatives(self, **kwargs) -> ApiResponse:
11+
# print(kwargs.get('body'))
12+
return self._request(kwargs.pop('path'), data=kwargs.pop('body'), params=kwargs)
13+
14+
@sp_endpoint('/sd/creatives', method='POST')
15+
def create_creatives(self, **kwargs) -> ApiResponse:
16+
return self._request(kwargs.pop('path'), data=kwargs.pop('body'), params=kwargs)
17+
18+
@sp_endpoint('/sd/moderation/creatives', method='GET')
19+
def list_moderation_creatives(self, **kwargs) -> ApiResponse:
20+
return self._request(kwargs.pop('path'), params=kwargs)
21+
22+
@sp_endpoint('/sd/creatives/preview', method='POST')
23+
def show_creative_preview(self, **kwargs) -> ApiResponse:
24+
#'not a valid key=value pair (missing equal-sign) in '
25+
return self._request(kwargs.pop('path'), data=kwargs.pop('body'), params=kwargs)

‎ad_api/api/sd/negative_product_targeting.py‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse
2+
3+
class NegativeTargets(Client):
4+
"""Amazon Advertising API for Sponsored Display
5+
6+
Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#/Negative%20targeting
7+
8+
This API enables programmatic access for campaign creation, management, and reporting for Sponsored Display campaigns. For more information on the functionality, see the `Sponsored Display Support Center <https://advertising.amazon.com/help#GTPPHE6RAWC2C4LZ>`_ . For API onboarding information, see the `account setup <https://advertising.amazon.com/API/docs/en-us/setting-up/account-setup>`_ topic.
9+
10+
This specification is available for download from the `Advertising API developer portal <https://d3a0d0y2hgofx6.cloudfront.net/openapi/en-us/sponsored-display/3-0/openapi.yaml>`_.
11+
12+
"""
13+
14+
@sp_endpoint('/sd/negativeTargets', method='GET')
15+
def list_negative_targets(self, **kwargs) -> ApiResponse:
16+
r"""
17+
list_negative_targets(self, \*\*kwargs) -> ApiResponse
18+
19+
Gets a list of negative targeting clauses filtered by specified criteria.
20+
21+
| query **startIndex**:*integer* | Optional. 0-indexed record offset for the result set. Default value : 0
22+
| query **count**:*integer* | Optional. Number of records to include in the paged response. Defaults to max page size.
23+
| query **stateFilter**:*string* | Optional. The returned array is filtered to include only ad groups with state set to one of the values in the specified comma-delimited list. Available values : enabled, paused, archived, enabled, paused, enabled, archived, paused, archived, enabled, paused, archived Default value : enabled, paused, archived.
24+
| query **campaignIdFilter**:*string* | Optional. A comma-delimited list of campaign identifiers.
25+
| query **adGroupIdFilter**:*string* | Optional. Restricts results to keywords associated with ad groups specified by identifier in the comma-delimited list.
26+
| query **targetIdFilter**:*string* | Optional. A comma-delimited list of target identifiers. Missing in official Amazon documentation
27+
28+
Returns:
29+
30+
ApiResponse
31+
32+
"""
33+
return self._request(kwargs.pop('path'), params=kwargs)
34+
35+
@sp_endpoint('/sd/negativeTargets', method='PUT')
36+
def edit_negative_targets(self, **kwargs) -> ApiResponse:
37+
r"""
38+
Updates one or more negative targeting clauses. Negative targeting clauses are identified using their targetId. The mutable field is state. Maximum length of the array is 100 objects.
39+
40+
body: | UpdateNegativeTargetingClause REQUIRED {'description': 'A list of up to 100 negative targeting clauses. Note that the only mutable field is state.}'
41+
42+
| '**state**': *number*, {'description': 'The resource state. [ enabled, paused, archived ]'}
43+
| '**targetId***': *integer($int64)*, {'description': 'The identifier of the TargetId.'}
44+
45+
Returns:
46+
47+
ApiResponse
48+
49+
50+
"""
51+
return self._request(kwargs.pop('path'), data=kwargs.pop('body'), params=kwargs)
52+
53+
54+
@sp_endpoint('/sd/negativeTargets', method='POST')
55+
def create_negative_targets(self, **kwargs) -> ApiResponse:
56+
r"""
57+
create_products_targets(self, \*\*kwargs) -> ApiResponse:
58+
59+
Creates one or more targeting expressions.
60+
61+
body: | REQUIRED {'description': 'An array of asins objects.}'
62+
63+
| '**state**': *number*, {'description': 'The current resource state. [ enabled, paused, archived ]'}
64+
| '**adGroupId**': *number*, {'description': 'The identifier of the ad group to which this negative target is associated.'}
65+
| '**expression**'
66+
| '**type**': *string*, {'description': 'The intent type. See the targeting topic in the Amazon Advertising support center for more information.', 'enum': '[ asinSameAs, asinBrandSameAs ]'}
67+
| '**value**': *string*, {'description': 'The value to be negatively targeted. Used only in manual expressions.'}
68+
| '**expressionType**': *string*, {'description': '[ auto, manual ]'}
69+
70+
Returns:
71+
72+
ApiResponse
73+
74+
75+
"""
76+
return self._request(kwargs.pop('path'), data=kwargs.pop('body'), params=kwargs)
77+
78+
79+
@sp_endpoint('/sd/negativeTargets/{}', method='GET')
80+
def get_negative_target(self, targetId, **kwargs) -> ApiResponse:
81+
r"""
82+
83+
This call returns the minimal set of negative targeting clause fields, but is more efficient than getNegativeTargetsEx.
84+
85+
Get a negative targeting clause specified by identifier.
86+
87+
path **negativeTargetId**:*integer* | Required. The negative targeting clause identifier.
88+
89+
Returns:
90+
91+
ApiResponse
92+
93+
"""
94+
return self._request(fill_query_params(kwargs.pop('path'), targetId), params=kwargs)
95+
96+
@sp_endpoint('/sd/negativeTargets/{}', method='DELETE')
97+
def delete_negative_targets(self, targetId, **kwargs) -> ApiResponse:
98+
r"""
99+
100+
Equivalent to using the updateNegativeTargetingClauses operation to set the state property of a targeting clause to archived. See Developer Notes for more information.
101+
102+
Archives a negative targeting clause.
103+
104+
path **negativeTargetId**:*integer* | Required. The negative targeting clause identifier.
105+
106+
Returns:
107+
108+
ApiResponse
109+
110+
"""
111+
return self._request(fill_query_params(kwargs.pop('path'), targetId), params=kwargs)
112+
113+
@sp_endpoint('/sd/negativeTargets/extended', method='GET')
114+
def list_negative_targets_extended(self, **kwargs) -> ApiResponse:
115+
r"""
116+
Gets an array of NegativeTargetingClauseEx objects for a set of requested negative targets. Note that this call returns the full set of negative targeting clause extended fields, but is less efficient than getNegativeTargets.
117+
118+
| query **startIndex**:*integer* | Optional. 0-indexed record offset for the result set. Default value : 0
119+
| query **count**:*integer* | Optional. Number of records to include in the paged response. Defaults to max page size.
120+
| query **stateFilter**:*string* | Optional. The returned array is filtered to include only ad groups with state set to one of the values in the specified comma-delimited list. Available values : enabled, paused, archived, enabled, paused, enabled, archived, paused, archived, enabled, paused, archived Default value : enabled, paused, archived.
121+
| query **campaignIdFilter**:*string* | Optional. A comma-delimited list of campaign identifiers.
122+
| query **adGroupIdFilter**:*string* | Optional. Restricts results to keywords associated with ad groups specified by identifier in the comma-delimited list.
123+
| query **targetIdFilter**:*string* | Optional. A comma-delimited list of target identifiers. Missing in official Amazon documentation
124+
125+
Returns:
126+
127+
ApiResponse
128+
129+
"""
130+
return self._request(kwargs.pop('path'), params=kwargs)
131+
132+
@sp_endpoint('/sd/negativeTargets/extended/{}', method='GET')
133+
def get_negative_target_extended(self, targetId, **kwargs) -> ApiResponse:
134+
r"""
135+
Gets a negative targeting clause with extended fields. Note that this call returns the full set of negative targeting clause extended fields, but is less efficient than getNegativeTarget.
136+
137+
path **negativeTargetId**:*integer* | Required. The negative targeting clause identifier.
138+
139+
Returns:
140+
141+
ApiResponse
142+
143+
"""
144+
return self._request(fill_query_params(kwargs.pop('path'), targetId), params=kwargs)

0 commit comments

Comments
 (0)