Bidders - Report service

The Report Service offers reporting data of interest to both buyers and sellers. It's used to answer questions such as:

• How much money was spent?
• How many impressions were seen?
• How many impressions were sold?
• How much revenue was earned?

This is a read-only service. Although you will POST a JSON-formatted report request, this will not alter any data in the Imp Bus cache. You must be authenticated as a "bidder" user type to run reports. Each report type provides its own metrics, filtering, and grouping options.

Report types

The primary report types are:

• Bidder Platform Buyer Report
• Platform Seller Report
• Bidder Billing Report API
• Seller Platform Billing Report
• Completed Creative Audits Report
• Bidder Bid Error Report API

REST API for viewing metadata

There are two layers of data in the Report Service - metadata and actual data. Metadata is a list of available reporting parameters.

To run a custom report you will need a JSON-formatted request. You can request data by a filter, group, or column. A filter will filter out results. A request having a filter such as day, will filter based on aggregated data. You can also search by individual parameters, such as imps_sold.

report?meta=report_type

GET https://api.adnxs.com/report?meta=platform_buyer

Metadata comes in the following format:

{"column":"day","type":"time"}
{"column":"month","type":"time"}
{"column":"geo_country","type":"string"}

Metadata example

$ curl "https://api.adnxs.com/report/meta/platform_buyer"
  "response": {
    "status": "OK",
 "meta": {
      "columns": [
        {
          "column": "month",
          "type": "time"
        },
        {
          "column": "day",
          "type": "date"
        },
        {
          "column": "hour",
          "type": "date"
        },
      ...
      ],
      "filters": [
        {
          "column": "hour",
          "type": "date"
        },
        {
          "column": "day",
          "type": "date"
        },
        {
          "column": "year",
          "type": "date"
        },
        ...
      ],
      "havings": [
        {
          "column": "clicks"
        },
        {
          "column": "buyer_spend"
        },
        {
          "column": "imps_bought"
        },
        {
          "column": "buyer_ecpm"
        },
        {
          "column": "click_rate_sold"
        }
      ],
      "time_intervals": [
        "current_hour",
        "last_hour",
        "last_48_hours",
        "today",
        "yesterday",
        "last_7_days",
        "month_to_date",
        "quarter_to_date",
        "last_month",
        "lifetime",
        "mtd"
      ]
    }
}

REST API for data retrieval

JSON fields

How to retrieve a report

• Step 1. Create a JSON-formatted report request
• Step 2. POST the request to the Report Service
• Step 3. GET the report status from the Report Service
• Step 4. GET the report data from the Report Download Service

Step 1. Create a JSON-formatted report request

The JSON file should include the specific report_type that you want to run, as well as the columns (dimensions and metrics) and report_interval ("today", "yesterday", "month_to_date", etc.) that you want to retrieve. You can also include filters for dimensions and define granularity (year, month, day) and specify the format in which the data should be returned. The format options are:

• "csv" - Comma-separated file
• "xls" - Tab-separated M.S. Excel file
• "xlsx" - Native M.S. Excel format

"filters": [{"bid_type": ["learn","optimized"]}, {"geo_country":"US"}]

"filters": [{"bid_type":"learn"}, {"bid_type":"optimized"}, {"geo_country":"US"}]

See JSON Fields above for more details about the fields that can be included in the request. For a full list of available dimensions and metrics, see the documentation for the specific report type that you want to run, or pull that report's metadata as described in REST API for Viewing Metadata.

$ cat report_request
{
    "report": {
        "report_type": "platform_buyer",
        "report_interval": "last_48_hours",
        "columns": ["day","imps_bought"],
        "filters": [{"geo_country":"US"}],
        "orders": [{"order_by":"day", "direction":"ASC"}],
        "format": "csv"
    }
}

Step 2. POST the request to the report service

You POST the JSON request and get back a report ID.

$ curl -b cookies -c cookies -X POST -d @report_request 'https://api.adnxs.com/report?member_id=255'
{
    "response": {
        "status": "OK",
        "report_id": "ca9955709eade9a0e89f5cda5345c12r",
        "dbg_info": {
            ...
        }
    }
}

Step 3. GET the report status from the report service

Make a GET call with the report ID to retrieve the status of the report. Continue making this call until the "execution_status" is "ready". Then use the report-download service to save the reporting data to a file. (This is described in the next step.)

$ curl -b cookies -c cookies 'https://api.adnxs.com/report/ca9955709eade9a0e89f5cda5345c12r'
{
    "response": {
        "status": "OK",
        "report": {
            "name": null,
            "created_on": "2012-03-13 18:15:48",
            "cache_hit": false,
            "fact_cache_hit": false,
            "json_request": "{\"report\":{\"report_type\":\"network_analytics\",\"report_interval\":
                \"last_48_hours\",\"columns\":[\"day\",\"imps\",\"clicks\"],\"filters\":[{\"geo_country\":
                \"US\"},{\"entity_member_id\":\"514\"},{\"entity_member_id\":null}],\"orders\":
                [{\"order_by\":\"day\",\"direction\":\"ASC\"},{\"order_by\":\"imps\",\"direction\":
                \"DESC\"}]}}",
            "header_info": "Report type:,network_analytics\r\n,\r\nRun at:,2012-03-13 18:15:48\r\nStart date:,
                \r\nEnd date:,\r\nTimezone:,\r\nUser:,John Smith (9385)\r\n",
            "report_size": "10",
            "row_count": "35",
            "url": "report-download?id=ca9955709eade9a0e89f5cda5345c12r"
        },
        "execution_status": "ready",
        "dbg_info": {
            ...
        }
    }
}

Step 4. GET the report data from the report download service

To download the report data to a file, make another GET call with the report ID, but this time to the report-download service. You can find the service and report ID in the url field of the previous GET response. When identifying the file that you want to save to, be sure to use the file extension of the "format" that you specified in your initial POST.

$ curl -b cookies -c cookies 'https://api.appnexus.com/report-download?id=<download_id>

You can then open the file.

Schedule recurring reports

You can automate the reporting process by creating saved versions of the reports you care about and having our system email the data to you at specified intervals. For more information about how to set up these automated reports, see the Saved Report Service.

Related topics

• Saved Report Service
• Completed Creative Audits Report
• Bidder Platform Buyer Report
• Bidder Billing Report API
• Platform Seller Report
• Seller Platform Billing Report
• Bidder Bid Error Report API
• Inventory Availability Reporting
• Reporting Timezones