Product Targeting

Warning

Sponsored Product v3.0 is not available for Sandbox endpoint while v2.0 it is

Note

This API contains version 2.0 and some endpoints of 3.0 for older version compatibility please migrate to v3.0

class ad_api.api.sp.Targets(account='default', marketplace: Marketplaces = Marketplaces.EU, credentials=None, proxies=None, verify=True, timeout=None, debug=False, access_token=None)

Amazon Advertising API - Sponsored Products - Product Targetting

Use the Amazon Advertising API for Sponsored Products for campaign, ad group, keyword, negative keyword, and product ad management operations. For more information about Sponsored Products, see the Sponsored Products Support Center. For onboarding information, see the account setup topic.

Version 2.0

Doc: https://advertising.amazon.com/API/docs/en-us/sponsored-products/2-0/openapi#/Product%20targeting This specification is available for download from the Advertising API Sponsored Products 2.0.

Version 3.0

Doc: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#/Product%20Targeting This specification is available for download from the Advertising API Sponsored Products 3.0.

Endpoints available version 2.0

Method	Endpoint	Description
POST	/v2/sp/targets	Creates one or more targeting expressions.
PUT	/v2/sp/targets	Updates one or more targeting clauses.
GET	/v2/sp/targets	Gets a list of targeting clauses filtered by specified criteria.
GET	/v2/sp/targets/{targetId}	Get a targeting clause specified by identifier.
DELETE	/v2/sp/targets/{targetId}	Archives a targeting clause.
GET	/v2/sp/targets/extended	Gets a list of targeting clauses filtered by specified criteria.
GET	/v2/sp/targets/extended/{targetId}	Get a targeting clause specified by identifier.
POST	/v2/sp/targets/productRecommendations	Gets a list of recommended products for targeting.
GET	/v2/sp/targets/brands	Get recommended brands for Sponsored Products.

Endpoints available version 3.0

Method	Endpoint	Description
POST	/sp/targets/categories/recommendations	Returns a list of category recommendations for the input list of ASINs.
GET	/sp/negativeTargets/brands/recommendations	Returns brands recommended for negative targeting.
POST	/sp/targets/products/count	Get number of targetable asins based on refinements provided by the user.
GET	/sp/targets/categories	Returns all targetable categories.
POST	/sp/negativeTargets/brands/search	Returns brands related to keyword input for negative targeting.
GET	/sp/targets/category/{categoryId}/refinements	Returns refinements according to category input.

create_products_targets(self, **kwargs) → ApiResponse:

Creates one or more targeting expressions.

body: | REQUIRED {‘description’: ‘An array of asins objects.}’

‘campaignId’: number, {‘description’: ‘The number or recommendations returned in a single page.’}

‘adGroupId’: number, {‘description’: ‘The page number in the result set to return.’}

‘expression’

‘value’: string, {‘description’: ‘The expression value.’}

‘type’: string, {‘description’: ‘[ queryBroadMatches, queryPhraseMatches, queryExactMatches, asinCategorySameAs, asinBrandSameAs, asinPriceLessThan, asinPriceBetween, asinPriceGreaterThan, asinReviewRatingLessThan, asinReviewRatingBetween, asinReviewRatingGreaterThan, asinSameAs, queryBroadRelMatches, queryHighRelMatches, asinSubstituteRelated, asinAccessoryRelated, asinAgeRangeSameAs, asinGenreSameAs, asinIsPrimeShippingEligible ]’}

‘resolvedExpression’

‘value’: string, {‘description’: ‘The expression value.’}

‘type’: string, {‘description’: ‘[ queryBroadMatches, queryPhraseMatches, queryExactMatches, asinCategorySameAs, asinBrandSameAs, asinPriceLessThan, asinPriceBetween, asinPriceGreaterThan, asinReviewRatingLessThan, asinReviewRatingBetween, asinReviewRatingGreaterThan, asinSameAs, queryBroadRelMatches, queryHighRelMatches, asinSubstituteRelated, asinAccessoryRelated, asinAgeRangeSameAs, asinGenreSameAs, asinIsPrimeShippingEligible ]’}

‘expressionType’: string, {‘description’: ‘[ auto, manual ]’}

‘bid’: number, {‘description’: ‘The bid for ads sourced using the target. Min / Max 0.02 / 1000’}

Returns:

ApiResponse

edit_products_targets(self, **kwargs) → ApiResponse:

Updates one or more targeting clauses.

body: | REQUIRED {‘description’: ‘An array of asins objects.}’

‘targetId’: number, {‘description’: ‘The target id.’}

‘state’: string, {‘description’: ‘[ enabled, paused, archived ]’}

‘expression’

‘value’: string, {‘description’: ‘The expression value.’}

‘type’: string, {‘description’: ‘[ queryBroadMatches, queryPhraseMatches, queryExactMatches, asinCategorySameAs, asinBrandSameAs, asinPriceLessThan, asinPriceBetween, asinPriceGreaterThan, asinReviewRatingLessThan, asinReviewRatingBetween, asinReviewRatingGreaterThan, asinSameAs, queryBroadRelMatches, queryHighRelMatches, asinSubstituteRelated, asinAccessoryRelated, asinAgeRangeSameAs, asinGenreSameAs, asinIsPrimeShippingEligible ]’}

‘resolvedExpression’

‘value’: string, {‘description’: ‘The expression value.’}

‘type’: string, {‘description’: ‘[ queryBroadMatches, queryPhraseMatches, queryExactMatches, asinCategorySameAs, asinBrandSameAs, asinPriceLessThan, asinPriceBetween, asinPriceGreaterThan, asinReviewRatingLessThan, asinReviewRatingBetween, asinReviewRatingGreaterThan, asinSameAs, queryBroadRelMatches, queryHighRelMatches, asinSubstituteRelated, asinAccessoryRelated, asinAgeRangeSameAs, asinGenreSameAs, asinIsPrimeShippingEligible ]’}

‘expressionType’: string, {‘description’: ‘[ auto, manual ]’}

‘bid’: number, {‘description’: ‘The bid for ads sourced using the target. Min / Max 0.02 / 1000’}

Returns:

ApiResponse

list_products_targets(self, **kwargs) → ApiResponse:

Gets a list of targeting clauses filtered by specified criteria.

query startIndex:integer | Optional. 0-indexed record offset for the result set. Default value : 0

query count:integer | Optional. Number of records to include in the paged response. Defaults to max page size.

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.

query campaignIdFilter:string | Optional. A comma-delimited list of campaign identifiers.

query adGroupIdFilter:string | Optional. Restricts results to keywords associated with ad groups specified by identifier in the comma-delimited list.

query targetIdFilter:string | Optional. A comma-delimited list of target identifiers.

Returns:

ApiResponse

get_products_target(self, targetId, **kwargs) → ApiResponse:

Get a targeting clause specified by identifier.

path targetId:number | Required. The target identifier.

Returns:

ApiResponse

delete_products_target(self, targetId, **kwargs) → ApiResponse:

Archives a targeting clause.

path targetId:number | Required. The target identifier.

Returns:

ApiResponse

list_products_targets_extended(self, **kwargs) → ApiResponse:

Gets a list of targeting clauses filtered by specified criteria.

query startIndex:integer | Optional. 0-indexed record offset for the result set. Default value : 0

query count:integer | Optional. Number of records to include in the paged response. Defaults to max page size.

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.

query campaignIdFilter:string | Optional. A comma-delimited list of campaign identifiers.

query adGroupIdFilter:string | Optional. Restricts results to keywords associated with ad groups specified by identifier in the comma-delimited list.

query targetIdFilter:string | Optional. A comma-delimited list of target identifiers.

Returns:

ApiResponse

get_products_target_extended(self, targetId, **kwargs) → ApiResponse:

Get a targeting clause specified by identifier.

path targetId:number | Required. The target identifier.

Returns:

ApiResponse

get_products_targets_recommendations(self, **kwargs) → ApiResponse:

Gets a list of recommended products for targeting.

body: | REQUIRED {‘description’: ‘An array of asins objects.}’

‘pageSize’: number, {‘description’: ‘The number or recommendations returned in a single page.’}

‘pageNumber’: number, {‘description’: ‘The page number in the result set to return.’}

‘asins’: list>*string*, {‘description’: ‘A list of ASINs.’}

Returns:

ApiResponse

get_brand_targets(self, **kwargs) → ApiResponse:

Gets a list of recommended products for targeting.

path keyword:string | Optional Unique exclude categoryId. A keyword for which to get recommended brands. path categoryId:number | Optional Unique exclude keyword. Gets the top 50 brands for the specified category identifier.

Returns:

ApiResponse

list_products_targets_categories_recommendations(self, **kwargs) → ApiResponse:

Returns a list of category recommendations for the input list of ASINs. Use this API to discover relevant categories to target. To find ASINs, either use the Product Metadata API or browse the Amazon Retail Website.

header Prefer:string | Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.

body: | REQUIRED {‘description’: ‘An array of asins objects.}’

‘asins’: list>*string*, {‘description’: ‘List of input ASINs. This API does not check if the ASINs are valid ASINs. maxItems: 10000.’}

‘includeAncestor’: boolean, {‘description’: ‘Enable this if you would like to retrieve categories which are ancestor nodes of the original recommended categories. This may increase the number of categories returned, but decrease the relevancy of those categories.’}

Returns:

ApiResponse

list_negative_targets_brands_recommendations(self, **kwargs) → ApiResponse:

Returns brands recommended for negative targeting. Only available for Sellers and Vendors. These recommendations include your own brands because targeting your own brands usually results in lower performance than targeting competitors’ brands.

header Prefer:string | Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.

Returns:

ApiResponse

get_products_targets_count(self, **kwargs) → ApiResponse:

Get number of targetable asins based on refinements provided by the user. Please use the GetTargetableCategories API or the GetCategoryRecommendationsForASINs API to retrieve the category ID. Please use the GetRefinementsByCategory API to retrieve refinements data for a category.

header Prefer:string | Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.

Returns:

ApiResponse

list_targets_categories(self, **kwargs) → ApiResponse:

Returns all targetable categories. This API returns a large JSON string containing a tree of category nodes. Each category node has the fields - category id, category name, and child categories.

header Prefer:string | Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.

Returns:

ApiResponse

list_negative_targets_brands_search(self, **kwargs) → ApiResponse:

Returns brands related to keyword input for negative targeting.

header Prefer:string | Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.

Returns:

ApiResponse

list_products_targets_category_refinements(self, categoryId, **kwargs) → ApiResponse:

Get a targeting clause specified by identifier.

path categoryId:string | Required. The target identifier.

header Prefer:string | Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.

Returns:

ApiResponse