python-amazon-ad-api 1.0.9__tar.gz → 1.1.1__tar.gz

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.0.9
+Version: 1.1.1
 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.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/ad_creatives_v4.py

@@ -58,6 +58,7 @@ class AdCreativesV4(Client):
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
     @sp_endpoint('/sb/ads/creatives/productCollection', method='POST')
+    @Utils.deprecated
     def create_new_version_product_collection_ad_creative(self, version: int = 4, **kwargs) -> ApiResponse:
         """
         Creates a new version of creative for given Sponsored Brands ad by supplying product collection creative content.
@@ -91,10 +92,10 @@ class AdCreativesV4(Client):
 
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
-    @sp_endpoint('/sb/ads/creatives/productCollection', method='POST')
+    @sp_endpoint('/sb/ads/creatives/storeSpotlight', method='POST')
     def create_new_version_store_spotlight_ad_creative(self, version: int = 4, **kwargs) -> ApiResponse:
         """
-        Creates a new version of creative for given Sponsored Brands ad by supplying product collection creative content.
+        Creates a new version of creative for a given Sponsored Brands ad by supplying store spotlight creative content.
 
         Request Body [Required]
             | **adId** (string) : The unique ID of a Sponsored Brands ad.

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/bid_recommendations.py

@@ -6,6 +6,13 @@ class BidRecommendations(Client):
     Use the Amazon Advertising API for Sponsored Brands for campaign, ad group, keyword, negative keyword, drafts, Stores, landing pages, and Brands management operations. For more information about Sponsored Brands, see the Sponsored Brands Support Center. For onboarding information, see the account setup topic.
     """
 
+    _ACCEPT = 'application/vnd.sbbidsrecommendation.v3+json'
+
+    @classmethod
+    def _accept(cls):
+        """Response media type the v3 contract declares for these routes."""
+        return {"Accept": cls._ACCEPT}
+
     @sp_endpoint('/sb/recommendations/bids', method='POST')
     def get_bid_recommendations(self, **kwargs) -> ApiResponse:
         r"""
@@ -32,4 +39,5 @@ class BidRecommendations(Client):
 
         """
 
-        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False),
+                             params=kwargs, headers=self._accept())

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/brands.py

@@ -6,6 +6,13 @@ class Brands(Client):
     Use the Amazon Advertising API for Sponsored Brands for campaign, ad group, keyword, negative keyword, drafts, Stores, landing pages, and Brands management operations. For more information about Sponsored Brands, see the Sponsored Brands Support Center. For onboarding information, see the account setup topic.
     """
 
+    _ACCEPT = 'application/vnd.brand.v3+json'
+
+    @classmethod
+    def _accept(cls):
+        """Response media type the v3 contract declares for these routes."""
+        return {"Accept": cls._ACCEPT}
+
     @sp_endpoint('/brands', method='GET')
     def list_brands(self, **kwargs) -> ApiResponse:
         """
@@ -22,4 +29,4 @@ class Brands(Client):
             | '**brandRegistryName**': *string*, {'description': 'The Brand name.'}
 
         """
-        return self._request(kwargs.pop('path'), params=kwargs)
+        return self._request(kwargs.pop('path'), params=kwargs, headers=self._accept())

python_amazon_ad_api-1.1.1/ad_api/api/sb/forecast.py

@@ -0,0 +1,90 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class Forecast(Client):
+    """Sponsored Brands campaign performance forecasts.
+
+    Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/4-0/openapi#tag/Forecasting
+
+    .. warning::
+        The Amazon backend for this route answers ``500 InternalFailure`` with an
+        empty body once the request passes validation. Verified from every angle:
+        keywords, targets, themes with landing pages, and mixed ad groups all fail
+        the same way, while the validation rules themselves do answer correctly
+        (``400`` with a business message). The client is built to the contract, so
+        it will work unchanged once Amazon fixes the service.
+
+    Validation rules observed against the live service, not in the contract:
+
+    * ``themes`` require ``landingPages``:
+      *"LandingPageUrl list is null or empty but theme list is not empty"*.
+    * An ad group with only ``landingPages`` is rejected:
+      *"Ad group is null or missing required fields"*; it needs something to bid on.
+    """
+
+    _ACCEPT = 'application/vnd.sbforecasting.v4+json'
+
+    @classmethod
+    def _accept(cls):
+        return {"Accept": cls._ACCEPT, "Content-Type": cls._ACCEPT}
+
+    @sp_endpoint('/sb/forecasts', method='POST')
+    def list_forecast(self, campaigns, version: int = 4, **kwargs) -> ApiResponse:
+        r"""
+        Gets performance forecasts for new campaigns.
+
+        ``campaigns`` is the list under the required ``campaigns`` key, ready to
+        send: the method wraps it in ``{"campaigns": [...]}``.
+
+        Positional Args
+            | **campaigns** (list): One or more campaign objects. The contract
+              states only one new campaign is supported for now.
+
+        Keyword Args
+            | **version** (int): Media type version, ``4`` by default.
+
+        Campaign object
+            | **budget** (number): [required] Budget amount.
+            | **budgetType** (string): [required] ``DAILY`` or ``LIFETIME``.
+            | **forecastType** (string): [required] ``WEEKLY`` or ``MONTHLY``.
+            | **adGroups** (list): [required] Ad groups to forecast.
+            | **startDate** (string): ``YYYY-MM-DD``.
+            | **endDate** (string): ``YYYY-MM-DD``, later than ``startDate``.
+            | **goal** (string): ``PAGE_VISIT``, ``BRAND_IMPRESSION_SHARE``,
+              ``ACQUIRE_NEW_CUSTOMERS`` or ``AD_VIEWS``. Defaults to ``PAGE_VISIT``
+              when the campaign was created without a goal.
+
+        Ad group object
+            | **keywords** (list): ``keywordText``, ``matchType`` and ``bid``.
+            | **targets** (list): ``expressions`` and ``bid``.
+            | **themes** (list): ``themeType`` and ``bid``. Requires landingPages.
+            | **landingPages** (list): ``landingPageUrl``.
+            | **negativeKeywords** (list): ``keywordText`` and ``matchType``.
+            | **negativeTargets** (list): ``expressions``.
+            | **creativeAsins** (list): ASINs used by the creative.
+
+        Returns:
+            | ApiResponse, with status ``207`` on success.
+
+        Example::
+
+            forecast = Forecast(account='account_name')
+            response = forecast.list_forecast(campaigns=[{
+                "budget": 100,
+                "budgetType": "DAILY",
+                "forecastType": "WEEKLY",
+                "startDate": "2026-11-01",
+                "endDate": "2026-11-30",
+                "goal": "PAGE_VISIT",
+                "adGroups": [{
+                    "themes": [{"themeType": "KEYWORDS_RELATED_TO_YOUR_BRAND", "bid": 0.5}],
+                    "landingPages": [{"landingPageUrl": "https://www.amazon.es/stores/page/XXXX"}],
+                }],
+            }])
+        """
+        return self._request(
+            kwargs.pop('path'),
+            data=Utils.convert_body({'campaigns': campaigns}, False),
+            params=kwargs,
+            headers=self._accept(),
+        )

python_amazon_ad_api-1.1.1/ad_api/api/sb/keywords_recommendations.py

@@ -0,0 +1,16 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class KeywordsRecommendations(Client):
+
+    _ACCEPT = 'application/vnd.sbkeywordrecommendation.v3+json'
+
+    @classmethod
+    def _accept(cls):
+        """Response media type the v3 contract declares for these routes."""
+        return {"Accept": cls._ACCEPT}
+
+    @sp_endpoint('/sb/recommendations/keyword', method='POST')
+    def list_keywords_recommendations(self, **kwargs) -> ApiResponse:
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False),
+                             params=kwargs, headers=self._accept())

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/landing_page_asins.py

@@ -6,6 +6,13 @@ class PageAsins(Client):
     Use the Amazon Advertising API for Sponsored Brands for campaign, ad group, keyword, negative keyword, drafts, Stores, landing pages, and Brands management operations. For more information about Sponsored Brands, see the Sponsored Brands Support Center. For onboarding information, see the account setup topic.
     """
 
+    _ACCEPT = 'application/vnd.pageasins.v3+json'
+
+    @classmethod
+    def _accept(cls):
+        """Response media type the v3 contract declares for these routes."""
+        return {"Accept": cls._ACCEPT}
+
     @sp_endpoint('/pageAsins', method='GET')
     def get_page_asins(self, **kwargs) -> ApiResponse:
         """
@@ -18,4 +25,4 @@ class PageAsins(Client):
         Returns
             asinList
         """
-        return self._request(kwargs.pop('path'), params=kwargs)
+        return self._request(kwargs.pop('path'), params=kwargs, headers=self._accept())

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/media.py

@@ -6,6 +6,13 @@ class Media(Client):
     Use this interface to request and retrieve store information. This can be used for Sponsored Brands campaign creation, to pull the store URL information, and for asset registration for Stores.
     """
 
+    # NOTE: /media/upload and /media/complete are NOT in the v3 contract.
+    # Probing /media/upload answers 403 IncompleteSignatureException before the
+    # router sees it, which suggests the route expects an AWS SigV4 signature
+    # rather than the bearer token this client sends. Not verified either way.
+    # /media/complete answers 500 with a NullPointerException on an empty body,
+    # so the route exists but its expected fields are unknown.
+
     @sp_endpoint('/media/upload', method='POST')
     def create_media(self, **kwargs) -> ApiResponse:
         """
@@ -30,5 +37,19 @@ class Media(Client):
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
 
     @sp_endpoint('/media/describe', method='GET')
-    def describe_media(self, **kwargs) -> ApiResponse:
-        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
+    def describe_media(self, mediaId, **kwargs) -> ApiResponse:
+        """
+        Describes an uploaded media resource.
+
+        The media id goes in the query string. Answered ``400 InvalidMediaId``
+        for an id that does not exist, which means the route is live.
+
+        Keyword Args
+            | path **mediaId** (string): The media identifier. [required]
+
+        Returns:
+            | ApiResponse
+
+        Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi
+        """
+        return self._request(kwargs.pop('path'), params={'mediaId': mediaId, **kwargs})

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/negative_keywords.py

@@ -6,6 +6,13 @@ class NegativeKeywords(Client):
     Use the Amazon Advertising API for Sponsored Brands for campaign, ad group, keyword, negative keyword, drafts, Stores, landing pages, and Brands management operations. For more information about Sponsored Brands, see the Sponsored Brands Support Center. For onboarding information, see the account setup topic.
     """
 
+    _ACCEPT = 'application/vnd.sbnegativekeyword.v3.2+json'
+
+    @classmethod
+    def _accept(cls):
+        """Response media type the v3 contract declares for these routes."""
+        return {"Accept": cls._ACCEPT}
+
     @sp_endpoint('/sb/negativeKeywords', method='GET')
     def list_negative_keywords(self, **kwargs) -> ApiResponse:
         r"""
@@ -26,7 +33,7 @@ class NegativeKeywords(Client):
             | ApiResponse
 
         """
-        return self._request(kwargs.pop('path'), params=kwargs)
+        return self._request(kwargs.pop('path'), params=kwargs, headers=self._accept())
 
     @sp_endpoint('/sb/negativeKeywords', method='PUT')
     def edit_negative_keywords(self, **kwargs) -> ApiResponse:

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/negative_product_targeting.py

@@ -6,6 +6,13 @@ class NegativeTargets(Client):
     Use the Amazon Advertising API for Sponsored Brands for campaign, ad group, keyword, negative keyword, drafts, Stores, landing pages, and Brands management operations. For more information about Sponsored Brands, see the Sponsored Brands Support Center. For onboarding information, see the account setup topic.
     """
 
+    _ACCEPT = 'application/vnd.sblistnegativetargetsresponse.v3.2+json'
+
+    @classmethod
+    def _accept(cls):
+        """Response media type the v3 contract declares for the listing route."""
+        return {'Accept': cls._ACCEPT}
+
     @sp_endpoint('/sb/negativeTargets/list', method='POST')
     def list_negative_targets(self, **kwargs) -> ApiResponse:
         r"""
@@ -28,7 +35,8 @@ class NegativeTargets(Client):
         Returns:
             ApiResponse
         """
-        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False),
+                             params=kwargs, headers=self._accept())
 
     @sp_endpoint('/sb/negativeTargets', method='PUT')
     def edit_negative_targets(self, **kwargs) -> ApiResponse:

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/reports.py

@@ -8,6 +8,13 @@ class Reports(Client):
 
     """
 
+    _ACCEPT = 'application/json'
+
+    @classmethod
+    def _accept(cls):
+        """Response media type the v3 contract declares for these routes."""
+        return {"Accept": cls._ACCEPT}
+
     @sp_endpoint('/v2/hsa/{}/report', method='POST')
     def post_report(self, recordType, **kwargs) -> ApiResponse:
         r"""Requests a Sponsored Brands report.
@@ -27,7 +34,8 @@ class Reports(Client):
             ApiResponse
 
         """
-        return self._request(fill_query_params(kwargs.pop('path'), recordType), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
+        return self._request(fill_query_params(kwargs.pop('path'), recordType), data=Utils.convert_body(kwargs.pop('body'), False),
+                             params=kwargs, headers=self._accept())
 
     @sp_endpoint('/v2/reports/{}', method='GET')
     def get_report(self, reportId, **kwargs) -> ApiResponse:
@@ -42,7 +50,7 @@ class Reports(Client):
         Returns:
             ApiResponse
         """
-        return self._request(fill_query_params(kwargs.pop('path'), reportId), params=kwargs)
+        return self._request(fill_query_params(kwargs.pop('path'), reportId), params=kwargs, headers=self._accept())
 
     def download_report(self, **kwargs) -> ApiResponse:
         r"""Downloads the report previously get report specified by location

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/ad_api/api/sb/stores.py

@@ -24,7 +24,8 @@ class Stores(Client):
         Returns:
             | ApiResponse
         """
-        return self._request(kwargs.pop('path'), params=kwargs)
+        return self._request(kwargs.pop('path'), params=kwargs,
+                             headers={'Accept': 'application/vnd.mediaasset.v3+json'})
 
     @sp_endpoint('/stores/assets', method='POST')
     def create_asset(self, image, brandEntityId, mediaType='brandLogo', filename=None, **kwargs) -> ApiResponse:

python_amazon_ad_api-1.1.1/ad_api/version.py

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

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/python_amazon_ad_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.0.9
+Version: 1.1.1
 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.0.9 → python_amazon_ad_api-1.1.1}/setup.cfg

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

{python_amazon_ad_api-1.0.9 → python_amazon_ad_api-1.1.1}/setup.py

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

python_amazon_ad_api-1.0.9/ad_api/api/sb/forecast.py

@@ -1,7 +0,0 @@
-from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
-
-
-class Forecast(Client):
-    @sp_endpoint('/sb/campaigns/shopperSegments/forecast', method='POST')
-    def list_forecast(self, **kwargs) -> ApiResponse:
-        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)

python_amazon_ad_api-1.0.9/ad_api/api/sb/keywords_recommendations.py

@@ -1,7 +0,0 @@
-from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
-
-
-class KeywordsRecommendations(Client):
-    @sp_endpoint('/sb/recommendations/keyword', method='POST')
-    def list_keywords_recommendations(self, **kwargs) -> ApiResponse:
-        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)

python_amazon_ad_api-1.0.9/ad_api/version.py

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