python-amazon-ad-api 1.0.1__tar.gz → 1.0.2__tar.gz

{python_amazon_ad_api-1.0.1 → python_amazon_ad_api-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.0.1
+Version: 1.0.2
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro
@@ -299,37 +299,13 @@ There is a new version 3 Portfolios API, please check the [migration guide](http
 * [Get test account information](https://python-amazon-ad-api.readthedocs.io/en/latest/api/advertising_test_account.html#ad_api.api.AdvertisingTestAccount.AdvertisingTestAccount.get_test_account)
 
 
-### Amazon Ads API v1 (new, unified)
+### [Amazon Ads API v1 (new, unified)](https://python-amazon-ad-api.readthedocs.io/en/latest/v1.html)
 
 The v1 API lives under `/adsApi/v1/` and is **not** split by product: every call targets the same resource and the product is selected in the request body with `adProductFilter`. It supersedes the per-product v2/v3 endpoints.
 
-```python
-from ad_api.api import v1
-```
-
-| Method | Endpoint | Body |
-|---|---|---|
-| `query_campaigns` | `POST /adsApi/v1/query/campaigns` | filters + `maxResults`/`nextToken` |
-| `create_campaigns` | `POST /adsApi/v1/create/campaigns` | `campaigns[]` (`adProduct`, `name`, `state` required) |
-| `update_campaigns` | `POST /adsApi/v1/update/campaigns` | `campaigns[]` (`campaignId` required) |
-| `delete_campaigns` | `POST /adsApi/v1/delete/campaigns` | `campaignIds[]` |
-
-All four return a **207 MultiStatus** response (except `query_campaigns`, which returns 200), so check the payload for per-entity errors.
+* [Campaigns](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/campaigns.html#ad_api.api.v1.Campaigns.Campaigns.query_campaigns)
+* [Ad Groups](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/ad_groups.html#ad_api.api.v1.AdGroups.AdGroups.query_ad_groups)
 
-```python
-from ad_api.api import v1
-
-result = v1.Campaigns(credentials=credentials, debug=True).query_campaigns(
-    body={
-        "adProductFilter": {"include": ["SPONSORED_PRODUCTS"]},
-        "stateFilter": {"include": ["ENABLED"]},
-        "maxResults": 100,
-    }
-)
-
-campaigns = result.payload.get("campaigns")
-next_token = result.payload.get("nextToken")
-```
 
 ### [Modules Available Sponsored Products 2.0](https://python-amazon-ad-api.readthedocs.io/en/latest/sp_v2.html)
 
@@ -409,6 +385,23 @@ Warning: `list_campaigns` is deprecated. Use the v1 `query_campaigns` method ins
 
 * [Reports](https://python-amazon-ad-api.readthedocs.io/en/latest/dsp/reports.html)
 
+### Amazon Ads API v1 - basic example
+
+```python
+from ad_api.api import v1
+
+result = v1.Campaigns(credentials=credentials, debug=True).query_campaigns(
+    body={
+        "adProductFilter": {"include": ["SPONSORED_PRODUCTS"]},
+        "stateFilter": {"include": ["ENABLED"]},
+        "maxResults": 100,
+    }
+)
+
+campaigns = result.payload.get("campaigns")
+next_token = result.payload.get("nextToken")
+```
+
 ### Simple Example Usage Campaigns with Credentials (v3, legacy)
 
 Warning: this example uses `CampaignsV3.list_campaigns`, which is deprecated. See the v1 `query_campaigns` example above.

{python_amazon_ad_api-1.0.1 → python_amazon_ad_api-1.0.2}/README.md

@@ -271,37 +271,13 @@ There is a new version 3 Portfolios API, please check the [migration guide](http
 * [Get test account information](https://python-amazon-ad-api.readthedocs.io/en/latest/api/advertising_test_account.html#ad_api.api.AdvertisingTestAccount.AdvertisingTestAccount.get_test_account)
 
 
-### Amazon Ads API v1 (new, unified)
+### [Amazon Ads API v1 (new, unified)](https://python-amazon-ad-api.readthedocs.io/en/latest/v1.html)
 
 The v1 API lives under `/adsApi/v1/` and is **not** split by product: every call targets the same resource and the product is selected in the request body with `adProductFilter`. It supersedes the per-product v2/v3 endpoints.
 
-```python
-from ad_api.api import v1
-```
-
-| Method | Endpoint | Body |
-|---|---|---|
-| `query_campaigns` | `POST /adsApi/v1/query/campaigns` | filters + `maxResults`/`nextToken` |
-| `create_campaigns` | `POST /adsApi/v1/create/campaigns` | `campaigns[]` (`adProduct`, `name`, `state` required) |
-| `update_campaigns` | `POST /adsApi/v1/update/campaigns` | `campaigns[]` (`campaignId` required) |
-| `delete_campaigns` | `POST /adsApi/v1/delete/campaigns` | `campaignIds[]` |
-
-All four return a **207 MultiStatus** response (except `query_campaigns`, which returns 200), so check the payload for per-entity errors.
+* [Campaigns](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/campaigns.html#ad_api.api.v1.Campaigns.Campaigns.query_campaigns)
+* [Ad Groups](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/ad_groups.html#ad_api.api.v1.AdGroups.AdGroups.query_ad_groups)
 
-```python
-from ad_api.api import v1
-
-result = v1.Campaigns(credentials=credentials, debug=True).query_campaigns(
-    body={
-        "adProductFilter": {"include": ["SPONSORED_PRODUCTS"]},
-        "stateFilter": {"include": ["ENABLED"]},
-        "maxResults": 100,
-    }
-)
-
-campaigns = result.payload.get("campaigns")
-next_token = result.payload.get("nextToken")
-```
 
 ### [Modules Available Sponsored Products 2.0](https://python-amazon-ad-api.readthedocs.io/en/latest/sp_v2.html)
 
@@ -381,6 +357,23 @@ Warning: `list_campaigns` is deprecated. Use the v1 `query_campaigns` method ins
 
 * [Reports](https://python-amazon-ad-api.readthedocs.io/en/latest/dsp/reports.html)
 
+### Amazon Ads API v1 - basic example
+
+```python
+from ad_api.api import v1
+
+result = v1.Campaigns(credentials=credentials, debug=True).query_campaigns(
+    body={
+        "adProductFilter": {"include": ["SPONSORED_PRODUCTS"]},
+        "stateFilter": {"include": ["ENABLED"]},
+        "maxResults": 100,
+    }
+)
+
+campaigns = result.payload.get("campaigns")
+next_token = result.payload.get("nextToken")
+```
+
 ### Simple Example Usage Campaigns with Credentials (v3, legacy)
 
 Warning: this example uses `CampaignsV3.list_campaigns`, which is deprecated. See the v1 `query_campaigns` example above.

{python_amazon_ad_api-1.0.1 → python_amazon_ad_api-1.0.2}/ad_api/api/v1/__init__.py

@@ -1,7 +1,9 @@
 from .campaigns import Campaigns
 from .ad_groups import AdGroups
+from .ads import Ads
 
 __all__ = [
     "Campaigns",
     "AdGroups",
+    "Ads",
 ]

python_amazon_ad_api-1.0.2/ad_api/api/v1/ads.py

@@ -0,0 +1,163 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class Ads(Client):
+    r"""
+    Ads(account='default', marketplace: Marketplaces = Marketplaces.EU, credentials=None, debug=False)
+
+    Amazon Ads API v1 - unified Ads endpoints
+
+    The v1 API is not split by product: every call goes to the same resource
+    (``/adsApi/v1/...``) and the product is selected in the request body via
+    ``adProductFilter``.
+
+    """
+
+    @sp_endpoint('/adsApi/v1/query/ads', method='POST')
+    def query_ads(self, **kwargs) -> ApiResponse:
+        r"""
+        query_ads(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Query Ads (operationId: QueryAd)
+
+        Request Body [Required]
+            | **adProductFilter** (dict) : [required]
+                | **include** (list<AdProduct>) : Enum [ AMAZON_DSP, SPONSORED_BRANDS, SPONSORED_DISPLAY, SPONSORED_PRODUCTS, SPONSORED_TELEVISION ]
+            | **adIdFilter** (dict) [optional]
+                | **include** (list<string>) : Ad identifiers
+            | **adGroupIdFilter** (dict) [optional]
+                | **include** (list<string>) : Ad group identifiers
+            | **campaignIdFilter** (dict) [optional]
+                | **include** (list<string>) : Campaign identifiers
+            | **marketplaceScopeFilter** (dict) [optional]
+                | **include** (list<MarketplaceScope>) : Enum [ GLOBAL, SINGLE_MARKETPLACE ]
+            | **nameFilter** (dict) [optional]
+                | **include** (list<string>) : Ad names
+                | **queryTermMatchType** (string) : [required] Enum [ BROAD_MATCH, EXACT_MATCH ]
+            | **retailerScopeFilter** (dict) [optional]
+                | **include** (list<RetailerScope>) : Enum [ AMAZON, OTHER_RETAILERS ]
+            | **stateFilter** (dict) [optional]
+                | **include** (list<State>) : Enum [ ARCHIVED, DRAFT, ENABLED, PAUSED ]
+            | **maxResults** (int) [optional] Maximum number of records in the response
+            | **nextToken** (string) [optional] Token to navigate to the next page
+
+        Headers
+            | **Amazon-Ads-AccountId** (string) [optional] Advertiser account identifier
+
+        Returns
+            ApiResponse
+                | **ads** (list), **nextToken** (string)
+
+        """
+        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/create/ads', method='POST')
+    def create_ads(self, **kwargs) -> ApiResponse:
+        r"""
+        create_ads(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Create Ads (operationId: CreateAd)
+
+        Request Body [Required]
+            | **ads** (list<dict>) : [required] One or more ad objects.
+              Each object requires **adProduct**, **adType**, **creative** and **state**.
+
+        Ad fields
+            | **adProduct** (string) : [required] Enum [ AMAZON_DSP, SPONSORED_BRANDS, SPONSORED_DISPLAY, SPONSORED_PRODUCTS, SPONSORED_TELEVISION ]
+            | **adType** (string) : [required] Enum [ AUDIO, COMPONENT, DISPLAY, PRODUCT_AD, THIRD_PARTY, VIDEO ]
+            | **creative** (dict) : [required] Exactly one of the six variants below
+            | **state** (string) : [required] Enum [ DRAFT, ENABLED, PAUSED ]
+            | **adGroupId** (string) [optional] Identifier of the parent ad group
+            | **name** (string) [optional] Name of the ad
+            | **marketplaceScope** (string) : Enum [ GLOBAL, SINGLE_MARKETPLACE ]
+            | **marketplaces** (list<dict>) : Marketplaces where the ad runs
+            | **marketplaceConfigurations** (list<dict>) : Per marketplace overrides
+            | **tags** (list<dict>) : Each with **key** and **value** (both required)
+
+        Creative variants (use exactly one, matching ``adType``)
+            | **audioCreative** (dict) : For ``AUDIO``
+            | **displayCreative** (dict) : For ``DISPLAY``, carries ``standardDisplaySettings``
+            | **videoCreative** (dict) : For ``VIDEO``, carries ``onlineVideoSettings`` / ``streamingTvSettings``
+            | **thirdPartyCreative** (dict) : For ``THIRD_PARTY``, carries ``thirdPartyDisplaySettings`` / ``thirdPartyVideoSettings``
+            | **componentCreative** (dict) : For ``COMPONENT``, carries ``assetBasedCreativeSettings``,
+              ``autoCollectionSettings``, ``brandGallerySettings``, ``brandStoreSettings``,
+              ``manualCollectionSettings``, ``productCollectionSettings``,
+              ``productVideoSettings``, ``responsiveEcommerceSettings``,
+              ``storeSpotlightSettings``
+            | **productCreative** (dict) : For ``PRODUCT_AD``, carries ``productCreativeSettings``
+
+            Example of the envelope::
+
+                {"creative": {"productCreative": {"productCreativeSettings": {...}}}}
+
+        Headers
+            | **Amazon-Ads-AccountId** (string) [optional] Advertiser account identifier
+
+        Returns
+            ApiResponse
+                | **207** MultiStatus response with partial errors. Inspect the payload
+                  to know which ads were created and which failed.
+
+        """
+        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/ads', method='POST')
+    def update_ads(self, **kwargs) -> ApiResponse:
+        r"""
+        update_ads(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Update Ads (operationId: UpdateAd)
+
+        Request Body [Required]
+            | **ads** (list<dict>) : [required] One or more ad objects.
+              Each object requires **adId** and may include any of the fields below.
+
+        Ad fields [optional except adId]
+            | **adId** (string) : [required] The identifier of the ad to update.
+            | **creative** (dict) : Same six-variant envelope as in create
+            | **name** (string) : Name of the ad
+            | **state** (string) : Enum [ DRAFT, ENABLED, PAUSED ]
+            | **marketplaceScope** (string) : Enum [ GLOBAL, SINGLE_MARKETPLACE ]
+            | **marketplaces** (list<dict>)
+            | **marketplaceConfigurations** (list<dict>)
+            | **tags** (list<dict>)
+
+        Headers
+            | **Amazon-Ads-AccountId** (string) [optional] Advertiser account identifier
+
+        Returns
+            ApiResponse
+                | **207** MultiStatus response with partial errors. Inspect the payload
+                  to know which ads were updated and which failed.
+
+        """
+        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/delete/ads', method='POST')
+    def delete_ads(self, **kwargs) -> ApiResponse:
+        r"""
+        delete_ads(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Delete Ads (operationId: DeleteAd)
+
+        Request Body [Required]
+            | **adIds** (list<string>) : [required] Ad identifiers to delete
+
+        Headers
+            | **Amazon-Ads-AccountId** (string) [optional] Advertiser account identifier
+
+        Returns
+            ApiResponse
+                | **207** MultiStatus response with partial errors. Inspect the payload
+                  to know which ad ids succeeded and which failed.
+
+        """
+        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)

python_amazon_ad_api-1.0.2/ad_api/version.py

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

{python_amazon_ad_api-1.0.1 → python_amazon_ad_api-1.0.2}/python_amazon_ad_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.0.1
+Version: 1.0.2
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro
@@ -299,37 +299,13 @@ There is a new version 3 Portfolios API, please check the [migration guide](http
 * [Get test account information](https://python-amazon-ad-api.readthedocs.io/en/latest/api/advertising_test_account.html#ad_api.api.AdvertisingTestAccount.AdvertisingTestAccount.get_test_account)
 
 
-### Amazon Ads API v1 (new, unified)
+### [Amazon Ads API v1 (new, unified)](https://python-amazon-ad-api.readthedocs.io/en/latest/v1.html)
 
 The v1 API lives under `/adsApi/v1/` and is **not** split by product: every call targets the same resource and the product is selected in the request body with `adProductFilter`. It supersedes the per-product v2/v3 endpoints.
 
-```python
-from ad_api.api import v1
-```
-
-| Method | Endpoint | Body |
-|---|---|---|
-| `query_campaigns` | `POST /adsApi/v1/query/campaigns` | filters + `maxResults`/`nextToken` |
-| `create_campaigns` | `POST /adsApi/v1/create/campaigns` | `campaigns[]` (`adProduct`, `name`, `state` required) |
-| `update_campaigns` | `POST /adsApi/v1/update/campaigns` | `campaigns[]` (`campaignId` required) |
-| `delete_campaigns` | `POST /adsApi/v1/delete/campaigns` | `campaignIds[]` |
-
-All four return a **207 MultiStatus** response (except `query_campaigns`, which returns 200), so check the payload for per-entity errors.
+* [Campaigns](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/campaigns.html#ad_api.api.v1.Campaigns.Campaigns.query_campaigns)
+* [Ad Groups](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/ad_groups.html#ad_api.api.v1.AdGroups.AdGroups.query_ad_groups)
 
-```python
-from ad_api.api import v1
-
-result = v1.Campaigns(credentials=credentials, debug=True).query_campaigns(
-    body={
-        "adProductFilter": {"include": ["SPONSORED_PRODUCTS"]},
-        "stateFilter": {"include": ["ENABLED"]},
-        "maxResults": 100,
-    }
-)
-
-campaigns = result.payload.get("campaigns")
-next_token = result.payload.get("nextToken")
-```
 
 ### [Modules Available Sponsored Products 2.0](https://python-amazon-ad-api.readthedocs.io/en/latest/sp_v2.html)
 
@@ -409,6 +385,23 @@ Warning: `list_campaigns` is deprecated. Use the v1 `query_campaigns` method ins
 
 * [Reports](https://python-amazon-ad-api.readthedocs.io/en/latest/dsp/reports.html)
 
+### Amazon Ads API v1 - basic example
+
+```python
+from ad_api.api import v1
+
+result = v1.Campaigns(credentials=credentials, debug=True).query_campaigns(
+    body={
+        "adProductFilter": {"include": ["SPONSORED_PRODUCTS"]},
+        "stateFilter": {"include": ["ENABLED"]},
+        "maxResults": 100,
+    }
+)
+
+campaigns = result.payload.get("campaigns")
+next_token = result.payload.get("nextToken")
+```
+
 ### Simple Example Usage Campaigns with Credentials (v3, legacy)
 
 Warning: this example uses `CampaignsV3.list_campaigns`, which is deprecated. See the v1 `query_campaigns` example above.

{python_amazon_ad_api-1.0.1 → python_amazon_ad_api-1.0.2}/python_amazon_ad_api.egg-info/SOURCES.txt

@@ -110,6 +110,7 @@ ad_api/api/sp/snapshots.py
 ad_api/api/sp/suggested_keywords.py
 ad_api/api/v1/__init__.py
 ad_api/api/v1/ad_groups.py
+ad_api/api/v1/ads.py
 ad_api/api/v1/campaigns.py
 ad_api/auth/__init__.py
 ad_api/auth/access_token_client.py

{python_amazon_ad_api-1.0.1 → python_amazon_ad_api-1.0.2}/setup.cfg

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

{python_amazon_ad_api-1.0.1 → python_amazon_ad_api-1.0.2}/setup.py

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

python_amazon_ad_api-1.0.1/ad_api/version.py

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