Reports

class ad_api.api.sp.Reports(account='default', marketplace: Marketplaces = Marketplaces.EU, credentials=None, proxies=None, verify=True, timeout=None, debug=False, access_token=None)

Sponsored Products Reports

Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-products/2-0/openapi#/Reports

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.

post_report(self, recordType, **kwargs) → ApiResponse:

Requests a Sponsored Products report.

Request the creation of a performance report for all entities of a single type which have performance data to report. Record types can be one of campaigns, adGroups, keywords, productAds, asins, and targets. Note that for asin reports, the report currently can not include metrics associated with both keywords and targets. If the targetingId value is set in the request, the report filters on targets and does not return sales associated with keywords. If the targetingId value is not set in the request, the report filters on keywords and does not return sales associated with targets. Therefore, the default behavior filters the report on keywords. Also note that if both keywordId and targetingId values are passed, the report filters on targets only and does not return keywords.

Keyword Args: path recordType (integer): The type of entity for which the report should be generated. Available values : campaigns, adGroups, keywords, productAds, asins, targets [required]
Request body: stateFilter (string): [optional] Filters the response to include reports with state set to one of the values in the comma-delimited list. Note that this filter is only valid for reports of the following type and segment. Asins and targets report types are not supported. Enum [ enabled, paused, archived ].

campaignType (list > string): [required] Enum: The type of campaign. Only required for asins report - don’t use with other report types. [sponsoredProducts]

segment (string) Dimension on which the report is segmented. Note that Search-terms report for auto-targeted campaigns created before 11/14/2018 can be accessed from the /v2/sp/keywords/report resource. Search-terms report for auto-targeted campaigns generated on-and-after 11/14/2018 can be accessed from the /v2/sp/targets/report resource. Also, keyword search terms reports only return search terms that have generated at least one click or one sale. Enum [ query, placement ].

reportDate (string): [optional] The date for which to retrieve the performance report in YYYYMMDD format. The time zone is specified by the profile used to request the report. If this date is today, then the performance report may contain partial information. Reports are not available for data older than 60 days. For details on data latency, see the Service Guarantees in the developer notes section.

metrics (string) [optional] A comma-separated list of the metrics to be included in the report. The following tables summarize report metrics which can be requested via the reports interface. Different report types can use different metrics. Note that ASIN reports only return data for either keywords or targets, but not both.
Returns:: ApiResponse

### Example python

from ad_api.api.sp.reports import Reports

file = open("ad_groups.json")
data = file.read()
file.close()

# Available values : campaigns, adGroups, keywords, productAds, asins, targets
record_type = 'adGroups'

result = Reports().post_report(
    recordType=record_type,
    body=data
)

payload = result.payload
report_id = payload.get('reportId')

### Example json

Open this json file to see the result:

{
  "stateFilter": "enabled",
  "reportDate": "20210917",
  "metrics": "campaignName,campaignId,adGroupName,adGroupId,impressions,clicks,attributedConversions30d"
}

get_report(self, reportId, **kwargs) → ApiResponse:

Gets a previously requested report specified by identifier.

Keyword Args: path reportId (number): The report identifier. [required]
Returns:: ApiResponse

### Example python

from ad_api.api.sp.reports import Reports

# this report_id is obtained from post_report method
report_id = 'amzn1.clicksAPI.v1.p44551.61549C5E.e4599469-7392-4624-a858-fc1fecdb165c'

result = Reports().get_report(
    reportId=report_id
)

### Result json

{
    "expiration": 1640736000000,
    "fileSize": 6546,
    "location": "https://advertising-api-eu.amazon.com/v1/reports/amzn1.clicksAPI.v1.p44551.61549C5E.e4599469-7392-4624-a858-fc1fecdb165c/download",
    "reportId": "amzn1.clicksAPI.v1.p44551.61549C5E.e4599469-7392-4624-a858-fc1fecdb165c",
    "status": "SUCCESS",
    "statusDetails": "Report has been successfully generated."
}

download_report(self, **kwargs) → ApiResponse:

Downloads the report previously get report specified by location (this is not part of the official Amazon Advertising API, is a helper method to download the report). Take in mind that a direct download of location returned in get_report will return 401 - Unauthorized.

kwarg parameter file if not provided will take the default amazon name from path download (add a path with slash / if you want a specific folder, do not add extension as the return will provide the right extension based on format choosed if needed)

kwarg parameter format if not provided a format will return a url to download the report (this url has a expiration time)

Keyword Args: url (string): The location obatined from get_report [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 report: data (list), raw, url, json, zip, gzip. Default (url) [optional]
Returns:: ApiResponse

Warning

This method is not a part of the Amazon Advertising Api.

### Example python

from ad_api.api.sp.reports import Reports

# the url=location is obtained from get_report method need to in stay 'status': 'SUCCESS' if is 'IN_PROGRESS' the report cannot be downloaded
location = 'https://advertising-api-eu.amazon.com/v1/reports/amzn1.clicksAPI.v1.p44551.61549C5E.e4599469-7392-4624-a858-fc1fecdb165c/download'

# path = '/Users/your-profile/Downloads/report_name'
# mode = "data"  # "data (list), raw, url, json, zip, gzip default is url"

result = Reports().download_report(
    url=location,
    # file=path,
    # format=mode
)

Tip

Just provide the url keyword arg with the location and you will get a response with the url ready to download