Brand Metrics API open beta

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

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.

post_report(*args, **kwargs)

Requests a Sponsored Brands report.

Generates the Brand Metrics report in CSV or JSON format. Customize the report by passing a specific categoryNodeTreeName, categoryNodePath, 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.

Request body

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

categoryNodePath (string): [optional] The hierarchical path that leads to a node starting with the root node. If no Category Node Name is passed, then all data available for all brands belonging to the entity are retrieved. example: List [ “Categories”, “Snack Food”, “Granola & Snack Bars” ]]

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). This defines the period of time used to determine the number of shoppers in the metrics computation [ 1m, 1w, 1cm ]. 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

Returns:

ApiResponse

### Example python

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

dictionary = {
    "categoryNodeTreeName": "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=json.dumps(data)
    )

    print(result)

except AdvertisingApiException as error:

    print(error)

### Example results

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

get_report(*args, **kwargs)

Gets a previously requested report specified by identifier.

Keyword Args

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

Returns:

ApiResponse

### 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 to get the location

{
 "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!"
}

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

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

### 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,
        format="csv"
    )

    print(result)

except AdvertisingApiException as error:

    print(error)

### Result of the file downloaded

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