Date: Thu, 28 Mar 2024 11:26:45 +0000 (UTC) Message-ID: <1443699553.117.1711625205736@6bed97201f62> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_116_281235378.1711625205736" ------=_Part_116_281235378.1711625205736 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
The CityGrid Ad Performance API generates performance r= eports for developers, providing information on queries, clicks, impression= s, 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 rep= orting website.
Each reporting day is from 9:00 p.m. to 9:00 p.m., Pacific Time. For exa= mple, if a report is requested at noon on Friday for yesterday, the reporti= ng range will be from 9:00 p.m. Wednesday evening through 9:00 p.m. Thursda= y evening.
The Ad Performance API is intended for developers of web and mobile appl= ications who place ads from CityGrid into the= ir applications to earn credit when the advertisement is clicked. The API s= erves as a reporting tool to monitor the performance of such ads.
The API is accessed at the following endpoint with HTTPS GET:
https:/= /api.citygridmedia.com/ads/performance/v2/daily
The supported query parameters are as follows:
Parameter Name |
Required |
Default Value |
Examples |
Description |
---|---|---|---|---|
publisher_code |
No |
|
pub_seo |
Specific publisher code for which to generate report. If no publisher co= de 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 inpu= ts can be specified in the request as separate placement parameters. I= f no placement is specified, all placements are used. |
view_type |
No |
overall |
overall |
Specific view type for which to generate report. |
report_time |
No |
yesterday |
yesterday |
Pre-defined date ranges for the report. If no report_time is specified t= he default is yesterday. |
The service accepts the following HTTPS headers:
Header Name |
Required |
Default Value |
Example |
Description |
---|---|---|---|---|
Accept |
Yes |
|
|
The desired output format. Possible values are:
|
The following are examples of requests:
Type of Call |
Example |
---|---|
Calling from curl with results in CSV |
|
Calling from curl with results in JSON |
|
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<= /p> |
406 Not Acceptable |
The media type requested in the Accept header is not supported |
500 Server Error |
Internal server error |
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 wi= ll 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 wa= s specified in the request, all publisher codes associated with the authent= icated 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 |
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 |
RPM for this date metric. |
ctr |
daily_results |
ads |
CTR for this date metric. |
cpc |
daily_results |
overall |
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 |
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 |
Total RPM for the report period. |
total_ctr |
|
ads |
Total CTR for the report period. |
total_cpc |
|
overall |
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. |
The following is an example response for seven days of reporting data wi= th view_type=3Doverall:
{ "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=3Dads:
{ "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=3DplacesThatPa= y:
{ "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 req= uest 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 }
The following is an example response for seven days of data with view_ty= pe=3Doverall:
"Date R= ecorded","Billable Connections","Revenue(USD)","CPC(USD)","LTC","LTC Revenu= e(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=3Dads:
"Date",= "Impressions","Bidded Impressions","Billable Clicks","Revenue(USD)","RPM(US= D)","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=3DplacesThatPay:
"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 req= uest parameters:
"Date R= ecorded","Billable Connections","Revenue(USD)","CPC(USD)","LTC","LTC Revenu= e(USD)" "Total: ","0","0.0","0.0","0","0.0"