python-amazon-ad-api 1.2.4__py3-none-any.whl → 1.2.6__py3-none-any.whl

ad_api/api/history.py

@@ -5,26 +5,49 @@ class History(Client):
     """ """
 
     @sp_endpoint('/history', method='POST')
-    def get_history(self, **kwargs) -> ApiResponse:
+    def get_history(self, version: str = "1.0", **kwargs) -> ApiResponse:
         r"""
-
-        get_history(body: (dict, str, file)) -> ApiResponse
-
-        Returns history of changes for provided event sources that match the filters and time ranges specified. Only events that belong to the authenticated Advertiser can be queried. All times will be in UTC Epoch format. This API accepts identifiers in either the alphamumeric format (default), or the numeric format. If numeric IDs are supplied, then numeric IDs will be returned otherwise, alphanumeric IDs are returned.
-
-        body: | REQUIRED {'description': 'A HistoryQuery}'
-
-            | **from_date** | **int** | Max 90 days of history.
-            | **to_date** | **int** |
-            | **event_types**
-                | HistoryEventType
-            | **next_token** | **str** | token from previous response to get next set of data. | [optional]
-            | **page_offset** | **int** | Mutually exclusive with 'nextToken'. Max results with pageOffset is 10000. Use nextToken instead for more results. | [optional]
-            | **count** | **int** | Requested number of results. Default 100. Minimum 50. Maximum 200. | [optional]
-            | **sort**
-                | HistorySortParameter
-            | **any string name** | **bool, date, datetime, dict, float, int, list, str, none_type** | any string name can be used but the value must be the correct type | [optional]
+        Returns the changes made to campaigns, ad groups, ads and the rest of the
+        entity tree, within a time range. Only events belonging to the
+        authenticated advertiser come back.
+
+        Keyword Args
+
+        - ``version`` (string): the ``Accept`` version, ``"1.0"`` by default.
+          Pass ``"1.1"`` to query the ``THEME`` event type, which the service
+          refuses at 1.0. The other six types work at either. [optional]
+
+        Request Body (required)
+
+        - ``fromDate`` (integer): epoch in **milliseconds**, not seconds.
+        - ``toDate`` (integer): epoch in milliseconds.
+        - ``eventTypes`` (object): one or more of ``AD``, ``AD_GROUP``,
+          ``CAMPAIGN``, ``KEYWORD``, ``NEGATIVE_KEYWORD``, ``PRODUCT_TARGETING``
+          and ``THEME``. Each carries an object, usually ``{}`` or
+          ``{"filters": [...]}``.
+        - ``count`` (integer): page size. Default 100, minimum 50, maximum 200.
+        - ``nextToken`` (string): token from a previous answer. Mutually
+          exclusive with ``pageOffset``.
+        - ``pageOffset`` (integer): alternative to ``nextToken``, up to 10000.
+        - ``sort`` (object): ``{"direction": "ASC"|"DESC", "key": "DATE"}``.
+
+        The field names are camelCase and the service rejects anything else: a
+        body written with ``from_date`` answers ``400`` naming ``fromDate`` as a
+        required field. The dates are counted back from the moment of the
+        request, so a window computed once and reused drifts out of range: the
+        service measures 90 days from its own clock, and a few seconds of drift
+        past the edge answers ``400 fromDate is more than 90 days ago``.
+
+        This route throttles. Seven calls within twelve seconds answered ``429``.
+
+        Returns
+            ApiResponse with ``events``, ``pageSize``, ``pageOffset``,
+            ``maxPageNumber`` and ``totalRecords``. An empty ``events`` with
+            ``totalRecords`` at ``0`` means the account saw no change in the
+            window, not that the call failed.
 
         """
+        accept = 'application/vnd.historyresponse.v' + version + '+json'
+        headers = {'Accept': accept}
         body = Utils.convert_body(kwargs.pop('body'), wrap=False)
-        return self._request(kwargs.pop('path'), data=body, params=kwargs)
+        return self._request(kwargs.pop('path'), data=body, params=kwargs, headers=headers)

ad_api/api/insights.py

@@ -5,38 +5,48 @@ class Insights(Client):
     """ """
 
     @sp_endpoint('/insights/audiences/{}/overlappingAudiences', method='GET')
-    def get_insights(self, audienceId: str, version: int = 1, **kwargs) -> ApiResponse:
+    def get_insights(self, audienceId: str, version: int = 2, **kwargs) -> ApiResponse:
         r"""
-        get_insights(audienceId: str, version: int = 1, **kwargs) -> ApiResponse
+        Returns the audiences that overlap with the one given, ranked by affinity.
 
-        Retrieves the top audiences that overlap with the provided audience.
+        Keyword Args
 
-        Requires one of these permissions: ["advertiser_campaign_edit","advertiser_campaign_view"]
+        - ``version`` (int): the ``Accept`` version. **Only 2 answers**; 1 was
+          retired and replies ``415`` naming v2 as the sole supported type.
+          Defaults to 2. [optional]
 
-        path **audienceId**:string | Required. The identifier of an audience.
+        Path
 
-        internal **version**:int | Optional. The version of the overlapping audiences accept 'application/vnd.insightsaudiencesoverlap.v'+str(version)+'+json'. Available values : 1, 2 Default: 1
+        - ``audienceId`` (string): required. The audience to measure against.
 
-        query **adType**:string | Required. The advertising program. Available values : DSP, SD
+        Query
 
-        query **advertiserId**:string | Optional. The identifier of the advertiser you'd like to retrieve overlapping audiences for. This parameter is required for the DSP adType, but is optional for the SD adType.
+        - ``adType`` (string): required in practice, ``SD`` or ``DSP``. When it
+          is left out the service assumes ``DSP`` and answers
+          ``400 Missing advertiserId parameter for DSP request``, which names the
+          wrong parameter. Send it explicitly.
+        - ``advertiserId`` (string): required for ``DSP``, ignored for ``SD``.
+        - ``audienceCategory`` (string): keep only audiences of that category,
+          such as ``"In-market"``. The contract calls it an array; a plain string
+          is what the service accepts and applies.
+        - ``maxResults`` (integer): how many overlaps to return. Default 30.
+          Works, and the count follows it.
+        - ``nextToken`` (string): token from a previous answer. Subsequent calls
+          must repeat the same parameters.
 
-        query **minimumAudienceSize**:number | Optional. If specified, the sizes of all returned overlapping audiences will be at least the provided size. This parameter is supported only for request to return application/vnd.insightsaudiencesoverlap.v1+json.
+        Three parameters are accepted and then ignored: ``minimumAudienceSize``,
+        ``maximumAudienceSize`` and ``minimumOverlapAffinity``. The call answers
+        ``200`` with the same count as without them, so a filter that was never
+        applied is indistinguishable from one that matched everything. Check the
+        count, not the status.
 
-        query **maximumAudienceSize**:number | Optional. If specified, the sizes of all returned overlapping audiences will be at most the provided size. This parameter is supported only for request to return application/vnd.insightsaudiencesoverlap.v1+json.
-
-        query **minimumOverlapAffinity**:number | Optional. If specified, the affinities of all returned overlapping audiences will be at least the provided affinity.
-
-        query **maximumOverlapAffinity**:number | Optional. If specified, the affinities of all returned overlapping audiences will be at most the provided affinity.
-
-        query **audienceCategory**:array[string] | Optional. f specified, the categories of all returned overlapping audiences will be one of the provided categories.
-
-        query **maxResults**:integer | Optional. Sets the maximum number of overlapping audiences in the response. This parameter is supported only for request to return application/vnd.insightsaudiencesoverlap.v2+json. Default value : 30
-
-        query **nextToken**:string | Optional. TToken to be used to request additional overlapping audiences. If not provided, the top 30 overlapping audiences are returned. Note: subsequent calls must be made using the same parameters as used in previous requests.
+        Returns
+            ApiResponse with ``requestedAudienceMetadata``, ``overlappingAudiences``,
+            ``marketplace`` and ``nextToken``. Each overlap carries
+            ``audienceMetadata`` and ``affinity``, a number where higher means a
+            closer match.
 
         """
-
         contentType = 'application/vnd.insightsaudiencesoverlap.v' + str(version) + '+json'
         headers = {'Accept': contentType}
         return self._request(fill_query_params(kwargs.pop('path'), audienceId), params=kwargs, headers=headers)

ad_api/version.py

@@ -1 +1 @@
-__version__ = "1.2.4"
+__version__ = "1.2.6"

{python_amazon_ad_api-1.2.4.dist-info → python_amazon_ad_api-1.2.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.2.4
+Version: 1.2.6
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro
@@ -267,7 +267,7 @@ curl \
 * [Invoices](https://python-amazon-ad-api.readthedocs.io/en/latest/api/invoices.html)
 * [Billing](https://python-amazon-ad-api.readthedocs.io/en/latest/api/billing.html)
 * [Audiences](https://python-amazon-ad-api.readthedocs.io/en/latest/api/audiences.html)
-* [Change History open Beta](https://python-amazon-ad-api.readthedocs.io/en/latest/api/history.html)
+* [Change History](https://python-amazon-ad-api.readthedocs.io/en/latest/api/history.html)
 * [Creative Assets open Beta](https://python-amazon-ad-api.readthedocs.io/en/latest/api//creative_assets.html)
 * [Elegibility](https://python-amazon-ad-api.readthedocs.io/en/latest/api/eligibility.html)
 * [Insights](https://python-amazon-ad-api.readthedocs.io/en/latest/api/insights.html)

{python_amazon_ad_api-1.2.4.dist-info → python_amazon_ad_api-1.2.6.dist-info}/RECORD

@@ -1,5 +1,5 @@
 ad_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ad_api/version.py,sha256=XBKH8E1LmDxv06U39yqMBbXZapOERFgICEDYZs_kRso,22
+ad_api/version.py,sha256=vMQK58X8_YZGKzRm0ThvPAKFtpfyejGmUnDrY9RQ13w,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
@@ -10,8 +10,8 @@ ad_api/api/brand_metrics.py,sha256=IlOlVJ2t6cL5DA49RaM3M1AW_3KFEyal08e0ZcnLdVE,6
 ad_api/api/creative_assets.py,sha256=EzxrQbxMe5Y1b6qONJ3zi8cwoorCZAqSmHhiug6d87E,6671
 ad_api/api/eligibility.py,sha256=xbHMNxpRqToQDlG8y7nhhSr55ZZIJ_ZA304rmWa7Jx0,3680
 ad_api/api/exports.py,sha256=Y59C99axCAltMgu3gbfzdnoLKjNTsJ7s1z18yzcxzls,2788
-ad_api/api/history.py,sha256=KmpUodvxTQPSeJ1kyOSm_uHnfaR23Y6SUvB3gYn5uh4,1727
-ad_api/api/insights.py,sha256=Z4h00erksU58yjGm5qX_sHKDAv5UuJagqCA0d3rUlJU,2932
+ad_api/api/history.py,sha256=tB4XawmQNxDMolaubDUjuIHtrYXRFuhOr4WCB8OJ1t8,2568
+ad_api/api/insights.py,sha256=b0m2_khfDGskbvn4sidsUpOvV-gr2bsjUup0kSo8HV8,2398
 ad_api/api/invoices.py,sha256=EwSUVPOTxu1zYPSh0Bg6sCQ22evnUrMJBgU8ZttWN4w,1579
 ad_api/api/localization.py,sha256=HdkChAawloJ8zj5rCye9NVf7kLnQ7vW6aKsBLZ2W-gI,17158
 ad_api/api/manager_accounts.py,sha256=tnmJxOGIKTuJ3i8wciwfs931REW0aeNKQiqCpBrTZ2Y,5107
@@ -108,8 +108,8 @@ ad_api/base/exceptions.py,sha256=9D3M40ZIlLS0fA-aQh1BTWPOW-Nvf0tRhbA85jFnDJ4,438
 ad_api/base/helpers.py,sha256=UK7Q13vZ0mNdF54xzfzoGDn2O_cd2yPrK2X4rOzC41c,2334
 ad_api/base/marketplaces.py,sha256=44lvCcluXNpqTprWQ80e3weSQmQbJoWL-WDSOWVbCyQ,4657
 ad_api/base/utils.py,sha256=_qnCBOvyJTLgaZjJzUWTi38GGLHkQszXELs79133Rb4,5618
-python_amazon_ad_api-1.2.4.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
-python_amazon_ad_api-1.2.4.dist-info/METADATA,sha256=TYwJLNkevDvojJVYRbb8DDtVtTMUC7FjQZqFxXQ60R0,21479
-python_amazon_ad_api-1.2.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_amazon_ad_api-1.2.4.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
-python_amazon_ad_api-1.2.4.dist-info/RECORD,,
+python_amazon_ad_api-1.2.6.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
+python_amazon_ad_api-1.2.6.dist-info/METADATA,sha256=Exh1vIVjTvA9mkFreWZ4j3M8taTveXGf53Ir1luQrl8,21469
+python_amazon_ad_api-1.2.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_amazon_ad_api-1.2.6.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
+python_amazon_ad_api-1.2.6.dist-info/RECORD,,