python-amazon-ad-api 1.1.0__py3-none-any.whl → 1.1.2__py3-none-any.whl

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.

ad_api/api/sb/forecast.py

@@ -2,6 +2,89 @@ 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)
+    """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(),
+        )

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})

ad_api/api/sb/recommendations.py

@@ -2,6 +2,6 @@ from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
 
 
 class Recommendations(Client):
-    @sp_endpoint('/sb​/recommendations​/creative​/headline', method='POST')
+    @sp_endpoint('/sb/recommendations/creative/headline', method='POST')
     def list_recommendations(self, **kwargs) -> ApiResponse:
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)

ad_api/version.py

@@ -1 +1 @@
-__version__ = "1.1.0"
+__version__ = "1.1.2"

{python_amazon_ad_api-1.1.0.dist-info → python_amazon_ad_api-1.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.1.0
+Version: 1.1.2
 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.0.dist-info → python_amazon_ad_api-1.1.2.dist-info}/RECORD

@@ -1,5 +1,5 @@
 ad_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ad_api/version.py,sha256=LGVQyDsWifdACo7qztwb8RWWHds1E7uQ-ZqD8SAjyw4,22
+ad_api/version.py,sha256=5SgGjThsHu_ITn8V83BvCziqCwxdXxTQqcC3KQMHPfM,22
 ad_api/api/__init__.py,sha256=E9c0ZyK4vplMlKKEBF8CV5u7P4uSkTMSQsAuSQu5bfY,1514
 ad_api/api/account.py,sha256=CmOvCfHoPWaeTUJvtB0pNoNulZVSz4oMMCKIpVTpHos,2931
 ad_api/api/advertising_test_account.py,sha256=btOVbdk2tBDmyKSJaQbcIFyzNG8KFJVUmTe4p9xMhpU,1507
@@ -25,7 +25,7 @@ ad_api/api/stores.py,sha256=7W3RJKZyZOQ3nHzInvK9FDhWTXCH6Xe9a6dCBatEZ-o,2484
 ad_api/api/stream.py,sha256=JpnF8SKniOAHiEnEq1RPrh6tNy-Q2-8GPBTmnlxEXqQ,2989
 ad_api/api/validation_configurations.py,sha256=V3o06uWGwvA_Ly1x2lAiCk35Wo7DC_k8AtHgMdpm6wU,3830
 ad_api/api/sb/__init__.py,sha256=Lb7biv_idmsN6SkObBhQS4hZs3rdeQr0ytSvcl2tfSo,1274
-ad_api/api/sb/ad_creatives_v4.py,sha256=VwBDMnYdf10wtP6bVnTQjOLp7ZzJYueU_q_xN6Yxie4,10490
+ad_api/api/sb/ad_creatives_v4.py,sha256=86sF2lhSc3AC6d4P5TXyEnJMBjn9HvsJe4bbCQbSWK0,10508
 ad_api/api/sb/ad_groups.py,sha256=W06Fk0CCsuEYen1Bd8obR6aHpOMhk6tGWNWApecw59c,2882
 ad_api/api/sb/ad_groups_v4.py,sha256=f6KpOrJ2RsCa4aznP8vdGbXp0HGsCmLOvC9yXX2pESc,3669
 ad_api/api/sb/ads_v4.py,sha256=EOn-ts0cPqCwt5vdGq6rkDHyYPoT6vbDP8UQE-TFjmE,7931
@@ -34,15 +34,15 @@ ad_api/api/sb/bid_recommendations.py,sha256=ssO9XwYC9wK2GFaLtcsC-D3cZhDpCclcu1r0
 ad_api/api/sb/brands.py,sha256=XIMDzV0tJoPiOcY0KoCKcyIwYLPMlJ-zkB2SeRVMF4Q,1376
 ad_api/api/sb/campaigns.py,sha256=41yRnrgvx4-9Zra7Zdqtzr2Ptq__YD-mHOWbACaEQOk,13674
 ad_api/api/sb/campaigns_v4.py,sha256=_SfEQhHCS90UaSxOq35mm7NAr2BVpqJ4gzAbauVCZiA,7290
-ad_api/api/sb/forecast.py,sha256=hFOYQi4qlvsIkTRiqiexiI4XRv1tWmdnvQZk9Sl641A,334
+ad_api/api/sb/forecast.py,sha256=qf2ivhGX3_dv_uMGP9cmrt_x3S7QLg-P_5nCI8bAr00,3967
 ad_api/api/sb/keywords.py,sha256=P1dGqcLia349O0CwpBRURlIzgRc0cbFotkAGTSrErt4,7634
 ad_api/api/sb/keywords_recommendations.py,sha256=oA4FRBwDtk52SZK0RgWvjNQ7K2GX0G2zSoisJGiEYDw,629
 ad_api/api/sb/landing_page_asins.py,sha256=j3qi2-KccuEzGLZrl6EfZBSikW2R4B4l7TixpkAnTq8,1259
-ad_api/api/sb/media.py,sha256=wHa91d9qQb-bvBS5vaeNqlaAJ60iITedj-Hr9yR5aaw,1634
+ad_api/api/sb/media.py,sha256=5LTeM4AHSDKw_58aTB2nEZhIYdWkztH0syBXaovS1rs,2529
 ad_api/api/sb/negative_keywords.py,sha256=ww3IRbawidDHAaYIkX5SsH2OZKJj4UnCylqqFeq3OoY,6918
 ad_api/api/sb/negative_product_targeting.py,sha256=QbK1EhhzmnNOzGtbkrAZ4HS5OqiLU3nZBmsl1scd2D0,5085
 ad_api/api/sb/product_targeting.py,sha256=o6aB3hIh9jKvi_uTXFi--1hpnPFuXzQ-U9N7VUP_Bz4,5362
-ad_api/api/sb/recommendations.py,sha256=Ck4DLAKLTqwodmQJfih9MUD1sujG6LDjRlSoefKmOC4,356
+ad_api/api/sb/recommendations.py,sha256=_21L8tZPuArmJ30XyR1SKQHQH_yswvF0IMqwD9sLhgY,347
 ad_api/api/sb/reports.py,sha256=icw5DpRrqfj0idEo0NN1GPDpIWQun2h_c2Uwc7CpNUA,3801
 ad_api/api/sb/stores.py,sha256=sLdA6Lp37VR-ldu_sTUZIqc8MbMzysPhNOh05VaKBcA,4371
 ad_api/api/sb/targeting_recommendations.py,sha256=_7NxD5kC-Od11QOuLT03qpLVxEOIZgy-BtzniWK4CI8,2862
@@ -104,8 +104,8 @@ ad_api/base/exceptions.py,sha256=9D3M40ZIlLS0fA-aQh1BTWPOW-Nvf0tRhbA85jFnDJ4,438
 ad_api/base/helpers.py,sha256=naUkDLK466x_OBCPXxMlzRc2nPC6iQ6H_vyUji0MJJ0,2282
 ad_api/base/marketplaces.py,sha256=44lvCcluXNpqTprWQ80e3weSQmQbJoWL-WDSOWVbCyQ,4657
 ad_api/base/utils.py,sha256=_qnCBOvyJTLgaZjJzUWTi38GGLHkQszXELs79133Rb4,5618
-python_amazon_ad_api-1.1.0.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
-python_amazon_ad_api-1.1.0.dist-info/METADATA,sha256=tTSo2QGb0e6DIYzbUPaIclYQ1iLHTZ-OlglceAaMvGw,20486
-python_amazon_ad_api-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_amazon_ad_api-1.1.0.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
-python_amazon_ad_api-1.1.0.dist-info/RECORD,,
+python_amazon_ad_api-1.1.2.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
+python_amazon_ad_api-1.1.2.dist-info/METADATA,sha256=jEhN9JfVx95NGB5WsqesHlubfW8jfCOTmYFRofcUMAs,20486
+python_amazon_ad_api-1.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_amazon_ad_api-1.1.2.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
+python_amazon_ad_api-1.1.2.dist-info/RECORD,,