com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'html' is unknown.

Ad Performance API

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.

HTTPS Endpoint

The API is accessed at the following endpoint with HTTPS GET:

https://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 HTTPS headers:

Header Name

Required

Default Value

Example

Description

Accept

Yes

 

 

The desired output format. Possible values are:

  • application/csv — a simple CSV format
  • application/json — JSON format

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" "https://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" "https://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 HTTPS response codes:

HTTPS 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"