python-amazon-ad-api 1.5.9__tar.gz → 1.5.11__tar.gz

{python_amazon_ad_api-1.5.9/python_amazon_ad_api.egg-info → python_amazon_ad_api-1.5.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.5.9
+Version: 1.5.11
 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.5.11/ad_api/api/sb/media.py

@@ -0,0 +1,82 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class Media(Client):
+    """
+    Poll the status of media already uploaded for Sponsored Brands.
+
+    The v3 contract carries a single operation on this resource, GET
+    /media/describe, which answers the state of a media id. A creative can be
+    attached to a campaign once its media reaches PendingDeepValidation, but it
+    may still fail validation afterwards and move to Failed, so a campaign can
+    be rejected later. Only Available means the media finished processing and
+    is published for use.
+
+    /media/upload and /media/complete sit outside that contract. Probing
+    /media/upload answers 403 IncompleteSignatureException before the router
+    sees it, which suggests it expects an AWS SigV4 signature rather than the
+    bearer token this client sends. /media/complete answers 500 with a
+    NullPointerException on an empty body, so the route exists but its expected
+    fields are unknown. Neither is verified.
+    """
+
+    @sp_endpoint('/media/upload', method='POST')
+    def create_media(self, **kwargs) -> ApiResponse:
+        """
+        Creates an ephemeral resource (upload location) to upload Media for an Ad Program (SponsoredBrands).
+
+        The upload location is short lived and expires in 15 minutes. Once the upload is complete, /media/complete API should be used to notify that the upload is complete.
+
+        The upload location only supports PUT HTTP Method to upload the media content. If the upload location expires, API user will get 403 Forbidden response.
+
+        Request body
+            | **programType** (string): [required] [ SponsoredBrands ].
+            | **creativeType** (string): [required] [ Video ].
+
+        Returns:
+            | ApiResponse
+
+        """
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
+
+    @sp_endpoint('/media/complete', method='PUT')
+    def complete_media(self, **kwargs) -> ApiResponse:
+        """
+        Notifies the service that an upload started by create_media finished.
+
+        The upload location returned by create_media expires in 15 minutes, and
+        this call closes the loop after the PUT to that location succeeds.
+
+        The route answers 500 with a NullPointerException when the body is
+        empty, so the body is required but its fields are not documented in any
+        contract this package tracks. Pass a body as the registered example
+        does and inspect the error if the service refuses it.
+
+        Keyword Args
+            | body **body** (string | dict): the completion payload. [required]
+
+        Returns:
+            | ApiResponse
+
+        """
+        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, mediaId, **kwargs) -> ApiResponse:
+        """
+        Describes an uploaded media resource.
+
+        The media id goes in the query string, as the contract requires. The
+        answer carries a status of PendingDeepValidation, Available or Failed,
+        and 404 means the id is unknown. A media id that does not exist answers
+        400 InvalidMediaId, which means the route is live.
+
+        Keyword Args
+            | query **mediaId** (string): The media identifier. [required]
+
+        Returns:
+            | ApiResponse
+
+        Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi#tag/Media
+        """
+        return self._request(kwargs.pop('path'), params={'mediaId': mediaId, **kwargs})

python_amazon_ad_api-1.5.11/ad_api/api/sb/recommendations.py

@@ -0,0 +1,35 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class Recommendations(Client):
+    """
+    Ask for headline suggestions to use in a Sponsored Brands creative.
+
+    The resource has a single operation, POST with a HeadlineSuggestionRequest,
+    and it exists only in the 4.0 contract: the 3.0 contract does not carry the
+    route. The call suggests headlines; it neither creates nor changes a
+    creative, so it is safe to run while a campaign is live.
+    """
+
+    @sp_endpoint('/sb/recommendations/creative/headline', method='POST')
+    def list_recommendations(self, **kwargs) -> ApiResponse:
+        """
+        Returns suggested headlines for the products or store pages given.
+
+        The request names what the headlines are for, either by ASIN or by store
+        page, and caps how many suggestions come back. An answer of 422 means
+        the parameters were understood but rejected, which is what an empty or
+        contradictory request produces.
+
+        Request body (HeadlineSuggestionRequest)
+            | **asins** (array): the products the headlines are for.
+            | **storePages** (array): the store pages the headlines are for.
+            | **maxNumSuggestions** (number): how many suggestions to return.
+            | **adFormat** (string): the format the headlines are written for.
+
+        Returns:
+            | ApiResponse
+
+        Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/4-0/openapi
+        """
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)

{python_amazon_ad_api-1.5.9 → python_amazon_ad_api-1.5.11}/ad_api/api/sd/budget_rules.py

@@ -210,6 +210,12 @@ class BudgetRules(Client):
         r"""
         Gets the budget history for a campaign specified by identifier.
 
+        This route is not declared by the 3.0 contract this package tracks. A
+        probe against it answers 403 IncompleteSignatureException before the
+        service looks at the bearer token, so the route sits behind a gateway
+        that expects an AWS SigV4 signature. It exists, but this client cannot
+        call it as it stands.
+
         Param:
             | path **campaignId**\* (number). The campaign identifier.
             | query **nextToken** (string). To retrieve the next page of results, call the same operation and specify this token in the request. If the nextToken field is empty, there are no further results.

{python_amazon_ad_api-1.5.9 → python_amazon_ad_api-1.5.11}/ad_api/api/sd/snapshots.py

@@ -3,15 +3,35 @@ from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse, Uti
 
 class Snapshots(Client):
     """
-    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.
+    Request and read Sponsored Display snapshots.
+
+    A snapshot is an asynchronous record of what the account held at a moment:
+    the POST asks for one and answers 202 with no body, and the GET polls by
+    snapshot id until the record is ready. Both routes are marked deprecated in
+    the 3.0 contract, so they may stop answering; they are kept because the
+    account still uses them.
+
+    The contract also carries GET /sd/snapshots/{snapshotId}/download, which
+    answers 307 and redirects to the file. It is not wrapped here: a direct
+    download of the location returned by get_snapshot answers 401 unless the
+    client sends its own headers, which download_snapshot below already does.
     """
 
     @sp_endpoint('/sd/{}/snapshot', method='POST')
     def post_snapshot(self, recordType, **kwargs) -> ApiResponse:
         """
+        Requests a snapshot of one record type.
+
+        The contract answers 202 with an empty body and no snapshot id, so the
+        id has to be read from the account afterwards. Marked deprecated in the
+        3.0 contract.
+
+        Keyword Args
+            | path **recordType** (string): the record the snapshot covers. [required]
 
         Returns:
-            ApiResponse
+            | ApiResponse
+
         """
         return self._request(fill_query_params(kwargs.pop('path'), recordType), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
 
@@ -20,8 +40,15 @@ class Snapshots(Client):
         r"""
         Gets the status of a requested snapshot.
 
+        Answers 202 while the record is still being built. Once it is ready the
+        location field points at the file, and passing that location to
+        download_snapshot saves it. Marked deprecated in the 3.0 contract.
+
+        Keyword Args
+            | path **snapshotId** (string): the identifier of the snapshot. [required]
+
         Returns:
-            ApiResponse
+            | ApiResponse
         """
         return self._request(fill_query_params(kwargs.pop('path'), snapshotId), params=kwargs)
 
@@ -34,7 +61,7 @@ class Snapshots(Client):
         kwarg parameter **format** if not provided a format will return a url to download the snapshot (this url has a expiration time)
 
         Keyword Args
-            | **url** (string): The location obatined from get_snapshot [required]
+            | **url** (string): the location obtained from get_snapshot [required]
             | **file** (string): The path to save the file if mode is download json, zip or gzip. [optional]
             | **format** (string): The mode to download the snapshot: data (list), raw, url, json, zip, gzip. Default (url) [optional]
 

{python_amazon_ad_api-1.5.9 → python_amazon_ad_api-1.5.11}/ad_api/api/sp/budget_rules.py

@@ -210,6 +210,12 @@ class BudgetRules(Client):
         r"""
         Gets the budget history for a campaign specified by identifier.
 
+        This route is not declared by the 3.0 contract this package tracks. A
+        probe against it answers 403 IncompleteSignatureException before the
+        service looks at the bearer token, so the route sits behind a gateway
+        that expects an AWS SigV4 signature. It exists, but this client cannot
+        call it as it stands.
+
         Param:
             | path **campaignId**\* (number). The campaign identifier.
             | query **nextToken** (string). To retrieve the next page of results, call the same operation and specify this token in the request. If the nextToken field is empty, there are no further results.

python_amazon_ad_api-1.5.11/ad_api/api/stores.py

@@ -0,0 +1,53 @@
+from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse, Utils
+
+
+class Stores(Client):
+    """
+    Read engagement and insight metrics for a Brand Store.
+
+    Both routes are keyed by the brand entity id and both answer a versioned
+    media type: the client asks for v1 by default and the service picks the
+    shape of the answer from it. The 3.0 contract declares both as POST, which
+    is why they carry a body even though they only read.
+    """
+
+    @sp_endpoint('/stores/{}/asinMetrics', method='POST')
+    def get_asin_engagement_for_store(self, brandEntityId, version: int = 1, **kwargs) -> ApiResponse:
+        r"""
+        Engagement figures for the ASINs of a store.
+
+        Keyword Args
+            | path **brandEntityId** (string): the brand entity id of the store. [required]
+            | **version** (int): the media type version asked for. Defaults to 1.
+            | body **body** (string | dict): the ASIN list to measure. [required]
+
+        Returns:
+            | ApiResponse
+        """
+        content_type = 'application/vnd.GetAsinEngagementForStoreRequest.v'+ str(version) +'+json'
+        accept = 'application/vnd.GetAsinEngagementForStoreResponse.v'+ str(version) +'+json'
+        headers = {'Content-Type': content_type, 'Accept': accept}
+        return self._request(fill_query_params(kwargs.pop('path'), brandEntityId), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
+    @sp_endpoint('/stores/{}/insights', method='POST')
+    def get_insights_for_store_api(self, brandEntityId, version: int = 1, **kwargs) -> ApiResponse:
+        r"""
+        Insight metrics for a store, over the period named in the body.
+
+        The contract declares this route as POST, so a body is expected even
+        though the call only reads. An earlier version of this method sent the
+        same body on a GET.
+
+        Keyword Args
+            | path **brandEntityId** (string): the brand entity id of the store. [required]
+            | **version** (int): the media type version asked for. Defaults to 1.
+            | body **body** (string | dict): the period and grouping to report. [required]
+
+        Returns:
+            | ApiResponse
+
+        Documentation: https://advertising.amazon.com/API/docs/en-us/stores
+        """
+        content_type = 'application/vnd.GetInsightsForStoreRequest.v'+ str(version) +'+json'
+        headers = {'Content-Type': content_type}
+        return self._request(fill_query_params(kwargs.pop('path'), brandEntityId), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)

python_amazon_ad_api-1.5.11/ad_api/version.py

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

{python_amazon_ad_api-1.5.9 → python_amazon_ad_api-1.5.11/python_amazon_ad_api.egg-info}/PKG-INFO

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

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

{python_amazon_ad_api-1.5.9 → python_amazon_ad_api-1.5.11}/setup.py

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

python_amazon_ad_api-1.5.9/ad_api/api/sb/media.py

@@ -1,55 +0,0 @@
-from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
-
-
-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:
-        """
-        Creates an ephemeral resource (upload location) to upload Media for an Ad Program (SponsoredBrands).
-
-        The upload location is short lived and expires in 15 minutes. Once the upload is complete, /media/complete API should be used to notify that the upload is complete.
-
-        The upload location only supports PUT HTTP Method to upload the media content. If the upload location expires, API user will get 403 Forbidden response.
-
-        Request body
-            | **programType** (string): [required] [ SponsoredBrands ].
-            | **creativeType** (string): [required] [ Video ].
-
-        Returns:
-            | ApiResponse
-
-        """
-        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
-
-    @sp_endpoint('/media/complete', method='PUT')
-    def complete_media(self, **kwargs) -> ApiResponse:
-        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, 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.5.9/ad_api/api/sb/recommendations.py

@@ -1,7 +0,0 @@
-from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
-
-
-class Recommendations(Client):
-    @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)

python_amazon_ad_api-1.5.9/ad_api/api/stores.py

@@ -1,35 +0,0 @@
-from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse, Utils
-
-
-class Stores(Client):
-    """
-    Brand Metrics provides a new measurement solution that quantifies opportunities for your brand at each stage of the customer journey on Amazon, and helps brands understand the value of different shopping engagements that impact stages of that journey. You can now access Awareness and Consideration indices that compare your performance to peers using models predictive of consideration and sales. Brand Metrics quantifies the number of customers in the awareness and consideration marketing funnel stages and is built at scale to measure all shopping engagements with your brand on Amazon, not just ad-attributed engagements. Additionally, BM breaks out key shopping engagements at each stage of the shopping journey, along with the Return on Engagement, so you can measure the historical sales following a consideration event or purchase.
-    """
-
-    @sp_endpoint('/stores/{}/asinMetrics', method='POST')
-    def get_asin_engagement_for_store(self, brandEntityId, version: int = 1, **kwargs) -> ApiResponse:
-        r"""
-        getAsinEngagementForStore
-        """
-        content_type = 'application/vnd.GetAsinEngagementForStoreRequest.v'+ str(version) +'+json'
-        accept = 'application/vnd.GetAsinEngagementForStoreResponse.v'+ str(version) +'+json'
-        headers = {'Content-Type': content_type, 'Accept': accept}
-        return self._request(fill_query_params(kwargs.pop('path'), brandEntityId), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
-
-    @sp_endpoint('/stores/{}/insights', method='GET')
-    def get_insights_for_store_api(self, brandEntityId, version: int = 1, **kwargs) -> ApiResponse:
-        r"""
-        getInsightsForStoreAPI
-        """
-        content_type = 'application/vnd.GetInsightsForStoreRequest.v'+ str(version) +'+json'
-        # accept = 'application/vnd.GetInsightsForStoreResponse.v'+ str(version) +'+json'
-        headers = {
-            'Content-Type': content_type, 
-            # 'Accept': accept,
-        }
-        # return self._request(fill_query_params(kwargs.pop('path'), brandEntityId),
-        #                      data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)
-        return self._request(fill_query_params(kwargs.pop('path'), brandEntityId), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
-        
-        
-

python_amazon_ad_api-1.5.9/ad_api/version.py

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