Introduction
The CityGrid Ad Performance API generates performance reports for developers, providing information on queries, clicks, impressions, click-through rates, coverage, revenue, and various additional metrics. Response formats include JSON and CSV. The webservice requires the user to authenticate using the same username and password used to log in to the reporting website.
Each reporting day is from 9:00 p.m. to 9:00 p.m., Pacific Time. For example, if a report is requested at noon on Friday for yesterday, the reporting range will be from 9:00 p.m. Wednesday evening through 9:00 p.m. Thursday evening.
Contents
Audience
The Ad Performance API is intended for developers of web and mobile applications who place ads from CityGrid into their applications to earn credit when the advertisement is clicked. The API serves as a reporting tool to monitor the performance of such ads.
HTTP Endpoint
The API is accessed at the following endpoint with HTTP GET:
http://api.citygridmedia.com/ads/performance/v2/daily
Request
Request Parameters
The supported query parameters are as follows:
| Parameter Name | Required | Default Value | Examples | Description |
|---|---|---|---|---|
| publisher_code | No |
pub_seo 1234567 |
Specific publisher code for which to generate report. If no publisher code is specified, all publisher codes associated with the authenticated user are used. | |
| placement | No | newyork_leaderboard | Specific placement for which to generate report. Multiple placement inputs can be specified in the request as separate placement parameters. If no placement is specified, all placements are used. | |
| view_type | No | overall | overall ads placesThatPay |
Specific view type for which to generate report. |
| report_time | No | yesterday | yesterday last7Days last14Days last30Days lastWeek lastBusinessWeek thisMonth lastMonth last3Months thisQuarter lastQuarter |
Pre-defined date ranges for the report. If no report_time is specified the default is yesterday. |
Request Headers
The service accepts the following HTTP headers:
| Header Name | Required | Default Value | Example | Description |
|---|---|---|---|---|
| Accept | Yes | The desired output format. Possible values are:
|
Usage Examples
The following are examples of requests:
| Type of Call | Example |
|---|---|
| Calling from curl with results in CSV | curl --user "<username>:<password>" --header "Accept: application/csv" "http://api.citygridmedia.com/ads/performance/v2/daily?publisher_code=guest&placement=placement_1&placement=placement_2" |
| Calling from curl with results in JSON | curl --user "<username>:<password>" --header "Accept: application/json" "http://api.citygridmedia.com/ads/performance/v2/daily?publisher_code=guest&report_time=lastWeek&view_type=ads" |
Response
Response Codes
The response may contain one of the following HTTP response codes:
| HTTP Status | Description |
|---|---|
| 200 OK | Success |
| 400 Bad Request | One or more parameters were invalid |
| 401 Unauthorized | The user did not provide a valid username/password |
| 403 Forbidden | The authenticated user does not have access to requested publisher code |
| 406 Not Acceptable | The media type requested in the Accept header is not supported |
| 500 Server Error | Internal server error |
Response Data
If successful, a response body will contain report data in JSON or CSV. The report data contains the following properties:
| Property | Parent | View Type | Description |
|---|---|---|---|
| view_type | Request view type. If no view type was specified in the request, this will default to 'overall'. | ||
| placements | Request placements. If no placements were specified in the request, this will be null. | ||
| from | Start date to which this report applies. | ||
| to | End date to which this report applies. | ||
| publisher_codes | List of publisher codes used to generate report. If no publisher code was specified in the request, all publisher codes associated with the authenticated user are returned. | ||
| daily_results | Element containing daily metric information. | ||
| date | daily_results | Date of this metric. | |
| billable_connections | daily_results | overall | Billable connections for this date metric. |
| impressions | daily_results | ads placesThatPay |
Queries for this date metric. |
| bidded_impressions | daily_results | ads | Ad impressions for this date metric. |
| billable_clicks | daily_results | ads | Ad clicks for this date metric. |
| revenue | daily_results | Revenue for this date metric. | |
| rpm | daily_results | ads placesThatPay |
RPM for this date metric. |
| ctr | daily_results | ads | CTR for this date metric. |
| cpc | daily_results | overall ads |
CPC for this date metric. |
| coverage | daily_results | ads | Coverage for this date metric. |
| ltc | daily_results | LTC clicks for this date metric. | |
| ltc_revenue | daily_results | LTC revenue for this date metric. | |
| total_billable_connections | overall | Sum of billable connections for the report period. | |
| total_impressions | ads placesThatPay |
Sum of queries for the report period. | |
| total_bidded_impressions | ads | Sum of ad impressions for the report period. | |
| total_billable_clicks | ads | Sum of ad clicks for the report period. | |
| total_revenue | Sum of revenue for the report period. | ||
| total_rpm | ads placesThatPay |
Total RPM for the report period. | |
| total_ctr | ads | Total CTR for the report period. | |
| total_cpc | overall ads |
Total CPC for the report period. | |
| total_coverage | ads | Total Coverage for the report period. | |
| total_ltc | Sum of LTC clicks for the report period. | ||
| total_ltc_revenue | Sum of LTC revenue for the report period. |
JSON Response
The following is an example response for seven days of reporting data with view_type=overall:
{
"view_type": "overall",
"placements": null,
"from": "2011-11-15",
"to": "2011-11-21",
"publisher_codes": [
"guest"
],
"daily_results": [
{
"date": "2011-11-15",
"billable_connections": 8,
"revenue": 11.5,
"cpc": 1.44,
"ltc": 2,
"ltc_revenue": 3.25
},
{
"date": "2011-11-16",
"billable_connections": 6,
"revenue": 4.5,
"cpc": 0.75,
"ltc": 7,
"ltc_revenue": 6.0
},
{
"date": "2011-11-17",
"billable_connections": 36,
"revenue": 45.0,
"cpc": 1.25,
"ltc": 2,
"ltc_revenue": 3.0
},
{
"date": "2011-11-18",
"billable_connections": 20,
"revenue": 71.0,
"cpc": 3.55,
"ltc": 7,
"ltc_revenue": 25.0
},
{
"date": "2011-11-19",
"billable_connections": 7,
"revenue": 32.0,
"cpc": 4.57,
"ltc": 1,
"ltc_revenue": 5.0
},
{
"date": "2011-11-20",
"billable_connections": 16,
"revenue": 4.0,
"cpc": 0.25,
"ltc": 8,
"ltc_revenue": 2.0
},
{
"date": "2011-11-21",
"billable_connections": 6,
"revenue": 44.25,
"cpc": 7.38,
"ltc": 6,
"ltc_revenue": 24.75
}
],
"total_billable_connections": 99,
"total_revenue": 212.25,
"total_cpc": 2.14,
"total_ltc": 33,
"total_ltc_revenue": 69.0
}
An example response for view_type=ads:
{
"view_type": "ads",
"placements": [
"placement_1"
],
"from": "2011-11-15",
"to": "2011-11-28",
"publisher_codes": [
"guest"
],
"daily_results": [
{
"date": "2011-11-15",
"impressions": 10,
"bidded_impressions": 5,
"billable_clicks": 2,
"revenue": 3.5,
"rpm": 700.0,
"ctr": 40.0,
"cpc": 1.75,
"coverage": 50.0,
"ltc": 1,
"ltc_revenue": 1.75
},
{
"date": "2011-11-16",
"impressions": 2,
"bidded_impressions": 0,
"billable_clicks": 0,
"revenue": 0.0,
"rpm": 0.0,
"ctr": 0.0,
"cpc": 0.0,
"coverage": 0.0,
"ltc": 0,
"ltc_revenue": 0.0
},
{
"date": "2011-11-17",
"impressions": 12,
"bidded_impressions": 7,
"billable_clicks": 6,
"revenue": 7.5,
"rpm": 1071.43,
"ctr": 85.71,
"cpc": 1.25,
"coverage": 58.33,
"ltc": 0,
"ltc_revenue": 0.0
},
{
"date": "2011-11-18",
"impressions": 7,
"bidded_impressions": 0,
"billable_clicks": 0,
"revenue": 0.0,
"rpm": 0.0,
"ctr": 0.0,
"cpc": 0.0,
"coverage": 0.0,
"ltc": 0,
"ltc_revenue": 0.0
},
{
"date": "2011-11-19",
"impressions": 0,
"bidded_impressions": 0,
"billable_clicks": 0,
"revenue": 0.0,
"rpm": 0.0,
"ctr": 0.0,
"cpc": 0.0,
"coverage": 0.0,
"ltc": 0,
"ltc_revenue": 0.0
},
{
"date": "2011-11-20",
"impressions": 10,
"bidded_impressions": 5,
"billable_clicks": 1,
"revenue": 0.5,
"rpm": 100.0,
"ctr": 20.0,
"cpc": 0.5,
"coverage": 50.0,
"ltc": 1,
"ltc_revenue": 0.5
},
{
"date": "2011-11-21",
"impressions": 15,
"bidded_impressions": 3,
"billable_clicks": 1,
"revenue": 10.0,
"rpm": 3333.33,
"ctr": 33.33,
"cpc": 10.0,
"coverage": 20.0,
"ltc": 0,
"ltc_revenue": 0.0
}
],
"total_impressions": 56,
"total_bidded_impressions": 20,
"total_billable_clicks": 10,
"total_revenue": 21.5,
"total_rpm": 1075.0,
"total_ctr": 50.0,
"total_cpc": 50.0,
"total_coverage": 35.71,
"total_ltc": 2,
"total_ltc_revenue": 2.25
}
An example response for seven days of data with view_type=placesThatPay:
{
"view_type": "placesThatPay",
"placements": null,
"from": "2011-11-15",
"to": "2011-11-21",
"publisher_codes": [
"guest"
],
"daily_results": [
{
"date": "2011-11-15",
"impressions": 6,
"revenue": 8.0,
"rpm": 571.43,
"ltc": 1,
"ltc_revenue": 1.5
},
{
"date": "2011-11-16",
"impressions": 1,
"revenue": 2.0,
"rpm": 200.0,
"ltc": 5,
"ltc_revenue": 5.0
},
{
"date": "2011-11-17",
"impressions": 20,
"revenue": 27.5,
"rpm": 785.71,
"ltc": 2,
"ltc_revenue": 3.0
},
{
"date": "2011-11-18",
"impressions": 16,
"revenue": 61.0,
"rpm": 1196.08,
"ltc": 5,
"ltc_revenue": 20.0
},
{
"date": "2011-11-19",
"impressions": 2,
"revenue": 7.0,
"rpm": 388.89,
"ltc": 0,
"ltc_revenue": 0.0
},
{
"date": "2011-11-20",
"impressions": 10,
"revenue": 1.0,
"rpm": 26.32,
"ltc": 5,
"ltc_revenue": 0.5
},
{
"date": "2011-11-21",
"impressions": 3,
"revenue": 4.25,
"rpm": 303.57,
"ltc": 5,
"ltc_revenue": 9.75
}
],
"total_impressions": 58,
"total_revenue": 110.75,
"total_rpm": 615.28,
"total_ltc": 23,
"total_ltc_revenue": 39.75
}
An example response when there is no data available for the provided request parameters:
{
"view_type": "overall",
"placements": null,
"from": "2011-07-01",
"to": "2011-09-30",
"publisher_codes": [
"guest"
],
"daily_results": [],
"total_billable_connections": 0,
"total_revenue": 0.0,
"total_cpc": 0.0,
"total_ltc": 0,
"total_ltc_revenue": 0.0
}
CSV Response
The following is an example response for seven days of data with view_type=overall:
"Date Recorded","Billable Connections","Revenue(USD)","CPC(USD)","LTC","LTC Revenue(USD)" "2011-11-15","8","11.5","1.44","2","3.25" "2011-11-16","6","4.5","0.75","7","6.0" "2011-11-17","36","45.0","1.25","2","3.0" "2011-11-18","20","71.0","3.55","7","25.0" "2011-11-19","7","32.0","4.57","1","5.0" "2011-11-20","16","4.0","0.25","8","2.0" "2011-11-21","6","44.25","7.38","6","24.75" "Total: ","99","212.25","2.14","33","69.0"
An example response for view_type=ads:
"Date","Impressions","Bidded Impressions","Billable Clicks","Revenue(USD)","RPM(USD)","CTR","CPC(USD)","Coverage(%)","LTC","LTC Revenue(USD)" "2011-11-15","10","5","2","3.5","700.0","40.0","1.75","50.0","1","1.75" "2011-11-16","2","0","0","0.0","0.0","0.0","0.0","0.0","0","0.0" "2011-11-17","12","7","6","7.5","1071.43","85.71","1.25","58.33","0","0.0" "2011-11-18","7","0","0","0.0","0.0","0.0","0.0","0.0","0","0.0" "2011-11-19","0","0","0","0.0","0.0","0.0","0.0","0.0","0","0.0" "2011-11-20","10","5","1","0.5","100.0","20.0","0.5","50.0","1","0.5" "2011-11-21","15","3","1","10.0","3333.33","33.33","10.0","20.0","0","0.0" "Total: ","56","20","10","21.5","1075.0","50.0","50.0","35.71","2","2.25"
An example response for view_type=placesThatPay:
"Date","Impressions","Revenue(USD)","RPM(USD)","LTC","LTC Revenue(USD)" "2011-11-15","6","8.0","571.43","1","1.5" "2011-11-16","1","2.0","200.0","5","5.0" "2011-11-17","20","27.5","785.71","2","3.0" "2011-11-18","16","61.0","1196.08","5","20.0" "2011-11-19","2","7.0","388.89","0","0.0" "2011-11-20","10","1.0","26.32","5","0.5" "2011-11-21","3","4.25","303.57","5","9.75" "Total: ","58","110.75","615.28","23","39.75"
An example response when there is no data available for the provided request parameters:
"Date Recorded","Billable Connections","Revenue(USD)","CPC(USD)","LTC","LTC Revenue(USD)" "Total: ","0","0.0","0.0","0","0.0"