dimensions not returned by AppNexus API

Question

I'm trying to setup an integration with the AppNexus reporting API, ran into problems, and wonder if anyone in the StackOverflow community has some insight to share.

The AppNexus API has a walk-though using curl and it sort-of works, except that the groups/dimensions don't get returned. Here's what I did:

There's a file called auth containing our credentials:

# JSON file containing our credentials
$ cat auth
{
    "auth": {
        "username" : "ourAppNexusApiUsername",
        "password" : "ourSecretApiUserPassword"
    }
}

There's also a JSON file containing a query. Note the dimensions in the "columns" list:

# The query itself, in JSON format. 
$ cat query.json 
{
    "report": {
        "format": "csv",
        "report_interval": "yesterday",
        "groups": [
            "publisher_id",
            "imp_type",
            "geo_country",
            "placement_id"
        ],
        "columns": [
            "imps_total",
            "imps_kept",
            "imps_resold",
            "publisher_filled_revenue",
            "total_convs"
        ],
        "report_type": "publisher_analytics"
    }
}

I'm able to authenticate:

$ curl -b cookies -c cookies -X POST -d @auth 'https://api.appnexus.com/auth'

{"response":{"status":"OK","token":"hbapi:133820:5571c87753c27:nym2","dbg_info":{"instance":"56.bm-hbapi.prod.lax1","slave_hit":false,"db":"master","parent_dbg_info":{"instance":"63.bm-hbapi.prod.nym2","slave_hit":false,"db":"master","parent_dbg_info":{"instance":"38.bm-api.prod.nym2","slave_hit":false,"db":"master","time":482.32913017273,"version":"1.15.279","warnings":[],"slave_lag":0,"start_microtime":1433520246.311},"awesomesauce_cache_used":false,"count_cache_used":false,"warnings":[],"time":1078.0298709869,"start_microtime":1433520246.2796,"version":"1.15.527","slave_lag":0,"output_term":"not_found"},"awesomesauce_cache_used":false,"count_cache_used":false,"warnings":[],"time":1360.9290122986,"start_microtime":1433520246.1491,"version":"1.15.527","slave_lag":1,"output_term":"not_found","master_instance":"63.bm-hbapi.prod.nym2","proxy":true,"master_time":1078.0298709869}}}

I can request a report for a given publisher. It returns a report_id: 72734c3a2df81522c7bae6684cfdd65c

$ curl -b cookies -c cookies -X POST -d @query.json 'http://api.appnexus.com/report?publisher_id=510332'

{"response":{"status":"OK","report_id":"72734c3a2df81522c7bae6684cfdd65c","existing":false,"cached":true,"dbg_info":{"instance":"58.bm-hbapi.prod.lax1","slave_hit":false,"db":"master","reads":0,"read_limit":100,"read_limit_seconds":60,"writes":1,"write_limit":60,"write_limit_seconds":60,"parent_dbg_info":{"instance":"61.bm-hbapi.prod.nym2","slave_hit":false,"db":"master","reads":0,"read_limit":100,"read_limit_seconds":60,"writes":1,"write_limit":60,"write_limit_seconds":60,"awesomesauce_cache_used":false,"count_cache_used":false,"warnings":[],"time":264.3940448761,"start_microtime":1433520268.8354,"version":"1.15.527","output_term":"not_found","reporting_dbg_info":{"instance":"11.bm-report-processor.prod.nym2","version":"1.72.130","time":1094.5529937744,"start_microtime":1433520268,"warnings":[],"api_cache_hit":"0","output_term":null}},"awesomesauce_cache_used":false,"count_cache_used":false,"warnings":[],"time":1238.8980388641,"start_microtime":1433520267.9206,"version":"1.15.527","output_term":"not_found","master_instance":"61.bm-hbapi.prod.nym2","proxy":true,"master_time":264.3940448761}}}

I'm able to download the report but, sadly, the report groups are missing:

$ curl -b cookies -c cookies 'http://api.appnexus.com/report-download?id=72734c3a2df81522c7bae6684cfdd65c'

imps_total,imps_kept,imps_resold,publisher_filled_revenue,total_convs
65086432,0,42898432,1234.776809,4

I imagine that I'm not the first person to encounter this. Anyone have any thoughts/suggestions?

Edit:

I uploaded a quick & dirty Python script to a Github repo to make it easier to test.

Also, AppNexus responded, via email:

It looks like you got your hands on some documentation for mobile reporting, rather than for our standard publisher analytics report. You should change "groups" to "row_per" like this:"

{
    "report": {
        "format": "csv",
        "report_interval": "yesterday",
        "row_per": [
            "hour"
        ],
        "columns": [
            "imps_total"
        ],
        "report_type": "publisher_analytics"
    }
}

I tried this, but it didn't work.

Answer 1

The AppNexus console (Appnexus' web-UI) uses the same API to provide content.

If you're able to produce the output you're looking for by running a report, you can reverse engineer the API calls by clicking on the 'OPEN API VIEWER' at the bottom of the screen. That'll show you the API parameters used to create the report.

Answer 2

AppNexus tech writer here (months later!). I'm pretty sure the example reporting API call on that page was wrong (and I've just fixed it – you can check it out here).

My understanding after testing the reporting API calls out is that:

1. The "bad" example from the docs doesn't work (as you said – now fixed)
2. You do get grouping behavior as long as you are grouping data (using "row_per") that you explicitly asked for (using "columns").

In other words, you must ask for data fields in "columns" and then group them (or more likely a subset) using "row_per". Here's the example I used in the updated docs:

{
    "report": {
        "report_type": "publisher_analytics",
        "report_interval": "yesterday",
        "columns": [
            "geo_country",
            "imp_type",
            "placement",
            "clicks",
            "total_convs",
            "publisher_revenue"
        ],
        "groups": [
            "geo_country",
            "imp_type",
            "placement",
        "imps_total"
        ],
        "name": "Publisher Analytics - 10/30/2015"
    }
}

I used quotes around "bad" above because I'm not sure if it's a bug in our API or the expected behavior - I'm trying to find that out with our engineering team now, but it's Friday afternoon, so I may have to check in again later.

In any case, I've updated the example on the page to reflect the actual behavior as tested for the time being.

Two more things:

1. That page is for our regular publisher analytics report. It's not mobile-specific, we just published it there too so it'd be available externally for some of our customers' customers. Sorry for the confusion!

2. According to my testing this afternoon, "row_per" and "groups" both work, and exhibit the same behavior.

I'm probably too late to help you out, but hopefully this is useful to someone!