Network Carrier Analytics Report

 

The Network Carrier Analytics report enables you to retrieve buy-side and sell-side performance data based on carriers for devices. This is especially helpful for analyzing how carriers affect campaign performance and advertiser payment. Also, in cases where advertisers set up specific landing pages for each carrier, this report helps you identify the carriers that campaigns ran on.

For instructions on requesting and retrieving this report, see the Example below.

Time Frame and Time Zone

This report can retrieve data for the last 45 days and only in the UTC timezone. The report_interval field in the JSON request can be set to one of the following:

Alternately, the start_date and end_date fields can be set to a range within the last 14 days. However, since hourly data is not available for this report, the start_date and end_date cannot be identical and must be formatted as "YYYY-MM-DD" rather than "YYYY-MM-DD HH:MM:SS". The timezone field in the JSON request can be set only to "UTC", but this is not necessary, as the timezone defaults to "UTC" if not specified.

Dimensions

Column

Type

Filter?

Example

Description

month

time

Yes

"2010-02"

The month of the auction.

day

time

Yes

"2010-02-01"

The day of the auction.

carrier_id

int

Yes

20

The ID of the carrier for the device on which the impression was served. To retrieve a complete list of carrier IDs and names, use the Carrier Service.

carrier_name

string

No

"Sprint - FR"

The name of the carrier for the device on which the impression was served.

carrier

string

No

"Sprint - FR (20)"

Deprecated.

device_type

string

Yes

"tablets"

The type of device on which the impression was served. Possible values are:

  • "desktops & laptops"
  • "tablets"
  • "mobile phones"
  • "tv"
  • "game consoles"
  • "set top box"
  • "media players"
  • "other devices"

connection_type

string

Yes

"Carrier-based"

The type of internet connection at the time of the impression. Possible values: "Carrier-based" or "Wifi or Static".

entity_member_id

int

Yes

123

If imp_type is 1 (Blank), 2 (PSA), 3 (Default Error), 4 (Default), 6 (Resold), or 8 (PSA Resulting from Default Error), the ID of the buying member; otherwise, the ID of the selling member.

buyer_member_id

int

Yes

123

The ID of the buying member. If the impression was not purchased, this field shows one of the following values: 229 = PSA, 0 = Blank, or 319 = Default.

buyer_member_name

string

No

"My Network"

The name of the buying member.

buyer_member

string

No

"My Network (123)"

Deprecated.

seller_member_id

int

Yes

456

The ID of the selling member.

seller_member_name

string

No

"That Seller"

The name of the selling member.

seller_member

string

No

"That Seller (456)"

Deprecated.

buyer_type

string

Yes

"Real Time"

The type of media purchased by the buyer member. Possible values: "Real Time" or "Direct".

seller_type

string

Yes

"Real Time"

The type of media sold by the seller member. Possible values: "Real Time" or "Direct".

advertiser_id

int

Yes

789

The ID of the advertiser. If the value is 0, either the impression was purchased by an external buyer or a default or PSA was shown.

advertiser_name

string

No

"Mobile Zombies"

The name of the advertiser.

advertiser

string

No

"Mobile Zombies (789)"

Deprecated.

advertiser_code

string

No

"MZB1010"

The custom code for the advertiser.

insertion_order_id

int

Yes

321

The ID of the insertion order.

insertion_order_name

string

No

"Mobile Insertion Order"

The name of the insertion order.

insertion_order

string

No

"Mobile Insertion Order (321)"

Deprecated.

insertion_order_code

string

No

"Mobile Insertion Order Code"

The custom code for the insertion order.

line_item_id

int

Yes

111

The ID of the line item.

line_item_name

string

No

"Mobile Line Item"

The name of the line item.

line_item

string

No

"Mobile Line Item (111)"

Deprecated.

line_item_code

string

No

"Mobile Line Item Code"

The custom code for the line item.

campaign_id

int

Yes

222

The ID of the campaign.

campaign_name

string

No

"Mobile Campaign"

The name of the campaign.

campaign

string

No

"Mobile Campaign (222)"

Deprecated.

campaign_code

string

No

"Mobile Campaign Code"

The custom code for the campaign.

split_idintYes342The ID of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_id (if included) will be null.
split_namestringYes"Mobile Split 2"The name of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_name (if included) will be null.

pixel_id

int

Yes

3849

The ID of the conversion pixel.

media_type

string

Yes

"Banner"

The media type of the creative. Possible values: "Banner", "Pop", "Interstitial", "Video", "Text", "Expandable", or "Skin". To retrieve a complete list of media types, use the Media Type Service.

mediatype_id

int

Yes

1

The ID of the media type of the creative.

size

string

Yes

"728x90"

The size of the placement/creative served.

geo_country

string

Yes

"US"

The code for the country.

geo_country_name

string

No

"United States"

The name of the country.

payment_type

string

Yes

"com", "revshare"

The type of payment to a broker.

revenue_type

string

No

"CPA"

The basis on which the advertiser pays the member.

revenue_type_id

int

Yes

4

The ID of the revenue type. Possible values: -1 = No Payment, 0 = Flat CPM, 1 = Cost Plus CPM, 2 = Cost Plus Margin, 3 = CPC, 4 = CPA, 5 = Revshare, or 6 = Flat Fee, 7 = Variable CPM, 8 = Estimated CPM.

publisher

string

Yes

"AppSite (123)"

Deprecated.

publisher_code

string

No

"Publisher Code"

The custom code for the publisher.

pub_rule_name

string

No

"Publisher Rule Name"

The name of the publisher rule.

pub_rule

string

No

"Publisher Rule Name (555)"

Deprecated.

pub_rule_code

string

No

"AppSitePR123"

The custom code for the publisher rule.

bid_type

string

Yes

"Manual"

The optimization phase the node was in when it bid for the impression. Note that the term "give up" is appended to the bid types below if the valuation for that impression falls below the venue's "give up price". For more information, see "What is a Venue" and "Give Up Price" in the UI documentation.

Allowed values:

  • "Manual": Applies when you are bidding with a CPM goal, whether it's Base, EAP, or ECP.
  • "Learn": Applies when you are bidding with optimization (CPA, CPC, or margin) and we do not yet have enough data to bid optimized.
  • "Optimized": Applies when you are bidding with optimization (CPA, CPC, or margin) and we have enough data to bid optimized.
  • "Unknown": The node was in an unknown optimization phase.
  • "Optimized give up"
  • "Learn give up"
  • "Manual give up"

imp_type_id

int

Yes

6

imp_type

string

Yes

"Resold"

The type of impression. For possible values, see imp_type_id.

venue

string

Yes

"Venue Name"

The name of the cluster of domain, site, tag, and user country that Xandr's' optimization system uses to determine bid valuations. A campaign cannot targeted a venue explicitly.

Metrics

Column

Type

Example

Formula

Description

imps

int

2340

imps

The total number of impressions (served and resold).

imps_blank

int

3

imps_blank

The number of impressions served with a blank.

imps_psa

int

5

imps_psa

The number of impressions that served a PSA.

imps_default_error

int

0

imps_default_error

The number of impressions that defaulted due to a timeout issue.

imps_default_bidder

int

0

imps_default_bidder

The number of impressions that defaulted because there were no valid bids.

imps_kept

int

0

imps_kept

The number of impressions your advertiser purchased from your publisher .

imps_resold

int

0

imps_resold

The number of impressions your publisher sold to a third party .

imps_rtb

int

2332

imps_rtb

The number of impressions your advertiser bought from a third party .

clicks

int

1

clicks

The total number of clicks across all impressions.

click_thru_pct

double

1.12359550561797%

(clicks / imps) x 100

The rate of clicks to impressions as a percentage.

ctr

double

0.000221877080097626

clicks / imps

The rate of clicks to impressions.

total_convs

int

1

total_convs

The total number of post-view and post-click conversions.

post_view_convs

int

15

post_view_convs

The total number of recorded post-view conversions.

post_click_convs

int

15

post_click_convs

The total number of recorded post-click conversions.

convs_per_mm

double

221.877080097625

(total_convs / imps) x 1,000,000

The number of conversions per million impressions.

convs_rate

double

0.000221877080097626

total_convs / imps

The rate of conversions to impressions.

cost

money

16.833378

cost

The total amount of media cost for direct publisher and purchased third-party inventory.

cpm

money

1.66051685393258

(cost / imps) x 1000

The media cost per 1000 impressions.

revenue

money

25.767257

booked_revenue + reseller_revenue

The total revenue booked through direct advertisers (line item) and direct publishers (resold impressions).

booked_revenue

money

25.767257

booked_revenue

The total revenue booked through direct advertisers (line item).

reseller_revenue

money

0

reseller_revenue

The total revenue on resold impressions through direct publishers.

rpm

money

2.60548314606741

(revenue / imps) x 1000

The revenue per 1000 impressions.

profit

money

0.084102

During the breaking change period: revenue - cost
After the breaking change period: booked_revenue - total_cost

During the breaking change period: The total network revenue minus network cost.
After the breaking change period: Booked revenue minus total cost.

ppm

money

0.944966292134831

(profit / imps) x 1000

To be deprecated. The profit per 1000 impressions.

total_publisher_rpm

money

1.66051685393258

(cost / imps) x 1000

The cost per 1000 impressions paid to direct and third-party publishers, including errors.

sold_publisher_rpm

double

147.786

(cost / imps) x 1000 ----- no errors

The cost per 1000 impressions paid to direct and third-party publishers, not including errors.

sold_network_rpm

double

231.888

(revenue / imps) x 1000 ----- no errors

The revenue per 1000 impressions that were not errors.

total_costmoney123.45

total_cost = media_cost + data_costs + partner_fees + commissions + serving_fees + publisher_revenue


The total amount of costs accrued over the reported period of time. This generally includes two types of costs, budgeted costs (media cost, data cost, partner fees, serving fees, commissions) and publisher revenue if you track publisher payouts on the platform.

Note: We have added logic to prevent double counting third-party fees during the breaking change period.

total_cost_ecpmmoney123.45(total_cost/imps) * 1,000 The total cost per 1,000 imps.
total_cost_ecpcmoney123.45total_cost/clicks The total cost per click.
total_cost_ecpamoney123.45total_cost/conversions The total cost per conversion.
network_profitmoney123.45(booked_revenue + reseller_revenue) - total_cost The sum of booked revenue and reseller revenue minus total cost.
network_profit_ecpmmoney123.45(network_profit/imps) * 1,000 Network profit per 1,000 imps.
network_profit_ecpcmoney123.45network_profit/clicks Network profit per click.
network_profit_ecpamoney123.45network_profit/conversions Network profit per conversion.
network_profit_marginmoney123.45network_profit/(booked_revenue + reseller_revenue) Network profit margin.
profit_ecpmmoney123.45

((booked_revenue - total_cost)/imps) * 1,000

 Profit per 1,000 imps.

profit_ecpcmoney123.45

(booked_revenue - total_cost)/clicks

 Profit per click.

profit_ecpamoney123.45

(booked_revenue - total_cost)/conversions

 Profit per conversion.

profit_marginmoney123.45

(booked_revenue - total_cost)/booked_revenue

 Buyer profit margin.

Example

1. Create the JSON-formatted report request
The JSON file should include the {{report_type}} "network_carrier_analytics", as well as the {{columns}} (dimensions and metrics) and {{report_interval}} that you want to retrieve. You can also filters for specific dimensions, define granularity (year, month, day), and specify the format in which the data should be returned (csv, excel, or html). For a full explanation of fields that can be included in the JSON file, see the [Report Service|https://wiki.appnexus.com/display/api/Report+Service#ReportService-RESTAPIforDataRetrieval].

In this example, we want to see how campaigns are performing on mobile phones and tablets across three specific carriers. Specifically, for each combination of carrier and device type, we want the number of impressions, the number of clicks, the total money spent, the money spent per 1000 impressions, the money paid to us by the advertiser, and the total profit (money earned - money spent).

{code}$ cat network_carrier_analytics

{
    "report": {
        "report_type": "network_carrier_analytics",
        "filters": [
            {
                "carrier_id": [
                    345,
                    567,
                    837
                ]
            },
            {
                "device_type": [
                    "mobile phones",
                    "tablets"
                ]
            }
        ],
        "columns": [
            "day",
            "carrier_id",
            "device_type",
            "imp_type",
            "imps",
            "clicks",
            "cost",
            "cpm",
            "booked_revenue",
            "profit"
        ],
        "report_interval": "last_14_days",
        "format": "csv"
    }
}{code}
2. POST the request to the Report Service
POST the JSON request to get back a Report ID.

{code}$ curl -b cookies -c cookies -X POST -d @network_carrier_analytics 'https://api.appnexus.com/report'
{
   "response":{
      "status":"OK",
      "report_id":"097f59fc3ab7d02c5d60db42081d9b69"
   }
}
{code}
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 GET call until the {{execution_status}} is "ready". Then use the *report-download* service to save the report data to a file, as described in the next step.

{code}$ curl -b cookies -c cookies 'https://api.appnexus.com/report?id=097f59fc3ab7d02c5d60db42081d9b69'
{
   "response":{
      "status":"OK",
      "report":{
         "name":null,
         "created_on":"2013-02-01 12:19:53",
            "json_request": "{\"report\":{\"report_type\":\"network_carrier_analytics\",\"filters\":[{\"advertiser_id\":1459},
             {\"geo_country\":\"US\"}],\"columns\":[\"day\",\"carrier_id\",\"device_make\",\"device_model\",\"connection_type\",
             \"imp_type\",\"imps\",\"clicks\",\"cost\",\"cpm\",\"booked_revenue\",\"profit\"],\"format\":\"csv\"]}}",
         "url": "report-download?id=097f59fc3ab7d02c5d60db42081d9b69"
      },
      "execution_status":"ready"
   }
}
{code}
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.

{tip}If an error occurs during download, the response header will include an HTTP error code and message. Use \-i or \-v in your call to expose the response header.{tip}

{code}$ curl -b cookies -c cookies 'https://api.appnexus.com/report-download?id=097f59fc3ab7d02c5d60db42081d9b69' > /tmp/network_carrier_analytics.csv
{code}

Related Topics