python-amazon-ad-api 1.5.11__py3-none-any.whl → 1.7.0__py3-none-any.whl

ad_api/api/exports.py

@@ -2,55 +2,148 @@ from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse, Uti
 
 
 class Exports(Client):
-    """Amazon Ads API Exports Version 3
+    """
+    Ask for a snapshot of one entity type and poll it until it is ready.
+
+    Four routes request an export, one per entity, and a fifth reads the result.
+    A request answers 202 with an export id; the file is built afterwards, so the
+    id is polled until its status reads COMPLETED and a download url appears.
+
+    The route picks the entity, not the body: /ads/export exports ads,
+    /campaigns/export exports campaigns, and so on. The body only narrows which
+    rows of that entity come back, by ad product and by state.
+
+    The status moves through PROCESSING, COMPLETED and FAILED. Only COMPLETED
+    carries a url, and that url expires at urlExpiresAt. On FAILED the answer
+    carries an error object with the reason.
+
+    Every route names its own media type, application/vnd.<entity>export.v<n>+json,
+    built from the entity and the version argument. The service routes on that
+    type, so the wrong one answers 406.
     """
     @sp_endpoint('/ads/export', method='POST')
     def ads_export(self, version: int = 1, **kwargs) -> ApiResponse:
         r"""
-        application/vnd.adsexport.v1+json
+        Requests an export of the ads.
+
+        Keyword Args
+            | body **body** (string | dict): filters. Every field is optional, and
+              omitting one leaves its default in place.
+                | **adProductFilter** (array): which ad products to include. One to
+                  three of SPONSORED_BRANDS, SPONSORED_DISPLAY, SPONSORED_PRODUCTS.
+                  Omitted, all three are included.
+                | **stateFilter** (array): which states to include. One to three of
+                  ARCHIVED, ENABLED, PAUSED. Omitted, only ENABLED and PAUSED come
+                  back, never ARCHIVED.
+            | **version** (int): media type version. Defaults to 1.
+
+        Returns:
+            | ApiResponse, 202 with an export id
         """
-        content_type = 'application/vnd.adsexport.v'+ str(version) +'+json'
-        accept = 'application/vnd.adsexport.v'+ str(version) +'+json'
+        content_type = 'application/vnd.adsexport.v' + str(version) + '+json'
+        accept = 'application/vnd.adsexport.v' + str(version) + '+json'
         headers = {'Content-Type': content_type, 'Accept': accept}
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
     @sp_endpoint('/campaigns/export', method='POST')
     def campaigns_export(self, version: int = 1, **kwargs) -> ApiResponse:
         r"""
-        application/vnd.campaignsexport.v1+json
+        Requests an export of the campaigns.
+
+        Keyword Args
+            | body **body** (string | dict): filters. Every field is optional, and
+              omitting one leaves its default in place.
+                | **adProductFilter** (array): which ad products to include. One to
+                  three of SPONSORED_BRANDS, SPONSORED_DISPLAY, SPONSORED_PRODUCTS.
+                  Omitted, all three are included.
+                | **stateFilter** (array): which states to include. One to three of
+                  ARCHIVED, ENABLED, PAUSED. Omitted, only ENABLED and PAUSED come
+                  back, never ARCHIVED.
+            | **version** (int): media type version. Defaults to 1.
+
+        Returns:
+            | ApiResponse, 202 with an export id
         """
-        content_type = 'application/vnd.campaignsexport.v'+ str(version) +'+json'
-        accept = 'application/vnd.campaignsexport.v'+ str(version) +'+json'
+        content_type = 'application/vnd.campaignsexport.v' + str(version) + '+json'
+        accept = 'application/vnd.campaignsexport.v' + str(version) + '+json'
         headers = {'Content-Type': content_type, 'Accept': accept}
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
-
     @sp_endpoint('/adGroups/export', method='POST')
     def adgroups_export(self, version: int = 1, **kwargs) -> ApiResponse:
         r"""
-        application/vnd.adgroupsexport.v1+json
+        Requests an export of the ad groups.
+
+        Keyword Args
+            | body **body** (string | dict): filters. Every field is optional, and
+              omitting one leaves its default in place.
+                | **adProductFilter** (array): which ad products to include. One to
+                  three of SPONSORED_BRANDS, SPONSORED_DISPLAY, SPONSORED_PRODUCTS.
+                  Omitted, all three are included.
+                | **stateFilter** (array): which states to include. One to three of
+                  ARCHIVED, ENABLED, PAUSED. Omitted, only ENABLED and PAUSED come
+                  back, never ARCHIVED.
+            | **version** (int): media type version. Defaults to 1.
+
+        Returns:
+            | ApiResponse, 202 with an export id
         """
-        content_type = 'application/vnd.adgroupsexport.v'+ str(version) +'+json'
-        accept = 'application/vnd.adgroupsexport.v'+ str(version) +'+json'
+        content_type = 'application/vnd.adgroupsexport.v' + str(version) + '+json'
+        accept = 'application/vnd.adgroupsexport.v' + str(version) + '+json'
         headers = {'Content-Type': content_type, 'Accept': accept}
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
-
     @sp_endpoint('/targets/export', method='POST')
     def targets_export(self, version: int = 1, **kwargs) -> ApiResponse:
         r"""
-        application/vnd.targetsexport.v1+json
+        Requests an export of the targets.
+
+        This route adds two filters of its own on top of the shared pair.
+
+        Keyword Args
+            | body **body** (string | dict): filters. Every field is optional, and
+              omitting one leaves its default in place.
+                | **adProductFilter** (array): which ad products to include. One to
+                  three of SPONSORED_BRANDS, SPONSORED_DISPLAY, SPONSORED_PRODUCTS.
+                  Omitted, all three are included.
+                | **stateFilter** (array): which states to include. One to three of
+                  ARCHIVED, ENABLED, PAUSED. Omitted, only ENABLED and PAUSED come
+                  back, never ARCHIVED.
+                | **negativeFilter** (array): booleans choosing negative targets,
+                  positive targets, or both. Omitted, both come back.
+                | **targetLevelFilter** (array): AD_GROUP, CAMPAIGN, or both.
+                  Omitted, both levels come back.
+            | **version** (int): media type version. Defaults to 1.
+
+        Returns:
+            | ApiResponse, 202 with an export id
         """
-        content_type = 'application/vnd.targetsexport.v'+ str(version) +'+json'
-        accept = 'application/vnd.targetsexport.v'+ str(version) +'+json'
+        content_type = 'application/vnd.targetsexport.v' + str(version) + '+json'
+        accept = 'application/vnd.targetsexport.v' + str(version) + '+json'
         headers = {'Content-Type': content_type, 'Accept': accept}
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
-
     @sp_endpoint('/exports/{}', method='GET')
     def get_export(self, exportId, typeExport, version: int = 1, **kwargs) -> ApiResponse:
         r"""
+        Reads the state of an export requested earlier.
+
+        Answers the export with its status and, once COMPLETED, the download url
+        and its expiry. A FAILED export carries an error object instead.
+
+        Keyword Args
+            | path **exportId** (string): the id returned when the export was
+              requested. [required]
+            | **typeExport** (string): the entity the export covers, used to build
+              the media type: ads, campaigns, adGroups or targets. [required]
+            | **version** (int): media type version. Defaults to 1.
+
+        Returns:
+            | ApiResponse
+                | **exportId** (string), **status** (string)
+                | **url** (string), **urlExpiresAt** (string)
+                | **createdAt**, **generatedAt**, **fileSize**, **error**
         """
-        content_type = 'application/vnd.'+typeExport+'export.v' + str(version) + '+json'
+        content_type = 'application/vnd.' + typeExport + 'export.v' + str(version) + '+json'
         headers = {'Content-Type': content_type, 'Accept': content_type}
         return self._request(fill_query_params(kwargs.pop('path'), exportId), 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 .location_indexes import LocationIndexes
 from .recommendation_types import RecommendationTypes
 
 __all__ = [
@@ -37,5 +38,6 @@ __all__ = [
     "SellingAccounts",
     "LabelObjectAssociations",
     "GeoLocations",
+    "LocationIndexes",
     "RecommendationTypes",
 ]

ad_api/api/v1/location_indexes.py

@@ -0,0 +1,109 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class LocationIndexes(Client):
+    """
+    Manage Smart Location Indexes for a campaign.
+
+    A Smart Location Index is a named dataset that maps postal codes to index
+    values, expressing relative audience quality or sales potential for one
+    advertiser. The values are supplied by the caller; the service only stores
+    and serves them for smart location targeting.
+
+    Writes are asynchronous. Creating or updating an index leaves it in PENDING
+    until the service has processed the data, and only then does it read ENABLED
+    and become usable for targeting. An index that fails processing carries
+    FAILED, or UPDATE_FAILED when it was an existing index being rewritten.
+
+    The contract requires one of advertiser_campaign_edit, campaign_edit,
+    dsp_campaign_edit or MasterAccount_Manager to write, and campaign_view
+    among others to read. On a Sponsored Ads seller profile this family is not
+    reachable: a probe answers 401 Customer <id> is not authorized to access
+    account, even though campaign_view is declared as enough.
+    """
+
+    @sp_endpoint('/adsApi/v1/create/locationIndexes', method='POST')
+    def create_location_index(self, **kwargs) -> ApiResponse:
+        r"""
+        Creates one or more Smart Location Indexes.
+
+        The index is processed asynchronously: it arrives with status PENDING and
+        only turns ENABLED once the service has read the data.
+
+        Request body
+            | **locationIndexes** (array): [required] one or more indexes.
+                | **indexName** (string): [required] the name of the index.
+                | **indexData** (dict): [required] the values.
+                | **campaignId** (string): the campaign the index belongs to.
+                | **countryCode** (string): one of AU, BE, BR, CA, DE, ES, FR,
+                  GB, IE, IN, IT, JP, MX, NL, SE, TR, US.
+
+        Returns:
+            | ApiResponse
+
+        """
+        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)
+
+    @sp_endpoint('/adsApi/v1/locationIndexes', method='GET')
+    def list_location_indexes(self, **kwargs) -> ApiResponse:
+        r"""
+        Lists every Smart Location Index of the advertiser, with its status.
+
+        Answers a page and a nextToken; when that token is empty there are no
+        more pages.
+
+        Keyword Args
+            | **maxResults** (int): page size.
+            | **nextToken** (string): the token from the previous page.
+
+        Returns:
+            | ApiResponse
+                | **locationIndexes** (array), **nextToken** (string)
+
+        """
+        schema_version = 'application/json'
+        headers = {"Accept": schema_version, "Content-Type": schema_version}
+        return self._request(kwargs.pop('path'), params=kwargs, headers=headers)
+
+    @sp_endpoint('/adsApi/v1/retrieve/locationIndexes', method='POST')
+    def retrieve_location_indexes(self, **kwargs) -> ApiResponse:
+        r"""
+        Reads one or more Smart Location Indexes by id.
+
+        An index still in PENDING is being processed and cannot yet be used for
+        smart location targeting.
+
+        Request body
+            | **indexIds** (array): [required] the identifiers to read.
+
+        Returns:
+            | ApiResponse
+
+        """
+        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)
+
+    @sp_endpoint('/adsApi/v1/update/locationIndexes', method='POST')
+    def update_location_indexes(self, **kwargs) -> ApiResponse:
+        r"""
+        Replaces the data of existing Smart Location Indexes.
+
+        The supplied values replace the ones the index held. The update is
+        asynchronous too: the index returns to PENDING until the new data has
+        been processed, and UPDATE_FAILED if that processing fails.
+
+        Request body
+            | **locationIndexes** (array): [required] one or more updates.
+                | **indexId** (string): [required] the index to rewrite.
+                | **indexData** (dict): the new values.
+
+        Returns:
+            | ApiResponse
+
+        """
+        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/auth/access_token_client.py

@@ -2,7 +2,7 @@ import requests
 import hashlib
 import logging
 from cachetools import TTLCache
-from ad_api.base import BaseClient
+from ad_api.shared.base_client import BaseClient
 
 from .credentials import Credentials
 from .access_token_response import AccessTokenResponse

ad_api/base/__init__.py

@@ -1,4 +1,4 @@
-from .base_client import BaseClient
+from ad_api.shared.base_client import BaseClient
 from .client import Client
 from .helpers import fill_query_params, sp_endpoint
 from .marketplaces import Marketplaces, MarketplacesIds, Currencies, CurrencySymbols, Locales
@@ -11,7 +11,6 @@ from .api_response import ApiResponse
 from .utils import Utils
 
 __all__ = [
-    'AccessTokenClient',
     'ApiResponse',
     'Client',
     'BaseClient',

ad_api/base/client.py

@@ -5,7 +5,7 @@ from cachetools import TTLCache
 from requests import request
 from ad_api.auth import AccessTokenClient, AccessTokenResponse
 from .api_response import ApiResponse
-from .base_client import BaseClient
+from ad_api.shared.base_client import BaseClient
 from .exceptions import get_exception_for_code, get_exception_for_content
 from .marketplaces import Marketplaces
 import os

ad_api/version.py

@@ -1 +1 @@
-__version__ = "1.5.11"
+__version__ = "1.7.0"