CityGrid Advertising APIs
Place Performance Reporting API
- Former user (Deleted)
- Former user (Deleted)
This documentation describes V3 of the place performance reporting API. Click here to see V2 of the place performance reporting API.
Introduction
The CityGrid Place Performance Reporting API is part of the Advertising API suite and generates advertiser performance reports by place in JSON format. The API provides two endpoints. The Daily Place Performance endpoint returns reports by place on connections, spending, and campaign information. It accepts HTTPS POST at:
The Performance API user action summary report is accessed via HTTPS POST at this endpoint:
The endpoints allows each call to retrieve a maximum of 500 reports per request.
By default the placeperformance report is generated for the most recent 24-hour period from 9:00 p.m. to 9:00 p.m., Pacific Time. For example, if a report is requested at noon on Friday, the reporting range will be from 9:00 p.m. Wednesday evening through 9:00 p.m. Thursday evening.
Request Parameters
Parameter | Description | Required | Type | Default | Example | Notes |
|---|---|---|---|---|---|---|
| Your own ID(s) identifying the place for which to generate report. | Yes, alternately we can use | String | N/A | camp_123 or abc123, def123 |
|
| Place ID(s) for which to generate report. This ID is created by CityGrid. | Yes, only if | Long | N/A | 1234567 or 1234,5678 |
|
| ID of the campaign | Only if the provided period is a billing cycle and | Long | N/A | 1234567
| Only one campaign ID is supported and is required when requesting a billing cycle as a period (billing1, billing2 or billing3). |
| External Campaign ID | ONLY if the provided period is a billing cycle and | String | N/A | camp_123 | Only one external campaign ID is supported and is required when requesting a billing cycle as a period (billing1, billing2 or billing3). |
| Pre-defined date ranges for the report. Tokens are case sensitive. Valid values are: | No | String | yesterday | last7Days |
|
| Start date (inclusive) for the report date range to query. Data is available for the last 90 days. | Yes if endDate is used. | Date (formatted as MM-DD-YYYY) | N/A | 11-17-2012 | |
| End date (inclusive) for the report date range to query. Data is available for the last 90 days. | Yes if startDate is used. | Date (formatted as MM-DD-YYYY) | N/A | 11-17-2012 |
billing1 refers to the most recent billing cycle, billing2 to the billing cycle just before billing1, and billing3 to the billing cycle just preceding billing2.
Request Header Values
Header | Description | Required | Valid Values |
|---|---|---|---|
| Media type of the request body, if any | Yes |
|
| Requested format for the response | Yes |
|
| Authentication Token from the Authentication API | Yes | Valid token |
| The token received during registration | Yes | Valid token |
Response Properties
Property | Type | Description |
|---|---|---|
| accountId | Integer | ID of the Account |
| accountName | String | Account Name |
| Long | Campaign Id associated with a place |
| String | Campaign Name associated with a place |
| Double | Cost per click |
| DailyPlacePerformance | Top-level element for performance report results. |
data | Data Metadata | List of results for each report |
| Date String | Date. Available only in daily place performance. |
| String | External Campaign Id associated with a place |
| String | External ID of the place |
| Long | ID of the place |
| String | Place name |
report | Array | List of reports. |
response | Response Metadata | |
| Integer | Total number of connections |
| Integer | Total number of billed connections |
| Integer | Total number of results in the given response |
| Double | Budget used based on total billed connections and CPC in U.S. Dollars |
userAction | String | User action. Available only in user action summary. |
Examples
Example 1: Request a daily report for campaigns 875 and 876 for last week
curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:Application/JSON'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken'
-d '{"places":[{"placeId":"770242580"},{"placeId":"771760700"}],"period":"lastWeek"}'
'http://api.citygrid.com/advertising/performance/v3/places/daily'
{
"reports": [
{
"campaignId": "875",
"campaignName": "",
"data": [
{
"cpc": 0.0,
"date": "20130127",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.0,
"date": "20130128",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.0,
"date": "20130129",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.0,
"date": "20130130",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.0,
"date": "20130131",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.0,
"date": "20130201",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.0,
"date": "20130202",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
}
],
"externalCampaignId": "",
"externalPlaceId": "",
"placeId": "771879900",
"placeName": "",
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
}
},
{
"campaignId": "876",
"campaignName": "",
"data": [
{
"cpc": 0.0,
"date": "20130127",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.58,
"date": "20130128",
"totalBilledConnections": 2,
"totalConnections": 2,
"totalSpend": 1.16
},
{
"cpc": 0.58,
"date": "20130129",
"totalBilledConnections": 2,
"totalConnections": 2,
"totalSpend": 1.16
},
{
"cpc": 0.0,
"date": "20130130",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.0,
"date": "20130131",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.58,
"date": "20130201",
"totalBilledConnections": 2,
"totalConnections": 2,
"totalSpend": 1.16
},
{
"cpc": 0.58,
"date": "20130202",
"totalBilledConnections": 5,
"totalConnections": 5,
"totalSpend": 2.9
}
],
"externalCampaignId": "",
"externalPlaceId": "",
"placeId": "771760700",
"placeName": "",
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
}
}
],
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
},
"totalNumEntries": 2
}
Example 2: Request a daily report for 01-01-2013 (inclusive) to 01-03-2013 (inclusive).
curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken'
-d '{"places":[{"placeId":"771760700"}],"startDate":"01-20-2013","endDate":"01-23-2013"}'
'http://api.citygrid.com/advertising/performance/v3/places/daily'
{
"reports": [
{
"campaignId": "171522",
"campaignName": "",
"data": [
{
"cpc": 0.58,
"date": "20130120",
"totalBilledConnections": 1,
"totalConnections": 1,
"totalSpend": 0.58
},
{
"cpc": 0.0,
"date": "20130121",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.0,
"date": "20130122",
"totalBilledConnections": 0,
"totalConnections": 0,
"totalSpend": 0.0
},
{
"cpc": 0.58,
"date": "20130123",
"totalBilledConnections": 1,
"totalConnections": 1,
"totalSpend": 0.58
}
],
"externalCampaignId": "",
"externalPlaceId": "",
"placeId": "771760700",
"placeName": "",
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
}
}
],
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
},
"totalNumEntries": 1
}
Example 3: Request an action report for last week.
curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken'
-d '{"places":[{"placeId":"771760700"}],"period":"lastWeek"}'
'http://api.citygrid.com/advertising/performance/v3/places/actions'
{
"reports": [
{
"campaignId": "171522",
"campaignName": "",
"data": [
{
"cpc": 0.58,
"totalBilledConnections": 11,
"totalConnections": 11,
"totalSpend": 6.38,
"userAction": "View Profile Page"
}
],
"externalCampaignId": "",
"externalPlaceId": "",
"placeId": "771760700",
"placeName": "",
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
}
}
],
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
},
"totalNumEntries": 1
}
Example 4: Request an action report for 01-01-2013 (inclusive) to 01-04-2013 (inclusive).
curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken'
-d '{"places":[{"placeId":"771760700"}],"startDate":"01-01-2013","endDate":"01-23-2013"}'
'http://api.citygrid.com/advertising/performance/v3/places/actions'
{
"reports": [
{
"campaignId": "171522",
"campaignName": "",
"data": [
{
"cpc": 0.58,
"totalBilledConnections": 2,
"totalConnections": 2,
"totalSpend": 1.16,
"userAction": "View Profile Page"
}
],
"externalCampaignId": "",
"externalPlaceId": "",
"placeId": "771760700",
"placeName": "",
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
}
}
],
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
},
"totalNumEntries": 1
}
Example 5: Request with incorrect period.
curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken'
-d '{"places":[{"placeId":"771760700"}],"period":"last14days"}'
'http://api.citygrid.com/advertising/performance/v3/places/daily'
{
"reports": [
{
"campaignId": "",
"campaignName": "",
"data": [],
"externalCampaignId": "",
"externalPlaceId": "",
"placeId": "771760700",
"placeName": "",
"response": {
"code": "PARAMETER_INVALID",
"field": "period",
"message": "The parameter, period, was invalid. Valid options are yesterday, last7Days, lastWeek, last14Days, last30Days, lastBusinessWeek, thisMonth, lastMonth, billing1, billing2, billing3."
}
}
],
"response": {
"code": "SUCCESS",
"field": "",
"message": "Success"
},
"totalNumEntries": 1
}
Example 6: Request for more than 500 reports.
curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken'
-d '{places":[{"placeId":"123"},{"placeId":"234"},{"placeId":"345"},{"placeId":"456"},{"placeId":"567"},{"placeId":"678"},{"placeId":"789"},{"placeId":"890"},{"placeId":"891"},{"placeId":"892"},{"placeId":"893"},{"placeId":"894"},{"placeId":"895"},{"placeId":"896"},{"placeId":"897"},{"placeId":"898"},{"placeId":"899"},{"placeId":"900"},{"placeId":"901"},{"placeId":"902"},{"placeId":"903"}],"period":"last14Days"}'
'http://api.citygrid.com/advertising/performance/v3/places/daily'
{
"reports": [],
"response": {
"code": "PARAMETER_SIZE_LIMIT_EXCEEDED",
"field": "",
"message": "The parameter, places, exceeds the size limit of 500."
},
"totalNumEntries": 0
}