python-amazon-ad-api 1.5.6__py3-none-any.whl → 1.5.8__py3-none-any.whl

ad_api/api/eligibility.py

@@ -1,72 +1,100 @@
 from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
-import json
 import logging
 
 
 class Eligibility(Client):
-    r""" """
+    r"""Product and program eligibility for Amazon ads."""
 
     @sp_endpoint('/eligibility/product/list', method='POST')
     def get_eligibility(self, **kwargs) -> ApiResponse:
         r"""
-
         get_eligibility(body: (dict, str)) -> ApiResponse
 
-        Gets a list of advertising eligibility objects for a set of products. Requests are permitted only for products sold by the merchant associated with the profile. Note that the request object is a list of ASINs, but multiple SKUs are returned if there is more than one SKU associated with an ASIN. If a product is not eligible for advertising, the response includes an object describing the reasons for ineligibility.
+        Product eligibility for a set of ASINs. Only products sold by the
+        merchant behind the profile are accepted. The request carries ASINs,
+        but several SKUs may come back for one ASIN, and an ineligible
+        product comes back with the reasons rather than being left out.
 
         body: | REQUIRED
+            '**adType**': *string* [dsp, sb, sd, sp] default sp
+            '**productDetailsList**': list of {asin, sku}
+            '**locale**': *string*
+        """
+        body = Utils.convert_body(kwargs.pop('body'), wrap=False)
+        return self._request(kwargs.pop('path'), data=body, params=kwargs)
 
-            '**adType**': *string*, {'description': 'Set to 'sp' to check product eligibility for Sponsored Products advertisements. Set to 'sb' to check product eligibility for Sponsored Brands advertisements. default: sp. [ sp, sb ]'}
+    @sp_endpoint('/eligibility/product/list', method='POST')
+    def get_eligibility_assistant(self, asin_list: list, sku_list: list = None,
+                                  ad_type: str = 'sp', locale: str = 'en-GB',
+                                  **kwargs) -> ApiResponse:
+        r"""
+        get_eligibility_assistant(asin_list, sku_list=None, ad_type='sp', locale='en-GB')
 
-            '**productDetailsList**': *dict*, {'asin*': 'An Amazon product identifier.', 'sku': 'A seller product identifier'}
+        Builds the body for get_eligibility from plain lists.
 
-            '**locale**': *string*, {'description': 'Set to the locale string in the table below to specify the language in which the response is returned.'}
+        sku_list is optional. When given it must be a list of the same length
+        as asin_list, so each entry pairs by position; a mismatch raises here
+        rather than sending a body the service will refuse.
+        """
 
-        Returns:
+        if not asin_list:
+            raise ValueError('asin_list is empty; at least one ASIN is required')
 
-            ApiResponse
+        if sku_list is not None:
+            if not isinstance(sku_list, list):
+                raise TypeError(
+                    'sku_list must be a list or None, got %s' % type(sku_list).__name__
+                )
+            if len(sku_list) != len(asin_list):
+                raise ValueError(
+                    'asin_list and sku_list must have the same length: %d != %d'
+                    % (len(asin_list), len(sku_list))
+                )
 
-        """
-        body = Utils.convert_body(kwargs.pop('body'), wrap=False)
-        return self._request(kwargs.pop('path'), data=body, params=kwargs)
+        details = []
 
-    @sp_endpoint('/eligibility/product/list', method='POST')
-    def get_eligibility_assistant(self, asin_list: list, sku_list: list = None, ad_type: str = "sp", locale: str = "en-GB", **kwargs) -> ApiResponse:
-        r"""
+        for index, asin in enumerate(asin_list):
+            entry = {'asin': asin}
+            if sku_list is not None:
+                entry['sku'] = sku_list[index]
+            details.append(entry)
 
-        get_eligibility_assistant(asin_list: list, sku_list: list = None, ad_type: str = "sp", locale:str = "en-GB") -> ApiResponse
+        body = {'adType': ad_type, 'productDetailsList': details, 'locale': locale}
 
-        Gets a list of advertising eligibility objects for a set of products. Requests are permitted only for products sold by the merchant associated with the profile. Note that the request object is a list of ASINs, but multiple SKUs are returned if there is more than one SKU associated with an ASIN. If a product is not eligible for advertising, the response includes an object describing the reasons for ineligibility.
+        logging.debug('get_eligibility_assistant body: %s', body)
 
-        | **asin_list**: 'A list of ASIN: An Amazon product identifier.'
-        | **sku_list**: 'A list of SKU: A seller product identifier'
-        | **adType**: *string*, {'description': 'Set to 'sp' to check product eligibility for Sponsored Products advertisements. Set to 'sb' to check product eligibility for Sponsored Brands advertisements. default: sp. [ sp, sb ]'}
-        | **locale**': *string*, {'description': 'Set to the locale string in the table below to specify the language in which the response is returned. default: en_GB'}
+        return self.get_eligibility(body=body, **kwargs)
 
-        Returns:
+    @sp_endpoint('/eligibility/programs', method='POST')
+    def get_program_eligibility(self, **kwargs) -> ApiResponse:
+        r"""
+        get_program_eligibility(body: dict) -> ApiResponse
 
-            ApiResponse
+        Account level eligibility for the Amazon ad programs, not for a
+        product: Sponsored Products, Sponsored Brands, Sponsored Display,
+        Stores, DirectToConsumer, Amazon Attribution and the rest.
 
-        """
+        Two media types are declared:
 
-        asin_dict = []
+            application/json                      the default shape, with skipChecks
+            application/vnd.programeligibility.v2+json
+                                                  v2, with maxResults and nextToken
 
-        required = {}
-        required.update({'adType': ad_type})
+        Pass media_type='v2' for the paginated one.
+        """
 
-        if len(asin_list) > 0 and isinstance(sku_list, str) or sku_list is None:
-            for asin in asin_list:
-                asin_dict.append({'asin': asin})
+        media_type = kwargs.pop('media_type', None)
 
-        if sku_list is not None and isinstance(sku_list, list):
-            if len(asin_list) == len(sku_list):
-                for i in range(len(asin_list)):
-                    asin_dict.append({'asin': asin_list[i], 'sku': sku_list[i]})
-            else:
-                logging.error("No coinciden las listas")
+        if media_type == 'v2':
+            content_type = 'application/vnd.programeligibility.v2+json'
+        else:
+            content_type = 'application/json'
 
-        required.update({'productDetailsList': asin_dict})
-        required.update({'locale': locale})
+        headers = {'Content-Type': content_type, 'Accept': 'application/json'}
 
-        data_str = json.dumps(required)
-        return self._request(kwargs.pop('path'), data=data_str, params=kwargs)
+        return self._request(
+            kwargs.pop('path'),
+            data=Utils.convert_body(kwargs.pop('body'), wrap=False),
+            params=kwargs,
+            headers=headers,
+        )

ad_api/api/v1/__init__.py

@@ -16,6 +16,7 @@ from .recommendations import Recommendations
 from .selling_accounts import SellingAccounts
 from .label_object_associations import LabelObjectAssociations
 from .geo_locations import GeoLocations
+from .recommendation_types import RecommendationTypes
 
 __all__ = [
     "Campaigns",
@@ -36,4 +37,5 @@ __all__ = [
     "SellingAccounts",
     "LabelObjectAssociations",
     "GeoLocations",
+    "RecommendationTypes",
 ]

ad_api/api/v1/recommendation_types.py

@@ -0,0 +1,48 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class RecommendationTypes(Client):
+    r"""
+    RecommendationTypes(account='default', marketplace: Marketplaces = Marketplaces.EU, credentials=None, debug=False)
+
+    Amazon Ads API v1 - recommendation types for Sponsored Brands
+
+    One route, read only, and the product is in the path:
+
+        POST /adsApi/v1/query/recommendationTypes/sb
+
+    This family lists the kinds of recommendation that exist. Recommendations
+    itself, in ad_api.api.v1.Recommendations, lists the ones the account
+    actually has.
+
+    Only the Sponsored Brands segment is published, and its schemas are
+    prefixed SB. The route keeps no SB in its name, so another product would
+    arrive as .../sp or .../sd beside it.
+    """
+
+    @sp_endpoint('/adsApi/v1/query/recommendationTypes/sb', method='POST')
+    def query_sb_recommendation_types(self, **kwargs) -> ApiResponse:
+        r"""
+        query_sb_recommendation_types(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Query SB Recommendation Types (operationId: SBQueryRecommendationType)
+
+        Request Body [All optional]
+            | **maxResults** (int) : 50..500, default 50
+            | **nextToken** (string) : token to navigate to the next page
+
+        Returns
+            | **recommendationTypes** (list<SBRecommendationType>) : 0..500
+                | **recommendationTypeId** (string) : [required] a UUID or a unique descriptive string
+                | **recommendationTypeTitle** (string) : [required]
+            | **nextToken** (string)
+
+        maxResults starts at 50, so a smaller value is a rejected body rather
+        than a shorter page. An empty body is valid and asks for the defaults.
+
+        Requires one of these permissions:
+            advertiser_campaign_view
+        """
+        schema_version = 'application/json'
+        headers = {"Accept": schema_version, "Content-Type": schema_version}
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)

ad_api/version.py

@@ -1 +1 @@
-__version__ = "1.5.6"
+__version__ = "1.5.8"

{python_amazon_ad_api-1.5.6.dist-info → python_amazon_ad_api-1.5.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.5.6
+Version: 1.5.8
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro
@@ -318,6 +318,7 @@ The v1 API lives under `/adsApi/v1/` and is **not** split by product: every call
 * [Selling Accounts](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/selling_accounts.html#ad_api.api.v1.SellingAccounts.SellingAccounts.query_selling_accounts)
 * [Label Object Associations](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/label_object_associations.html#ad_api.api.v1.LabelObjectAssociations.LabelObjectAssociations.query_label_object_associations)
 * [Geo Locations](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/geo_locations.html#ad_api.api.v1.GeoLocations.GeoLocations.create_geo_locations)
+* [Recommendation Types](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/recommendation_types.html#ad_api.api.v1.RecommendationTypes.RecommendationTypes.query_sb_recommendation_types)
 
 
 ### [Modules Available Sponsored Products](https://python-amazon-ad-api.readthedocs.io/en/latest/sp.html)

{python_amazon_ad_api-1.5.6.dist-info → python_amazon_ad_api-1.5.8.dist-info}/RECORD

@@ -1,5 +1,5 @@
 ad_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ad_api/version.py,sha256=u_3L7bjAA3w8BLRhTxxaVOCj_Cwsqn8JR4UZjPNAWbY,22
+ad_api/version.py,sha256=aGdl9Y3XkJkVSG47nNBoRdRr4veFwvs7t9uDlneAtdg,22
 ad_api/api/__init__.py,sha256=M07SD5BRC1L4_PqxLc8cKPI9Iq5zC2jPhkFUeHoh6CM,1632
 ad_api/api/account.py,sha256=CmOvCfHoPWaeTUJvtB0pNoNulZVSz4oMMCKIpVTpHos,2931
 ad_api/api/account_budgets.py,sha256=jFce5eLWAFK3ydjnYR7_Sv7B0-gHTG5bMTx_TcHyy1A,2319
@@ -9,7 +9,7 @@ ad_api/api/audiences.py,sha256=TQPt4avswFdCodNfQGDGxcJ2mY2LP2BfYvjxP6oJ0qY,3491
 ad_api/api/billing.py,sha256=pmBQzejCM8YIsI51KTVunDTVTKMIaox0D2B4acH4w6Y,23526
 ad_api/api/brand_metrics.py,sha256=DVg9qu_-sALxaQhQjRG6Isi_5SYxA5nmTg99jTe5Tls,9237
 ad_api/api/creative_assets.py,sha256=u0bCnioUFpGOQO5Z_MO0ErSLcAgSZB5GWM5wm2oW6L0,9687
-ad_api/api/eligibility.py,sha256=xbHMNxpRqToQDlG8y7nhhSr55ZZIJ_ZA304rmWa7Jx0,3680
+ad_api/api/eligibility.py,sha256=LS8CsTXRRVyBdVWOH_3cVybxTXUHahZMsrQHwdmuSxA,3893
 ad_api/api/exports.py,sha256=Y59C99axCAltMgu3gbfzdnoLKjNTsJ7s1z18yzcxzls,2788
 ad_api/api/history.py,sha256=tB4XawmQNxDMolaubDUjuIHtrYXRFuhOr4WCB8OJ1t8,2568
 ad_api/api/insights.py,sha256=b0m2_khfDGskbvn4sidsUpOvV-gr2bsjUup0kSo8HV8,2398
@@ -89,7 +89,7 @@ ad_api/api/sp/product_recommendations.py,sha256=vXoZIRqcFc5bo9MUprArKndxcEYe_Puy
 ad_api/api/sp/product_targeting_v3.py,sha256=vk_T0piHzP5uwt8HSHm5hFKP_0sXJD8nbyooPtM-BTs,9567
 ad_api/api/sp/ranked_keywords_recommendations.py,sha256=QYFje19TFmwhedh7sn5VJIypL8gp6d6tpBQCpf_SIXw,13094
 ad_api/api/sp/schedule_based_bid_optimization.py,sha256=G8VkS7iP1lTIAxZgbfRCLz8njw1DkVH9HQPOZ63pWNU,2371
-ad_api/api/v1/__init__.py,sha256=Y51M9bFX_nZhuiiJ1Co_9nQXi5fpCQSdK6BU75NPzqc,1167
+ad_api/api/v1/__init__.py,sha256=N1e8b3-ZkHINLz7Ejdb4QGRoKa6R5qMaSYdDFpnBzVQ,1248
 ad_api/api/v1/ad_associations.py,sha256=g5L8hAIagmsb-yQ09hP7z1zbVVe868NlpOOokv-Mouc,5812
 ad_api/api/v1/ad_extensions.py,sha256=kL-7xHaXXqb2jXTwZrY0oGttLAG0CW_IjBAqL_CI92U,5519
 ad_api/api/v1/ad_groups.py,sha256=pQhCVdve_O6kbL4mBA5bxxhKcKNl_BKqa7z9DvrxwaM,12626
@@ -104,6 +104,7 @@ ad_api/api/v1/geo_locations.py,sha256=gH1kR1rPQuIdzStB6wvWI40-XRo5yFyVI9AYYcjN5_
 ad_api/api/v1/label_object_associations.py,sha256=zXuD5cUAfqL-PRObvjOM54KC356HFqnzA5ehpGSJPYk,2597
 ad_api/api/v1/labels.py,sha256=jjPmafIQZTh99Ztj5MCcDC7UyoFFN0YuWdn2syqd3Yg,2438
 ad_api/api/v1/manager_accounts.py,sha256=cNAs1Qq6SYG0y4_4UpNBDfItqBJ1NvYACsIvFc8h-rw,4980
+ad_api/api/v1/recommendation_types.py,sha256=aEBfXu1EhzcRk9Nhin8_ieFiNnBiusX_vWviJw_qD08,2077
 ad_api/api/v1/recommendations.py,sha256=RJfmwUQ4YOcTdXiHz_U2ArJ01B29vKleRS_avJFjS14,3737
 ad_api/api/v1/reports.py,sha256=vJmWhIsALkX27HeijTsSUz3zrYhUBm4RodTCieJD8Y8,6657
 ad_api/api/v1/selling_accounts.py,sha256=0_R4yzvXGp_gFyfcZeWJyeIr7Wh4eGpLfK12podXqGA,1941
@@ -123,8 +124,8 @@ ad_api/base/exceptions.py,sha256=9D3M40ZIlLS0fA-aQh1BTWPOW-Nvf0tRhbA85jFnDJ4,438
 ad_api/base/helpers.py,sha256=UK7Q13vZ0mNdF54xzfzoGDn2O_cd2yPrK2X4rOzC41c,2334
 ad_api/base/marketplaces.py,sha256=44lvCcluXNpqTprWQ80e3weSQmQbJoWL-WDSOWVbCyQ,4657
 ad_api/base/utils.py,sha256=_qnCBOvyJTLgaZjJzUWTi38GGLHkQszXELs79133Rb4,5618
-python_amazon_ad_api-1.5.6.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
-python_amazon_ad_api-1.5.6.dist-info/METADATA,sha256=P-mpEe8OlzMB8dA-eu4MQkFh6nXHkr4Ey09arRKBTew,23957
-python_amazon_ad_api-1.5.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_amazon_ad_api-1.5.6.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
-python_amazon_ad_api-1.5.6.dist-info/RECORD,,
+python_amazon_ad_api-1.5.8.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
+python_amazon_ad_api-1.5.8.dist-info/METADATA,sha256=H-CSkEpq4IYNWM_YPyh57IIeZcPCnxrdrWgtapxHJh8,24150
+python_amazon_ad_api-1.5.8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_amazon_ad_api-1.5.8.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
+python_amazon_ad_api-1.5.8.dist-info/RECORD,,