Campaign Performance Reporting API

This documentation describes V3 of the campaign performance reporting API. Click here to see V2 of the campaign performance reporting API.

Introduction

The CityGrid Campaign Performance Reporting API is part of the Advertising API suite and generates advertiser performance reports by campaign in JSON format. The API provides two endpoints. The Daily Campaign performance endpoint returns reports by campaign on connections, spending, and campaign information. It accepts HTTPS POST at:

api.citygrid.com/advertising/performance/v3/campaign/daily

The User Action Summary endpoint returns data on user-advertising interactions. It accepts HTTPS POST at:

api.citygrid.com/advertising/performance/v3/campaign/actions

The endpoints allows each call to retrieve a maximum of 500 reports per request.

By default the performance 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

Parameter	Description	Required	Type	Default	Example
`campaignId`	Campaign ID	Yes, if `externalCampaignlId` is not specified	Long	N/A	1234567
`externalCampaignId`	External Campaign ID	Yes, if `campaignId` is not specified	String	N/A	camp_123
`period`	Date range for the report (case sensitive)	No	yesterday last7Days last14Days last30Days lastWeek lastBusinessWeek thisMonth lastMonth billing1 billing2 billing3	yesterday	last7Days
`startDate`	Start date (inclusive) for the report date range to query. Data is available for previous 90 days.	Yes if endDate is used.	Date (formatted as MM-DD-YYYY)	N/A	11-17-2012
`endDate`	End date (inclusive) for the report date range to query. Data is available for previous 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

Header	Description	Required	Valid Values
`Content-Type`	Media type of the request body, if any	Yes	`application/json`
`Accept`	Requested format for the response	Yes	`application/json`
`authToken`	Authentication Token from the Authentication API	Yes	Valid token
`developerToken`	The token received during registration	Yes	Valid token

Response Properties

Property	Type	Description

Property	Type	Description
`campaignId`	Long	Campaign Id associated with a place
`campaignName`	String	Campaign Name associated with a place
`cpc`	Double	Cost per click
`data`	Data Metadata	List of results for each report
`date`	Date String	Date. Available only in daily campaign performance.
`externalCampaignId`	String	External Campaign Id associated with a place
`impressions`	Integer	Total number of impressions
`report`	Array	List of reports.
`response`	Response Metadata	(See complete response descriptions)
`totalConnections`	Integer	Total number of connections
`totalBilledConnections`	Integer	Total number of billed connections
`totalNumEntries`	Integer	Total number of reports in the given response
`totalSpend`	Double	Budget used based on total billed connection
`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

Request

curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:Application/JSON'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' 
-d '{"campaigns":[{"campaignId":"875"},{"campaignId":"876"}],"period":"lastWeek"}' 
'http://api.citygrid.com/advertising/performance/v3/campaign/daily'

Response

{
    "reports": [
        {
            "campaignId": "875", 
            "campaignName": "National Campaign", 
            "data": [
                {
                    "cpc": 2.0, 
                    "date": "20130127", 
                    "totalBilledConnections": 1925, 
                    "totalConnections": 3789, 
                    "totalSpend": 3853.66
                }, 
                {
                    "cpc": 0.83, 
                    "date": "20130128", 
                    "totalBilledConnections": 10559, 
                    "totalConnections": 16061, 
                    "totalSpend": 8780.1
                }, 
                {
                    "cpc": 0.75, 
                    "date": "20130129", 
                    "totalBilledConnections": 8570, 
                    "totalConnections": 9320, 
                    "totalSpend": 6425.6
                }, 
                {
                    "cpc": 0.75, 
                    "date": "20130130", 
                    "totalBilledConnections": 7647, 
                    "totalConnections": 9823, 
                    "totalSpend": 5760.0
                }, 
                {
                    "cpc": 0.73, 
                    "date": "20130131", 
                    "totalBilledConnections": 8755, 
                    "totalConnections": 12070, 
                    "totalSpend": 6389.95
                }, 
                {
                    "cpc": 0.73, 
                    "date": "20130201", 
                    "totalBilledConnections": 4015, 
                    "totalConnections": 4673, 
                    "totalSpend": 2927.85
                }, 
                {
                    "cpc": 0.0, 
                    "date": "20130202", 
                    "totalBilledConnections": 0, 
                    "totalConnections": 309, 
                    "totalSpend": 0.0
                }
            ], 
            "externalCampaignId": "", 
            "response": {
                "code": "SUCCESS", 
                "field": "", 
                "message": "Success"
            }
        }, 
        {
            "campaignId": "876", 
            "campaignName": "Local Campaign", 
            "data": [
                {
                    "cpc": 0.37, 
                    "date": "20130127", 
                    "totalBilledConnections": 36168, 
                    "totalConnections": 90011, 
                    "totalSpend": 13530.44
                }, 
                {
                    "cpc": 0.38, 
                    "date": "20130128", 
                    "totalBilledConnections": 36754, 
                    "totalConnections": 73852, 
                    "totalSpend": 13832.02
                }, 
                {
                    "cpc": 0.31, 
                    "date": "20130129", 
                    "totalBilledConnections": 23637, 
                    "totalConnections": 90247, 
                    "totalSpend": 7389.02
                }, 
                {
                    "cpc": 0.34, 
                    "date": "20130130", 
                    "totalBilledConnections": 34618, 
                    "totalConnections": 113591, 
                    "totalSpend": 11909.45
                }, 
                {
                    "cpc": 0.34, 
                    "date": "20130131", 
                    "totalBilledConnections": 34033, 
                    "totalConnections": 94138, 
                    "totalSpend": 11670.51
                }, 
                {
                    "cpc": 0.34, 
                    "date": "20130201", 
                    "totalBilledConnections": 33166, 
                    "totalConnections": 92137, 
                    "totalSpend": 11298.89
                }, 
                {
                    "cpc": 0.34, 
                    "date": "20130202", 
                    "totalBilledConnections": 34560, 
                    "totalConnections": 102177, 
                    "totalSpend": 11589.22
                }
            ], 
            "externalCampaignId": "", 
            "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).

Request

curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' 
-d '{"campaigns":[{"campaignId":"875"}],"startDate":"01-01-2013","endDate":"01-03-2013"}' 
'http://api.citygrid.com/advertising/performance/v3/campaign/daily'

Response

{
    "reports": [
        {
            "campaignId": "875", 
            "campaignName": "National Campaign", 
            "data": [
                {
                    "cpc": 0.75, 
                    "date": "20130101", 
                    "totalBilledConnections": 12017, 
                    "totalConnections": 12017, 
                    "totalSpend": 9012.75
                }, 
                {
                    "cpc": 0.75, 
                    "date": "20130102", 
                    "totalBilledConnections": 10817, 
                    "totalConnections": 17862, 
                    "totalSpend": 8112.75
                }, 
                {
                    "cpc": 0.75, 
                    "date": "20130103", 
                    "totalBilledConnections": 13623, 
                    "totalConnections": 16579, 
                    "totalSpend": 10217.25
                }
            ], 
            "externalCampaignId": "", 
            "response": {
                "code": "SUCCESS", 
                "field": "", 
                "message": "Success"
            }
        }
    ], 
    "response": {
        "code": "SUCCESS", 
        "field": "", 
        "message": "Success"
    }, 
    "totalNumEntries": 1
}

Example 3: Request an action report for last week.

Request

curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' 
-d '{"campaigns":[{"campaignId":"875"},{"campaignId":"876"}],"period":"lastWeek"}' 
'http://api.citygrid.com/advertising/performance/v3/campaign/daily'

Response

{
    "reports": [
        {
            "campaignId": "875", 
            "campaignName": "National Campaign", 
            "data": [
                {
                    "cpc": 0.82, 
                    "totalBilledConnections": 41471, 
                    "totalConnections": 56045, 
                    "totalSpend": 34137.16, 
                    "userAction": "View Profile Page"
                }
            ], 
            "externalCampaignId": "", 
            "response": {
                "code": "SUCCESS", 
                "field": "", 
                "message": "Success"
            }
        }, 
        {
            "campaignId": "876", 
            "campaignName": "Local Campaign", 
            "data": [
                {
                    "cpc": 0.35, 
                    "totalBilledConnections": 232936, 
                    "totalConnections": 656153, 
                    "totalSpend": 81219.55, 
                    "userAction": "View Profile Page"
                }
            ], 
            "externalCampaignId": "", 
            "response": {
                "code": "SUCCESS", 
                "field": "", 
                "message": "Success"
            }
        }
    ], 
    "response": {
        "code": "SUCCESS", 
        "field": "", 
        "message": "Success"
    }, 
    "totalNumEntries": 2
}

Example 4: Request an action report for 01-01-2013 (inclusive) to 01-04-2013 (inclusive).

Request

curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' 
-d '{"campaigns":[{"campaignId":"875"},{"campaignId":"876"}],"startDate":"01-01-2013","endDate":"01-04-2013"}' 
'http://api.citygrid.com/advertising/performance/v3/campaign/actions'

Response

{
    "reports": [
        {
            "campaignId": "875", 
            "campaignName": "National Campaign", 
            "data": [
                {
                    "cpc": 0.75, 
                    "totalBilledConnections": 178706, 
                    "totalConnections": 229778, 
                    "totalSpend": 134899.48, 
                    "userAction": "View Profile Page"
                }
            ], 
            "externalCampaignId": "", 
            "response": {
                "code": "SUCCESS", 
                "field": "", 
                "message": "Success"
            }
        }, 
        {
            "campaignId": "876", 
            "campaignName": "Local Campaign", 
            "data": [
                {
                    "cpc": 3.5, 
                    "totalBilledConnections": 2, 
                    "totalConnections": 2, 
                    "totalSpend": 7.0, 
                    "userAction": "Click to Website"
                }, 
                {
                    "cpc": 0.41, 
                    "totalBilledConnections": 897117, 
                    "totalConnections": 2366334, 
                    "totalSpend": 365293.75, 
                    "userAction": "View Profile Page"
                }
            ], 
            "externalCampaignId": "", 
            "response": {
                "code": "SUCCESS", 
                "field": "", 
                "message": "Success"
            }
        }
    ], 
    "response": {
        "code": "SUCCESS", 
        "field": "", 
        "message": "Success"
    }, 
    "totalNumEntries": 2
}

Example 5: Request with incorrect period.

Request

curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' 
-d '{"campaigns":[{"campaignId":"875"}],"period":"last14days"}' 
'http://api.citygrid.com/advertising/performance/v3/campaign/daily'

Response

{
    "reports": [
        {
            "campaignId": "876", 
            "campaignName": "", 
            "data": [], 
            "externalCampaignId": "", 
            "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.

Request

curl -X POST
-H 'Accept:application/json'
-H 'Content-Type:application/json'
-H 'authToken:mytoken'
-H 'developerToken:mydevtoken' 
-d '{"campaigns":[{"campaignId":"123"},{"campaignId":"234"},{"campaignId":"345"},{"campaignId":"456"},{"campaignId":"567"},{"campaignId":"678"},{"campaignId":"789"},{"campaignId":"890"},{"campaignId":"891"},{"campaignId":"892"},{"campaignId":"893"},{"campaignId":"894"},{"campaignId":"895"},{"campaignId":"896"},{"campaignId":"897"},{"campaignId":"898"},{"campaignId":"899"},{"campaignId":"900"},{"campaignId":"901"},{"campaignId":"902"},{"campaignId":"903"}],"period":"last14Days"}' 
'http://api.citygrid.com/advertising/performance/v3/campaign/daily'

Response

{
    "reports": [], 
    "response": {
        "code": "PARAMETER_SIZE_LIMIT_EXCEEDED", 
        "field": "", 
        "message": "The parameter, campaigns, exceeds the size limit of 500."
    }, 
    "totalNumEntries": 0
}