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.

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"