python-amazon-ad-api 1.1.4__py3-none-any.whl → 1.1.6__py3-none-any.whl

ad_api/api/sb/__init__.py

@@ -22,6 +22,8 @@ from .benchmarks import Benchmarks
 from .themes import Themes
 from .budget_rules import BudgetRules
 from .optimization_rules import OptimizationRules
+from .targeting_categories import TargetingCategories
+from .migration import Migration
 
 __all__ = [
     "Brands",
@@ -48,4 +50,6 @@ __all__ = [
     "Themes",
     "BudgetRules",
     "OptimizationRules",
+    "TargetingCategories",
+    "Migration",
 ]

ad_api/api/sb/migration.py

@@ -0,0 +1,154 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class Migration(Client):
+    """Sponsored Brands legacy campaign migration from 3.0 to 4.0.
+
+    Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/4-0/openapi
+
+    Two media types live in this family, both versioned and both required:
+
+    ========================================  ==========================================================
+    Route                                      Media type
+    ========================================  ==========================================================
+    ``/sb/v4/legacyCampaigns/*``               ``vnd.SponsoredBrands.SponsoredBrandsMigrationApi.v4``
+    ``/sb/v4/migrations/list``                 ``vnd.sbAdMigration.v4``
+    ========================================  ==========================================================
+
+    .. warning::
+        ``list_migrations`` answers ``404 Could not find resource`` when sent
+        ``application/json``, the same behaviour already recorded for forecasts,
+        budget recommendations and optimization rules. Amazon routes on media
+        type; a wrong one reads exactly like a missing route.
+
+    .. note::
+        ``migration_job_status`` and ``migration_job_results`` answer ``500
+        INTERNAL_ERROR`` for a job identifier that does not exist, instead of a
+        400 or a 404. The routes are live; the service trips over an unknown id.
+    """
+
+    _MEDIA_LEGACY = ('application/vnd.SponsoredBrands.'
+                     'SponsoredBrandsMigrationApi.v4+json')
+    _MEDIA_ADMIG = 'application/vnd.sbAdMigration.v4+json'
+
+    @sp_endpoint('/sb/v4/legacyCampaigns/migrationJob', method='POST')
+    def start_migration_job(self, campaignIds, enableThemeTargeting, **kwargs) -> ApiResponse:
+        """
+        Starts a migration job for 3.0 campaigns.
+
+        Request Body [Required]
+            | **campaignIds** (array of string): [required] Campaigns to migrate.
+            | **enableThemeTargeting** (boolean): [required] Carry theme targets
+              into the new campaigns.
+            | **isStagedMigration** (boolean): [optional]
+            | **newCampaignState** (string): [optional] State for the migrated
+              campaigns.
+            | **brandEntityId** (string): [optional]
+
+        Returns:
+            | ApiResponse, ``200``.
+
+        .. warning::
+            **This changes the account.** It starts a real migration of 3.0
+            campaigns into 4.0, which is not something a probe or a retry should
+            trigger by accident. Because of that it was never exercised here: the
+            shape comes from the contract only.
+
+        .. note::
+            Do not treat a timeout as a failed migration. The job may be running;
+            check ``migration_job_status`` before trying again.
+        """
+        body = {'campaignIds': campaignIds, 'enableThemeTargeting': enableThemeTargeting}
+        for key in ('isStagedMigration', 'newCampaignState', 'brandEntityId'):
+            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_LEGACY,
+                                                     'Content-Type': self._MEDIA_LEGACY})
+
+    @sp_endpoint('/sb/v4/legacyCampaigns/migrationJob/status', method='POST')
+    def migration_job_status(self, jobId, **kwargs) -> ApiResponse:
+        """
+        Gets the status of a migration job.
+
+        Request Body [Required]
+            | **jobId** (string): [required]
+
+        Returns:
+            | ApiResponse, ``200``.
+
+        .. note::
+            An unknown ``jobId`` answers ``500 INTERNAL_ERROR`` rather than a
+            business error. Not a sign that the route is missing.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'jobId': jobId}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_LEGACY,
+                                                     'Content-Type': self._MEDIA_LEGACY})
+
+    @sp_endpoint('/sb/v4/legacyCampaigns/migrationJob/results', method='POST')
+    def migration_job_results(self, jobId, **kwargs) -> ApiResponse:
+        """
+        Lists the per-campaign results of a migration job.
+
+        Request Body [Required]
+            | **jobId** (string): [required]
+            | **nextToken** (string): [optional]
+
+        Returns:
+            | ApiResponse, ``200``.
+
+        .. note::
+            An unknown ``jobId`` answers ``500 INTERNAL_ERROR``, as with the
+            status route.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'jobId': jobId}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_LEGACY,
+                                                     'Content-Type': self._MEDIA_LEGACY})
+
+    @sp_endpoint('/sb/v4/legacyCampaigns/overallMigrationResults', method='POST')
+    def overall_migration_results(self, **kwargs) -> ApiResponse:
+        """
+        Lists every campaign migration result for the advertiser.
+
+        Request Body [Optional]
+            | **nextToken** (string): [optional]
+
+        Returns:
+            | ApiResponse, ``200``. With nothing migrated yet the service answers
+            an empty object rather than a list, so do not assume a ``migrations``
+            key is always present.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(kwargs.pop('body', {}), False),
+                             params=kwargs, headers={'Accept': self._MEDIA_LEGACY,
+                                                     'Content-Type': self._MEDIA_LEGACY})
+
+    @sp_endpoint('/sb/v4/migrations/list', method='POST')
+    def list_migrations(self, **kwargs) -> ApiResponse:
+        """
+        Lists ad migrations.
+
+        Request Body [Optional]
+            | **adGroupIdFilter** ({}): ``include``, a list of ad group ids.
+            | **adIdFilter** ({}): ``include``, a list of ad ids.
+            | **campaignIdFilter** ({}): ``include``, a list of campaign ids.
+            | **adStateFilter** ({}): ``include`` with ``ENABLED``, ``PAUSED``
+              or ``ARCHIVED``.
+            | **migrationStatusFilter** ({}): ``include`` with ``ACCEPTED``,
+              ``ELIGIBLE``, ``MIGRATED`` or ``MIGRATION_FAILED``.
+            | **maxResults** (number): Page size.
+            | **nextToken** (string): Pagination token.
+
+        Returns:
+            | ApiResponse, ``200``, with ``migrations`` and ``totalCount``.
+
+        Example::
+
+            {"migrations": [], "totalCount": 0}
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(kwargs.pop('body', {}), False),
+                             params=kwargs, headers={'Accept': self._MEDIA_ADMIG,
+                                                     'Content-Type': self._MEDIA_ADMIG})

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

ad_api/version.py

@@ -1 +1 @@
-__version__ = "1.1.4"
+__version__ = "1.1.6"

{python_amazon_ad_api-1.1.4.dist-info → python_amazon_ad_api-1.1.6.dist-info}/METADATA

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

@@ -1,5 +1,5 @@
 ad_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ad_api/version.py,sha256=XxXhu8-QnuD9hA8Ah0WX5rgpt_DwOQmAwcK-FtpngyQ,22
+ad_api/version.py,sha256=fe1i7ytQ67cmOi4fKSpfB74e36dkRgec1zdg71uuRFM,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
@@ -24,7 +24,7 @@ ad_api/api/reports.py,sha256=gNmDHLULD2uaJgsMpIbCX9kabwhMXRr9WfZBtHUdsOY,6043
 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=-rseg1GpT0FaUL_s4c0HTU1OvriGccqVybrNV2oPqws,1407
+ad_api/api/sb/__init__.py,sha256=APbCAkWM1gzYuhpEUU98XDIKJKJx1NXALjLBXA9zdBU,1538
 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
@@ -40,6 +40,7 @@ ad_api/api/sb/keywords.py,sha256=P1dGqcLia349O0CwpBRURlIzgRc0cbFotkAGTSrErt4,763
 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=5LTeM4AHSDKw_58aTB2nEZhIYdWkztH0syBXaovS1rs,2529
+ad_api/api/sb/migration.py,sha256=2Pse2ixv73ZzqKhoCq6hAHzilAXwP8iphuIzTIOWIUE,7091
 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/optimization_rules.py,sha256=aj9tZwKdaOzjnAN-8FHb49aiejNZKCCCcR8fjffH4k0,6802
@@ -47,6 +48,7 @@ ad_api/api/sb/product_targeting.py,sha256=o6aB3hIh9jKvi_uTXFi--1hpnPFuXzQ-U9N7VU
 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_categories.py,sha256=mTU3hMEW_orG_D2mlTqUX14DEDPn9A11vH-wntECklk,4212
 ad_api/api/sb/targeting_recommendations.py,sha256=_7NxD5kC-Od11QOuLT03qpLVxEOIZgy-BtzniWK4CI8,2862
 ad_api/api/sb/themes.py,sha256=rjxdGcllaqLOUMoTKKgBVSH5iKuxMdF0w-dHq0X3-yU,4618
 ad_api/api/sd/__init__.py,sha256=RulShFVpowt2L_ZMcifFVgVrQEg5Uf9_SlVRydUnTF4,911
@@ -106,8 +108,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.4.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
-python_amazon_ad_api-1.1.4.dist-info/METADATA,sha256=Eu-MK8yO9WBcDpXS-oU_GW5N2lz2Ye8XEl_P1kA1npk,20486
-python_amazon_ad_api-1.1.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_amazon_ad_api-1.1.4.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
-python_amazon_ad_api-1.1.4.dist-info/RECORD,,
+python_amazon_ad_api-1.1.6.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
+python_amazon_ad_api-1.1.6.dist-info/METADATA,sha256=z5F7aaY5WflWIew3RRAup1tAxtWYyE7sTzzSd2lwIfw,20486
+python_amazon_ad_api-1.1.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_amazon_ad_api-1.1.6.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
+python_amazon_ad_api-1.1.6.dist-info/RECORD,,