python-amazon-ad-api 1.1.3__tar.gz → 1.1.5__tar.gz

{python_amazon_ad_api-1.1.3 → python_amazon_ad_api-1.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.1.3
+Version: 1.1.5
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro

{python_amazon_ad_api-1.1.3 → python_amazon_ad_api-1.1.5}/ad_api/api/sb/__init__.py

@@ -21,6 +21,8 @@ from .reports import Reports
 from .benchmarks import Benchmarks
 from .themes import Themes
 from .budget_rules import BudgetRules
+from .optimization_rules import OptimizationRules
+from .targeting_categories import TargetingCategories
 
 __all__ = [
     "Brands",
@@ -46,4 +48,6 @@ __all__ = [
     "Benchmarks",
     "Themes",
     "BudgetRules",
+    "OptimizationRules",
+    "TargetingCategories",
 ]

python_amazon_ad_api-1.1.5/ad_api/api/sb/optimization_rules.py

@@ -0,0 +1,153 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class OptimizationRules(Client):
+    """Sponsored Brands optimization rules.
+
+    Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/4-0/openapi
+
+    Every route in this family takes a versioned media type on the way in, and the
+    service routes on it:
+
+    .. warning::
+        With ``application/json`` the router answers ``404 Could not find
+        resource`` on every route here, which reads like a missing route but is
+        only the wrong media type. Verified on ``list`` and ``recommendations``.
+
+    The two read routes were probed against a live account; the four write routes
+    are built from the contract and not exercised.
+    """
+
+    _MEDIA_RULES = 'application/vnd.sbruleoptimization.v4+json'
+    _MEDIA_RECS = 'application/vnd.sboptimizationrecommendationresource.v4+json'
+
+    @sp_endpoint('/sb/rules/optimization/list', method='POST')
+    def list_optimization_rules(self, **kwargs) -> ApiResponse:
+        """
+        Lists optimization rules.
+
+        Request Body [Optional]
+            | **entityFilter** ({}): ``entityType`` and ``entityId``.
+            | **optimizationRuleIdFilter** ({}): ``include``, a list of rule ids.
+            | **maxResults** (number): Page size.
+            | **nextToken** (string): Pagination token.
+
+        Returns:
+            | ApiResponse, ``200``, with ``optimizationRules`` and ``totalCount``.
+
+        Example::
+
+            {"optimizationRules": [], "totalCount": 0}
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(kwargs.pop('body', {}), False),
+                             params=kwargs, headers={'Accept': self._MEDIA_RULES,
+                                                     'Content-Type': self._MEDIA_RULES})
+
+    @sp_endpoint('/sb/recommendations/optimization', method='POST')
+    def get_optimization_recommendation(self, costControlMetric, landingPages, **kwargs) -> ApiResponse:
+        """
+        Gets an optimization rule recommendation.
+
+        Request Body [Required]
+            | **costControlMetric** ({}): [required] Cost control metric.
+            | **landingPages** (array): [required] Each entry carries ``pageType``
+              and either ``asins`` or ``url``.
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. note::
+            An empty body answers ``400`` with both members named:
+            *"Value null at 'costControlMetric' failed to satisfy constraint"*.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'costControlMetric': costControlMetric,
+                                                      'landingPages': landingPages}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_RECS,
+                                                     'Content-Type': self._MEDIA_RECS})
+
+    @sp_endpoint('/sb/rules/optimization', method='POST')
+    def create_optimization_rules(self, optimizationRules, **kwargs) -> ApiResponse:
+        """
+        Creates optimization rules.
+
+        Request Body [Required]
+            | **optimizationRules** (array): [required]
+                | **entityType** (string): Type of the entity the rule applies to.
+                | **entityId** (string): Identifier of that entity.
+                | **conditions** (array): Each entry needs ``attributeName`` and
+                  ``criteria`` with ``comparisonOperator`` and ``value``.
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. note::
+            Not probed: creates optimization rules on the account.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'optimizationRules': optimizationRules}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_RULES,
+                                                     'Content-Type': self._MEDIA_RULES})
+
+    @sp_endpoint('/sb/rules/optimization', method='PUT')
+    def update_optimization_rules(self, optimizationRules, **kwargs) -> ApiResponse:
+        """
+        Updates optimization rules.
+
+        Request Body [Required]
+            | **optimizationRules** (array): [required] Each entry needs
+              ``optimizationRuleId`` and ``conditions``.
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. note::
+            Not probed: updates live optimization rules.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'optimizationRules': optimizationRules}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_RULES,
+                                                     'Content-Type': self._MEDIA_RULES})
+
+    @sp_endpoint('/sb/rules/optimization/associate', method='POST')
+    def associate_optimization_rules(self, optimizationRuleAssociations, **kwargs) -> ApiResponse:
+        """
+        Associates optimization rules with entities.
+
+        Request Body [Required]
+            | **optimizationRuleAssociations** (array): [required] Each entry needs
+              ``entityId``, ``entityType`` and ``optimizationRuleId``.
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. note::
+            Not probed: changes which rules apply to live campaigns.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(
+                                 {'optimizationRuleAssociations': optimizationRuleAssociations}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_RULES,
+                                                     'Content-Type': self._MEDIA_RULES})
+
+    @sp_endpoint('/sb/rules/optimization/disassociate', method='POST')
+    def disassociate_optimization_rules(self, optimizationRuleDisassociations, **kwargs) -> ApiResponse:
+        """
+        Disassociates optimization rules from entities.
+
+        Request Body [Required]
+            | **optimizationRuleDisassociations** (array): [required] Each entry
+              needs ``entityId``, ``entityType`` and ``optimizationRuleId``.
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. note::
+            Not probed: changes which rules apply to live campaigns.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(
+                                 {'optimizationRuleDisassociations': optimizationRuleDisassociations}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_RULES,
+                                                     'Content-Type': self._MEDIA_RULES})

python_amazon_ad_api-1.1.5/ad_api/api/sb/targeting_categories.py

@@ -0,0 +1,98 @@
+from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse, Utils
+
+
+class TargetingCategories(Client):
+    """Sponsored Brands targetable categories.
+
+    Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/4-0/openapi
+
+    All three routes are reads, and all three were probed against a live account.
+
+    .. note::
+        ``list_categories`` returns the tree under ``categoryTree``, which the
+        contract does not name. Each node carries ``categoryRefinementId``,
+        ``name``, ``parentCategoryRefinementId``, ``isTargetable`` and, where the
+        service knows it, ``asinCountRange`` with a ``min`` and ``max``.
+
+    .. note::
+        Large root categories come back with ``isTargetable`` set to ``false``:
+        they have to be narrowed down to their children before they can be used
+        as a target.
+    """
+
+    _MEDIA = 'application/vnd.sbtargeting.v4+json'
+
+    @sp_endpoint('/sb/targets/categories', method='GET')
+    def list_categories(self, supplySource, **kwargs) -> ApiResponse:
+        """
+        Gets the targetable category tree.
+
+        Keyword Args
+            | query **supplySource** (string): [required] ``AMAZON`` or
+              ``STREAMING_VIDEO``.
+            | query **locale** (string): [optional] Market locale, for instance
+              ``es_ES``, ``en_US`` or ``de_DE``.
+            | query **includeOnlyRootCategories** (boolean): [optional] Return
+              root categories only.
+            | query **parentCategoryRefinementId** (string): [optional] Return
+              the children of that category.
+            | query **nextToken** (string): [optional] Pagination token.
+
+        Returns:
+            | ApiResponse, ``200``, with the tree under ``categoryTree``.
+
+        Example node::
+
+            {"categoryRefinementId": "1909624031", "name": "Chupetes",
+             "asinCountRange": {"min": 1247, "max": 2078},
+             "isTargetable": true, "parentCategoryRefinementId": "1862267031"}
+        """
+        return self._request(kwargs.pop('path'), params=kwargs,
+                             headers={'Accept': self._MEDIA, 'Content-Type': self._MEDIA})
+
+    @sp_endpoint('/sb/targets/categories/{}/refinements', method='GET')
+    def list_refinements(self, categoryRefinementId, **kwargs) -> ApiResponse:
+        """
+        Gets the refinements of a category.
+
+        Keyword Args
+            | path **categoryRefinementId** (string): [required]
+            | query **locale** (string): [optional]
+            | query **nextToken** (string): [optional]
+
+        Returns:
+            | ApiResponse, ``200``.
+        """
+        return self._request(fill_query_params(kwargs.pop('path'), categoryRefinementId),
+                             params=kwargs,
+                             headers={'Accept': self._MEDIA, 'Content-Type': self._MEDIA})
+
+    @sp_endpoint('/sb/targets/products/count', method='POST')
+    def get_product_count(self, category, **kwargs) -> ApiResponse:
+        """
+        Gets the number of products in a category.
+
+        Request Body [Required]
+            | **category** (string): [required] Category refinement identifier.
+            | **ageRanges** (array of string): [optional]
+            | **brands** (array of string): [optional]
+            | **genres** (array of string): [optional]
+            | **isPrimeShipping** (boolean): [optional]
+            | **ratingRange** ({}): [optional] ``min`` and ``max`` integers.
+            | **priceRange** ({}): [optional] ``min`` and ``max`` numbers.
+
+        Returns:
+            | ApiResponse, ``200``.
+
+        Raises:
+            | ``400`` when ``category`` is missing, naming that member.
+        """
+        body = {'category': category}
+        for key in ('ageRanges', 'brands', 'genres', 'isPrimeShipping',
+                    'ratingRange', 'priceRange'):
+            if key in kwargs:
+                body[key] = kwargs.pop(key)
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(body, False),
+                             params=kwargs, headers={'Accept': self._MEDIA,
+                                                     'Content-Type': self._MEDIA})

python_amazon_ad_api-1.1.5/ad_api/version.py

@@ -0,0 +1 @@
+__version__ = "1.1.5"

{python_amazon_ad_api-1.1.3 → python_amazon_ad_api-1.1.5}/python_amazon_ad_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.1.3
+Version: 1.1.5
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro

{python_amazon_ad_api-1.1.3 → python_amazon_ad_api-1.1.5}/python_amazon_ad_api.egg-info/SOURCES.txt

@@ -47,10 +47,12 @@ ad_api/api/sb/landing_page_asins.py
 ad_api/api/sb/media.py
 ad_api/api/sb/negative_keywords.py
 ad_api/api/sb/negative_product_targeting.py
+ad_api/api/sb/optimization_rules.py
 ad_api/api/sb/product_targeting.py
 ad_api/api/sb/recommendations.py
 ad_api/api/sb/reports.py
 ad_api/api/sb/stores.py
+ad_api/api/sb/targeting_categories.py
 ad_api/api/sb/targeting_recommendations.py
 ad_api/api/sb/themes.py
 ad_api/api/sd/__init__.py

{python_amazon_ad_api-1.1.3 → python_amazon_ad_api-1.1.5}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = python-amazon-ad-api
-version = 1.1.3
+version = 1.1.5
 author = Daniel Alvaro
 author_email = denisneuf@hotmail.com
 description = Python wrapper for the Amazon Advertising API

{python_amazon_ad_api-1.1.3 → python_amazon_ad_api-1.1.5}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup
 
 setup(
     name='python-amazon-ad-api',
-    version='1.1.3',
+    version='1.1.5',
     install_requires=[
         "requests>=2.27.1,<2.35.0",
         "six>=1.16,<1.18",

python_amazon_ad_api-1.1.3/ad_api/version.py

@@ -1 +0,0 @@
-__version__ = "1.1.3"