Brand Metrics API open beta

Current contract:

https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/BrandMetrics_prod_3p.json

Previously, Amazon served the same specification from a different host:

https://dtrnk0o2zy01c.cloudfront.net/openapi/en-us/dest/BrandMetrics_prod_3p.json

class ad_api.api.BrandMetrics(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)

Brand Metrics provides a new measurement solution that quantifies opportunities for your brand at each stage of the customer journey on Amazon, and helps brands understand the value of different shopping engagements that impact stages of that journey. You can now access Awareness and Consideration indices that compare your performance to peers using models predictive of consideration and sales. Brand Metrics quantifies the number of customers in the awareness and consideration marketing funnel stages and is built at scale to measure all shopping engagements with your brand on Amazon, not just ad-attributed engagements. Additionally, BM breaks out key shopping engagements at each stage of the shopping journey, along with the Return on Engagement, so you can measure the historical sales following a consideration event or purchase.

### Example python

from ad_api.api import BrandMetrics
from ad_api.base import AdvertisingApiException

dictionary = {
    "categoryTreeName": "es-automotive",
    "brandName": "BMW",
    "reportStartDate": "2022-03-01",
    "lookBackPeriod": "1W",
    "format": "CSV",
    "metrics": [
        "engagedShopperRateLowerBound",
        "customerConversionRate",
        "newToBrandCustomerRate"
    ],
    "reportEndDate": "2022-03-05"
}

try:

    result = BrandMetrics(account=store, marketplace=marketplace, debug=True).post_report(
        body=dictionary
    )

    print(result)

except AdvertisingApiException as error:

    print(error)

### Example results

The answer is a handle, not the report: it carries a reportId and status: IN_PROGRESS, and the file has to be collected later.

{
    "expiration": 300000,
     "format": "CSV",
     "location": "",
     "reportId": "820882fa-ff22-4772-99e1-6889e3ae97f8",
     "status": "IN_PROGRESS",
     "statusDetails": "Generation of the report is in progress!"
}

### Example python

from ad_api.api import BrandMetrics
from ad_api.base import Marketplaces, AdvertisingApiException

report_id = "820882fa-ff22-4772-99e1-6889e3ae97f8"

try:

    result = BrandMetrics(account=store, marketplace=marketplace, debug=True).get_report(
        reportId=report_id
    )

    print(result)

except AdvertisingApiException as error:

    print(error)

### Result once the report is ready

Poll the same reportId until status reads SUCCESSFUL; only then does location carry the signed address.

{
 "brandsInfo":
 [
   {
      "id": "BRAND|BRAND_AID|34cf8a28-77f0-44dd-kl98-c419a6203257",
      "name": "BMW"
   }
 ],
  "expiration": 300000,
  "format": "CSV",
  "location": "https://infrastack-prod-eu-eu-we-generatedreportsbucket49-96329mbigajd.s3.eu-west-1.amazonaws.com/[...]/[...]",
  "reportId": "820882fa-ff22-4772-99e1-6889e3ae97f8",
  "status": "SUCCESSFUL",
  "statusDetails": "Generation of the report was successful!"
}

### Example python

from ad_api.api import BrandMetrics
from ad_api.base import Marketplaces, AdvertisingApiException

location = "https://infrastack-prod-eu-eu-we-generatedreportsbucket49-96329mbigajd.s3.eu-west-1.amazonaws.com/[...]"

try:

    result = BrandMetrics(account=store, marketplace=marketplace, debug=True).download_report(
        url=location,
        file="report",
        format="csv"
    )

    print(result)

except AdvertisingApiException as error:

    print(error)

Without file the call returns the Amazon file name instead of writing a file, and the format argument only decides the extension: the bytes stay in whichever format the report was generated in.

### Result of the file downloaded

{
 "headers":{},
 "next_token": None,
 "payload": "A1RLL123456789-820882fa-ff22-4772-99e1-6889e3ae97f8.csv"
}

post_report(**kwargs) → ApiResponse

Requests a Brand Metrics report.

Asks the service to generate the report; the answer is a handle, not the data. It carries a reportId, a status and an empty location, and the report is produced asynchronously. Pass the reportId to get_report() until status reads SUCCESSFUL, then download location.

Generates the Brand Metrics report in CSV or JSON format. Customize the report by passing a specific categoryTreeName, categoryPath, brandName, reportStartDate, reportEndDate, lookBackPeriod, format or a list of metrics from the available metrics in the metrics field. If an empty request body is passed, report for the latest available report date in JSON format will get generated with all the available brands and metrics for an advertiser. The report may or may not contain the Brand Metrics data for one or more brands depending on data availability.

Every field is optional. An empty body generates the latest available report in JSON with every brand and metric on the account.

Request body

categoryTreeName (string): [optional] The node at the top of a browse tree. It is the start node of a tree. example: us-home

categoryPath (array of arrays): [optional] The hierarchical path that leads to a node starting with the root node, as a list of paths where each path is a list of levels. If no category path is passed, then all data available for all brands belonging to the entity are retrieved. example: [ [“Categories”, “Granola & Snack Bars”, “Snack Food”] ]

brandName (string): [optional] Brand Name. If no Brand Name is passed, then all data available for all brands belonging to the entity are retrieved. example: Mattress Mogul

reportStartDate (string($date)): [optional] Retrieves metrics with metricsComputationDate between reportStartDate and reportEndDate (inclusive). The date will be in the Coordinated Universal Time (UTC) timezone in YYYY-MM-DD format. If no date is passed in reportStartDate, all available metrics with metricsComputationDate till the reportEndDate will be provided. If no date is passed for either reportStartDate or reportEndDate, the metrics with the most receont metricsComputationDate will be returned. example: 2021-01-01

lookBackPeriod (string) [optional] Currently supported values: “1W” (one week), “1M” (one month) and “1CM” (one calendar month), which is the enum the v1 contract declares; the v1.1 contract declares the lower case forms and the service accepted both. This defines the period of time used to determine the number of shoppers in the metrics computation. default: 1w

format (string) [optional] Format of the report. [ JSON, CSV ]. default: JSON

metrics (list) [optional] Specify an array of string of metrics field names to include in the report. If no metric field names are specified, all metrics are returned.

reportEndDate (string($date)) [optional] Retrieves metrics with metricsComputationDate between reportStartDate and reportEndDate (inclusive). The date will be in the Coordinated Universal Time (UTC) timezone in YYYY-MM-DD format. If no date is passed in reportEndDate, all available metrics with metricsComputationDate from the reportStartDate will be provided. If no date is passed for either reportStartDate or reportEndDate, the metrics with the most receont metricsComputationDate will be returned. example: 2021-01-30

The contract names the two category fields categoryTreeName and categoryPath, while the answers come back carrying categoryNodeTreeName and categoryNodeName. Neither spelling filters: both were sent with different values, and a tree name that does not exist (zz-no-existe-zz) was answered with the account’s full set exactly like a real one. Send the contract names, but do not expect them to narrow the report – filter on brandName and the date range instead, which are the fields the service was seen to honour.

Returns:

• reportId (string): the handle for get_report().

• status (string): IN_PROGRESS on a fresh request.

• statusDetails (string): a sentence describing that status.

• expiration (integer): how long the result stays available.

• format (string): echoes the requested format.

• location (string): empty until the report is ready.

Return type:

ApiResponse. payload holds

Example:

from ad_api.api import BrandMetrics

bm = BrandMetrics(account="my_account")
bm.post_report(body={"format": "JSON", "lookBackPeriod": "1w"}).payload
# {'reportId': '8d3e7143-...', 'status': 'IN_PROGRESS',
#  'statusDetails': 'Generation of the report is in progress!',
#  'expiration': 300000, 'format': 'JSON', 'location': ''}

get_report(reportId, **kwargs) → ApiResponse

Gets a previously requested report specified by identifier.

This is the polling call. A report is generated asynchronously, so call this with the reportId that post_report() returned until status reads SUCCESSFUL; only then does location carry a signed S3 address that can be downloaded.

Keyword Args

path reportId (string): [required] The report Id to be fetched.

Returns:

• status (string): IN_PROGRESS, SUCCESSFUL or a failure status.

• statusDetails (string): the sentence behind that status.

• location (string): the signed URL, empty until success.

• format (string): the format the report was generated in.

• expiration (integer): how long the result stays available.

• brandsInfo (array): the brands the report covers, each with id and name. Absent while the report is still running.

Return type:

ApiResponse. payload holds

An unknown identifier is not a 404: the service answers 400 with NoDataFoundException and a message naming the id, which means the route ran and looked it up.

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

In this API the url is self-authorized so to avoid double authorization we pass a simple header to ovrewrite the API auth headers that will lead to an error.

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: raw, url, json, csv, Default (url)

Returns:

ApiResponse