Reports

Note

These endpoints keep the historical /v2/ path prefix but are part of the Sponsored Brands 3.0 documentation (see Amazon’s Reports tag). The path prefix does not indicate the API generation: Sponsored Brands mixes /sb/..., /v2/hsa/... and /v2/reports/... under the same version, and all of them answer.

Do not delete anything here based on the prefix alone. Only 404 with “Could not find resource for full path” proves a route is gone; a 404 that names a missing identifier means the route is alive.

Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi

Specification: https://d3a0d0y2hgofx6.cloudfront.net/openapi/en-us/sponsored-brands/3-0/openapi.yaml

class ad_api.api.sb.Reports(account: str = 'default', marketplace: Marketplaces = Marketplaces.EU, credentials: Dict[str, str] | None = None, proxies: Dict[str, str] | None = None, verify: bool = True, timeout: int | None = None, debug: bool = False, access_token: str | None = None, verify_additional_credentials: bool = True)

Sponsored Brand Reports

Documentation: https://advertising.amazon.com/API/docs/en-us/reference/sponsored-brands/2/reports

### Example python

from ad_api.api.sb.reports import Reports

with open("campaigns.json", "r", encoding="utf-8") as f:
    data = f.read()

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

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:

{
  "segment": "placement",
  "reportDate": "20211101",
  "metrics": "campaignName,campaignId,campaignStatus,campaignBudget,campaignBudgetType,campaignRuleBasedBudget"
}

### Example python

from ad_api.api.sb.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.'}}

### Example python

from ad_api.api.sb.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
)

classmethod _accept(): Response media type the v3 contract declares for these routes.

post_report(recordType, **kwargs) → ApiResponse

Requests a Sponsored Brands 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: campaigns, adGroups, and keywords.

Keyword Args: path recordType (string): The type of entity for which the report should be generated. Supported record types: campaigns, adGroups, and keywords
Request body: segment (string): [required] Dimension on which to segment the report. Available values : placement, query

reportDate (string): [required] 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.

metrics (string) [optional] A comma-separated list of the metrics to be included in the report.

creativeType (string) [optional] Set to video to request a Sponsored Brands video report.

Returns:: ApiResponse

get_report(reportId, **kwargs) → ApiResponse

Gets a previously requested report specified by identifier.

Keyword Args: path reportId (string): [required] The report identifier.
Request body: creativeType (string): [optional] Set to video to retrieve a Sponsored Brands video report.

Returns:: ApiResponse

download_report(**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): [required] The location obatined from get_report.

file (string): [optional] The path to save the file if mode is download json, zip or gzip.

format (string): [optional] The mode to download the report: data (list), raw, url, json, zip, gzip. Default (url)

Returns:: ApiResponse