CityGrid Advertising APIs
Deprecated Place Performance Reporting API
- Former user (Deleted)
This API has been Deprecated
Introduction
The CityGrid Place Performance Reporting API is part of the Advertising API suite and generates advertiser performance reports by place. Report information is available in either JSON or CSV formats.
The API provides two endpoints:
places/daily— to report connections, billing, and spending by placeplaces/actions— to report user interactions by place
Contents
Daily Place Performance Report Endpoint
The Daily Place Performance endpoint returns reports by place on connections, spending, and campaign information.
The Daily Place Performance API daily report is accessed at the following endpoint with either HTTPS GET or HTTPS POST:
By default the place performance report is generated for the most recent 24-hour period from 9:00 p.m. to 9:00 p.m., Pacific Standard 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 |
Request Header Values
Header | Description | Required | Valid Values |
|---|---|---|---|
| Media type of the request body, if any | Only if POST |
|
| Requested format for the response | Yes |
|
| Authentication Token from the Authentication API | Yes | Valid token |
| The token received during registration | Yes | Valid token |
Request Examples
Example 1: Request a daily report for place 662793130 for yesterday (JSON format, HTTPS GET)
curl -X GET
-H 'Accept:application/json
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
'https://api.citygrid.com/advertising/performance/v2/placeId=662793130'
Example 2: Request a daily report for places 662793130 and 662793256 for last 14 days (CSV format, HTTPS GET)
curl -X GET
-H 'Accept:application/csv
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
'https://api.citygrid.com/advertising/performance/v2/places/daily?placeId=662793130,662793256&period=last14Days'
Example 3: Request a daily report for places 662793130 and 662793256 for last 30 days (CSV format, HTTPS POST)
curl -X POST
-H 'Accept:application/csv
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"placeId":"662793130,662793256", "period":"last30Days"}'
'https://api.citygrid.com/advertising/performance/v2/places/daily'
Example 4: Request a daily report for places 662793130 and 662793256 for last 30 days (CSV format, HTTPS POST)
curl -X POST
-H 'Accept:application/csv
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"placeId":"662793130,662793256", "period":"last30Days"}'
'https://api.citygrid.com/advertising/performance/v2/places/daily'
Example 5: Request a daily report for places 662793130 and 662793256 for yesterday (JSON format, HTTPS POST)
curl -X POST
-H 'Accept:application/json
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"placeId":"662793130,662793256", "period":"last30Days"}'
'https://api.citygrid.com/advertising/performance/v2/places/daily'
Example 6: Request a daily report for places 662793130 and 662793256 for the most recent billing cycle (JSON format, HTTPS POST)
curl -X POST
-H 'Accept:application/json
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"placeId":"662793130,662793256", "period":"billing1", "campaignId":"1124698"}'
'https://api.citygrid.com/advertising/performance/v2/places/daily'
Example 7: Request a daily report for places (using externalPlaceIds 2131991 and 2131887) for the most recent billing cycle (JSON format, HTTPS POST)
curl -X POST
-H 'Accept:application/json
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"externalPlaceId":"2131991,2131887", "period":"billing1", "campaignId":"1124698"}'
'https://api.citygrid.com/advertising/performance/v2/places/daily'
Example 8: Request the daily report for 11-01-2012 (inclusive) to 11-15-2012 (inclusive).
curl -X GET \ -H 'Accept:application/json' \ -H 'authToken:mytoken' \ -H 'developerToken:mydevtoken' \ 'https://api.citygrid.com/advertising/performance/v2/places/daily?placeId=662793130,662793256&startDate=11-01-2012&endDate=11-15-2012'
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. |
| Date String | Date |
| String | External Campaign Id associated with a place |
| String | External ID of the place |
| Long | ID of the place |
| String | Place name |
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 |
Response Examples
Example 1: A JSON success response
A request to:
api.citygrid.com/advertising/performance/v2/places/daily?placeId=662793130,662793256&period=last30Days
may produce:
{
"totalNumEntries": "2",
"dailyPlacesPerformance": [
{
"date": "",
"placeId": "605754722",
"externalPlaceId": "605754722",
"placeName": "",
"campaignId": "",
"externalCampaignId": "",
"campaignName": "",
"totalConnections": "",
"totalBilledConnections": "",
"cpc": "",
"totalSpend": "",
"response": {
"code": "DATA_NOT_FOUND",
"message": "There is no data for given Id.",
"field": ""
}
},
{
"date": "20121011",
"placeId": "605754722",
"externalPlaceId": "605754722",
"placeName": "MedPro - DNA Testing, STD Testing - BRIDGEPORT",
"campaignId": "3042792",
"externalCampaignId": "",
"campaignName": "MedPro",
"totalConnections": "3",
"totalBilledConnections": "0",
"cpc": "0",
"totalSpend": "0.00",
"response": {
"code": "SUCCESS",
"message": "Success",
"field": ""
}
}
],
"response": {
"code": "SUCCESS",
"message": "Success",
"field": ""
}
}
Example 2: A CSV success response
A request to:
api.citygrid.com/advertising/performance/v2/places/daily?placeId=605754722,662793256&period=last7Days
may produce:
date,placeId,externalPlaceId,placeName,campaignId,externalCampaignId,campaignName,totalConnections,totalBilledConnections,cpc,totalSpend,code,message ,662793256,,,,,,,,,,, 20121011,605754722,662793130,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",3042792,,MedPro,3,0,0,0.00,, 20121012,605754722,662793130,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",3042792,,MedPro,1,1,1.30,1.30,, 20121013,605754722,662793130,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",3042792,,MedPro,1,0,0,0.00,, 20121014,605754722,662793130,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",3042792,,MedPro,1,0,0,0.00,, 20121015,605754722,662793130,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",3042792,,MedPro,1,1,1.30,1.30,, 20121016,605754722,662793130,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",3042792,,MedPro,1,0,0,0.00,, 20121017,605754722,662793130,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",3042792,,MedPro,2,0,0,0.00,,
Example 3: A JSON error response
A request with the misspelled billing period "Last14Days" (instead of the correct "last14Days"), such as:
api.citygrid.com/advertising/performance/v2/places/daily?placeId=1234&period=Last14Days
will produce:
{
"totalNumEntries": "",
"dailyPlacesPerformanceResources": [],
"response": {
"code": "PARAMETER_INVALID",
"message": "The parameter, period, was invalid. Valid options are lastBusinessWeek, last7Days, thisMonth, yesterday, lastWeek, lastMonth, last30Days, last14Days, billing1, billing2, billing3.",
"field": "period"
}
}
Example 4: A JSON error response
A request containing a campaignId for a period that is not a billing cycle, such as:
api.citygrid.com/advertising/performance/v2/places/daily?placeId=1234&period=Last14Days&campaignId=1124698
produces:
{
"totalNumEntries": "",
"dailyPlacesPerformance": [],
"response": {
"code": "ENTITY_NOT_ELIGIBLE",
"message": "Campaign not eligible for the specified period",
"field": ""
}
}
Example 5: A CSV error response
A request with the misspelled billing period "Last14Days" (instead of the correct "last14Days"), such as:
api.citygrid.com/advertising/performance/v2/places/daily?placeId=1234&period=Last14Days
will produce:
code,message,field PARAMETER_INVALID,The parameter, period, was invalid. Valid options are lastBusinessWeek, last7Days, thisMonth, yesterday, lastWeek, lastMonth, last30Days, last14Days, billing1, billin2, billing3.,period
Example 6: A CSV error response
A request containing two external campaign IDs, such as:
api.citygrid.com/advertising/performance/v2/places/daily?placeId=662793130&period=billing1&externalCampaignId=2578382,2578382
will produce:
code,message,field PARAMETER_ONLY_ONE,"There can only be one external campaign id specified,externalCampaignId
User Action Summary By Place Endpoint
The Place Performance API user action summary returns data on user-advertising interactions.
The Performance API user action summary report is accessed at the following endpoint with either HTTPS GET or HTTPS POST:
By default the place performance report is generated for the most recent 24-hour period from 9:00 p.m. to 9:00 p.m., Pacific Standard 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 Header Values
Header | Description | Required | Valid Values |
|---|---|---|---|
| Media type of the request body, if any | Only if POST |
|
| Requested format for the response | Yes |
|
| Authentication Token from the Authentication API | Yes | Valid token |
| The token received during registration | Yes | Valid token |
Request Parameters
Parameter | Description | Required | Type | Default | Example | Notes |
|---|---|---|---|---|---|---|
| Place ID for which to generate report. This ID is created by CityGrid. | Yes, if | Long | N/A | 1234567 |
|
| Your own ID identifying the place for which to generate report | Yes, if | String | N/A | camp_123 |
|
| 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. | 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. | Yes if startDate is used. | Date (formatted as MM-DD-YYYY) | N/A | 11-17-2012 |
Request Examples
Example 1: Request a user action report for place 662793130 for yesterday (JSON format, HTTPS GET)
curl -X GET
-H 'Accept:application/json
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
'https://api.citygrid.com/advertising/performance/v2/places/actions?placeId=662793130'
Example 2: Request a user action report for places 662793130 and 662793256 for last 14 days(CSV format, HTTPS GET)
curl -X GET
-H 'Accept:application/csv
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
'https://api.citygrid.com/advertising/performance/v2/places/actions?placeId=662793130,662793256&period=last14Days'
Example 3: Request a user action report for places (using externalPlaceIds 2131991 and 2131887) for last 7 days (CSV format, HTTPS GET)
curl -X GET
-H 'Accept:application/csv
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
'https://api.citygrid.com/advertising/performance/v2/places/actions?externalPlaceId=2131991,2131887&period=last7Days'
Example 4: Request a user action report for places 662793130 and 662793256 for last 30 days (CSV format, HTTPS POST)
curl -X POST
-H 'Accept:application/csv
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"placeId":"662793130,662793256", "period":"last30Days"}'
'https://api.citygrid.com/advertising/performance/v2/places/actions'
Example 5: Request a user action report for places 662793130 and 662793256 for yesterday (JSON format, HTTPS POST)
curl -X POST
-H 'Accept:application/json
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"placeId":"662793130,662793256", "period":"last30Days"}'
'https://api.citygrid.com/advertising/performance/v2/places/actions'
Example 6: Request a user action report for places 662793130 and 662793256 for this billing cycle (billing1) (JSON format, HTTPS POST)
curl -X POST
-H 'Accept:application/json
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"placeId":"662793130,662793256", "period":"billing1", "campaignId":"1124698"}'
'https://api.citygrid.com/advertising/performance/v2/places/actions'
Example 7: Request a user action report for places (using externalPlaceIds 2131991 and 2131887) for this billing cycle (billing1) using externalCampaignId (JSON format, HTTPS POST)
curl -X POST
-H 'Accept:application/json
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' \
-d '{"externalPlaceId":"2131991,2131887", "period":"billing1", "externalCampaignId":"2578382"}'
'https://api.citygrid.com/advertising/performance/v2/places/actions'
Example 8: Request a user action report for 11-01-2012 (inclusive) to 11-15-2012 (inclusive).
curl -X GET \ -H 'Accept:application/json' \ -H 'authToken:mytoken' \ -H 'developerToken:mydevtoken' \ 'https://api.citygrid.com/advertising/performance/v2/places/actions?placeId=662793130,662793256&startDate=11-01-2012&endDate=11-15-2012'
Response Properties
Property | Type | Description |
|---|---|---|
| Long | Campaign Id associated with a place |
| String | Campaign Name associated with a place |
| Double | Cost per click |
| String | External Campaign Id associated with a place |
| String | External ID of the Place |
| Long | ID of the Place |
| String | Name of the Place |
| Response Metadata | |
| Integer | Connection count for this action |
| Integer | Total number of billed connection |
| Integer | Total number of results in the given response |
| Double | Total advertising budget spending resulting from this user action |
| String | Description of the user action |
| UserActions | List of UserAction (summaries of user actions) |
Response Examples
Example 1: A JSON success response
A request to:
api.citygrid.com/advertising/performance/v2/places/actions?placeId=662793130,662793256&period=last30Days
may produce:
{
"totalNumEntries":"4",
"userActionPlacePerformance":[
{
"placeId":"662793256",
"externalPlaceId":"",
"placeName":"",
"campaignId":"",
"externalCampaignId":"",
"campaignName":"",
"userAction":"",
"totalConnections":"",
"totalBilledConnections":"",
"cpc":"",
"totalSpend":"",
"response":{
"code":"DATA_NOT_FOUND",
"message":"There is no data for given Id.",
"field":""
}
},
{
"placeId": "662793130",
"externalPlaceId": "",
"placeName": "MedPro - DNA Testing, STD Testing - BRIDGEPORT",
"campaignId": "3042792",
"externalCampaignId": "",
"campaignName": "MedPro",
"userAction": "Click to Website",
"totalConnections": "2",
"totalBilledConnections": "2",
"cpc": "1.30",
"totalSpend": "2.60",
"response": {
"code": "SUCCESS",
"message": "Success",
"field": ""
}
},
{
"placeId": "662793130",
"externalPlaceId": "",
"placeName": "MedPro - DNA Testing, STD Testing - BRIDGEPORT",
"campaignId": "3042792",
"externalCampaignId": "",
"campaignName": "MedPro",
"userAction": "Request Driving Directions",
"totalConnections": "1",
"totalBilledConnections": "1",
"cpc": "1.30",
"totalSpend": "1.30",
"response": {
"code": "SUCCESS",
"message": "Success",
"field": ""
}
},
{
"placeId": "662793130",
"externalPlaceId": "",
"placeName": "MedPro - DNA Testing, STD Testing - BRIDGEPORT",
"campaignId": "3042792",
"externalCampaignId": "",
"campaignName": "MedPro",
"userAction": "View Map",
"totalConnections": "1",
"totalBilledConnections": "0",
"cpc": "0",
"totalSpend": "0.00",
"response": {
"code": "SUCCESS",
"message": "Success",
"field": ""
}
}
],
"response":{
"code":"SUCCESS",
"message":"Success",
"field":""
}
}
Example 2: A CSV success response
A request to:
api.citygrid.com/advertising/performance/v2/places/actions?placeId=662793130,662793256&period=last30Days
may produce:
placeId,externalPlaceId,placeName,userAction,campaignId,externalCampaignId,campaignName,totalConnections,totalBilledConnections,totalSpend,cpc,code,message 662793256,,,,,,,,,,,, 605754722,2131991,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",Click to Website,3042792,,MedPro,2,2,2.60,1.30,, 605754722,2131991,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",Request Driving Directions,3042792,,MedPro,1,1,1.30,1.30,, 605754722,2131991,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",View Map,3042792,,MedPro,1,0,0.00,0,, 605754722,2131991,"MedPro - DNA Testing, STD Testing - BRIDGEPORT",View Profile Page,3042792,,MedPro,24,5,6.50,1.30,,
Example 3: A JSON error response
A request containing the misspelled period "Last14Days", such as:
api.citygrid.com/advertising/performance/v2/places/actions?placeId=1234&period=Last14Days
will produce:
{
"totalNumEntries": "",
"userActions": [],
"response": {
"code": "PARAMETER_INVALID",
"message": "The parameter, period, was invalid. Valid options are lastBusinessWeek, last7Days, thisMonth, yesterday, lastWeek, lastMonth, last30Days, last14Days, billing1, billing2, billing3.",
"field": "period"
}
}
Example 4: A JSON error response
A request containing a campaign ID in a non-period billing cycle, such as:
api.citygrid.com/advertising/performance/v2/places/actions?placeId=1234&period=Last14Days&campaignId=1124698
may produce:
{
"totalNumEntries": "",
"dailyPlacesPerformance": [],
"response": {
"code": "ENTITY_NOT_ELIGIBLE",
"message": "Campaign not eligible for the specified period",
"field": ""
}
}
Example 5: A CSV error response
A request containing the misspelled period "Last14Days", such as:
api.citygrid.com/advertising/performance/v2/places/actions?placeId=1234&period=Last14Days
may produce:
code,message,field PARAMETER_INVALID,The billing period was invalid,period
Example 6: A CSV error response
A request containing two campaign IDs, such as:
api.citygrid.com/advertising/performance/v2/places/actions?placeId=662793130&period=billing1&campaignId=2578382,2578382
will produce:
code,message,field PARAMETER_INVALID,The parameter campaignId was invalid. Valid options are numbers.,campaignId