Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata
Icon

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.

 

Icon

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

externalPlaceId

Your own ID(s) identifying the place for which to generate report.

Yes, alternately we can use placeId

String

N/A

camp_123

or

abc123, def123

 

placeId

Place ID(s) for which to generate report. This ID is created by CityGrid.

Yes, only if externalPlaceId is not specified

Long

N/A

1234567

or

1234,5678 

 

campaignId

ID of the campaign

Only if the provided period is a billing cycle and externalCampaignId is not specified.

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).

externalCampaignId

External Campaign ID

ONLY if the provided period is a billing cycle and campaignId is not specified.

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).

period

Pre-defined date ranges for the report. Tokens are case sensitive. Valid values are:
yesterday  
last7Days  
last14Days  
last30Days  
lastWeek  
lastBusinessWeek
billing1
billing2
billing3

No

String

yesterday

last7Days

 

startDate

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

 

endDate

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

 
Icon

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

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

accountIdIntegerID of the Account
accountNameStringAccount Name

campaignId

Long

Campaign Id associated with a place

campaignName

String

Campaign Name associated with a place

cpc

Double

Cost per click

dailyPlacePerformance

DailyPlacePerformance

Top-level element for performance report results.

data
Data MetadataList of results for each report

date

Date String

Date. Available only in daily place performance.

externalCampaignId

String

External Campaign Id associated with a place

externalPlaceId

String

External ID of the place

placeId

Long

ID of the place

placeName

String

Place name

report
ArrayList 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 results in the given response

totalSpend

Double

Budget used based on total billed connections and CPC in U.S. Dollars

userAction
StringUser action. Available only in user action summary.

Examples

Example 1: Request a daily report for campaigns 875 and 876 for last week
Request
Response
Example 2: Request a daily report for 01-01-2013 (inclusive) to 01-03-2013 (inclusive).
Request
Response
Example 3: Request an action report for last week.
Request
Response
Example 4: Request an action report for 01-01-2013 (inclusive) to 01-04-2013 (inclusive).
Request
Response
Example 5: Request with incorrect period.
Request
Response
Example 6: Request for more than 500 reports.
Request
Response
  • No labels