Introduction

The CityGrid Advertising APIs allow developers to create applications that manage CityGrid campaigns and generate performance reports.

The Advertising APIs are intended for resellers and advertisers who want to manage campaigns via an application programming interface. CityGrid also offers ad creation and management services for those who are interested.

The Advertising API suite includes:

Authentication APIs

The Authentication API, for logging in and receiving an access token to use in subsequent API calls.

Campaign Management APIs

The Campaign API, for creating, updating, and deleting campaigns.
The Campaign Status API, for retrieving the campaign status.
The AdGroup API, for managing ad groups that organize places inside a campaign.
The AdGroupAd API, for creating, updating, and deleting ads within an ad group.
The AdGroupCriterion API, for targeting ad groups by categories (criteria).
The AdGroupGeo API, for targeting ad groups by geographical regions.
The Category API, for looking up categories associated with keywords or places.

Place Management APIs

The Places Management API, for creating, viewing and updating places.
The Offer API for creating, viewing, updating and removing offers

Reporting APIs

The Campaign Performance Reporting API, for retrieving campaign performance data at the campaign level.
The Place Performance Reporting API, for retrieving campaign performance data at the place level.
The Call Detail Reporting API, for retrieving data on metered phone line activity.

Contents

Key Concepts

The Advertising APIs are structured around the following concepts:

An account consists of one or more campaigns.

A campaign has a budget, start date, optional end date, and contains one or more ad groups. Once click-throughs to the ads in a campaign exceed the campaign's budget, the campaign's ads will no longer be served during the current period.

Each ad group is a collection of one or more ads for one particular place (business). Ad groups are targeted via one or more geographies and one or more categories (also known as criteria).

Ad clicks normally direct to place pages within the CityGrid publisher network. It is possible, however, for an advertiser to define a virtual place by supplying a destination URL for ads directly. Please be aware that because direct URLs take users outside the network, CityGrid cannot provide detailed performance or call detail report information for virtual places.

The relationship between accounts, campaigns, ad groups, criteria and geographies is summarized in the following figure:

API Conventions

The Advertising APIs use a REST-like architecture that makes it easy to write and test applications. All API calls are implemented as URLs that can be invoked on the command line (via curl) or via a browser or other HTTP client. HTTP GET requests retrieve information about the campaigns and other resources, while POST requests add, modify, and delete the resources.

HTTP Requests

Data may be passed to the advertising APIs through (1) query parameters, (2) request headers, or (3) the request body. Please see Field Limits and Quotas for specific request restrictions.

HTTP requests make use of the following headers:

The developerToken header should contain the token you received during registration.
The authToken header should contain an authentication token such as "c65ce5b3e17bb9a2a3ef02d31b35471b" which is received from an initial call to the Authentication API.
The Accept header in a request specifies the desired format of the response; this is typically application/json or application/xml. The reporting APIs additionally support application/csv.
The Content-Type header should specify the media type of the request body (for POST requests). This is typically application/json or application/xml.

HTTP GET Requests

Requests for data are sent to the Advertising APIs as HTTPS GET requests with parameters included in the query string and the developer and authentication tokens passed in the request header.

For example, information about ads with ids 786, 666, and 111 is obtained by sending an HTTPS GET request to

api.citygrid.com/advertising/adgroupad/v2/get?adId=786,666,111

with the following sample request headers:

developerToken: abc
authToken: c65ce5b3e17bb9a2a3ef02d31b35471b
Accept: application/json

The Content-Type header is not used for GET requests because GET requests do not contain an entity body.

HTTP POST Requests

Requests for data manipulation are sent to the Advertising APIs as HTTPS POST requests to the endpoint. To manipulate (create, modify, or delete) data, the mutate endpoint is used. The HTTPS header should include the developer and authentication tokens and optionally the content type of the body.

For example, a new ad is created by sending an HTTPS POST request to

api.citygrid.com/advertising/adgroupad/v2/mutate

with the following sample request headers:

developerToken: abc
authToken: c65ce5b3e17bb9a2a3ef02d31b35471b
Content-Type: application/json
Accept: application/json

and a request body of the form:

{
  "mutateOperationListResource":[
    {
      "operator":"ADD",
      "operand":{
        "adGroupId":"2861",
        "ad":{
          "type":"PERFORMANCE_AD",
          "tagline":"myTagline"
        }
      }
    }
  ]
}

HTTP Responses

In addition to the HTTP status code, responses contain metadata with code, field, and message members to provide additional information about the success or failure of the request.

See the Response Codes page for a complete list of API-specific codes.

The following is an example JSON response:

{
  "totalNumEntries":1,
  "adGroupAds":[
    {
      "adGroupId":"2861",
      "id":"42150701",
      "adType":"PERFORMANCE_AD",
      "status":"ACTIVE",
      "tagline":"myTagline",
      "imageUrl":"",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      }
    }
  ]
}

Data Type Conventions

All date parameters are passed as strings in YYYYMMDD format. Example: 20100324 is March 24, 2010.

Postal codes are strings, not integers. They must therefore be quoted when appearing in JSON text.

Advertising APIs Walk-Through

The various APIs are generally used in the following sequence.

(1) Authenticate

The first call in a session must be to the Authentication API login operation to obtain an authentication token. The login endpoint is:

api.citygrid.com/accounts/user/v2/login

All subsequent calls to the other Advertising APIs must include the authToken received from this API.

(2) Create a Campaign

After successfully authenticating, a campaign can be created with a call to the Campaign API mutate operation. The endpoint is:

api.citygrid.com/advertising/campaign/v2/mutate

After successfully creating a campaign, you may verify the campaign with a call to the Campaign API get operation. The endpoint is:

api.citygrid.com/advertising/campaign/v2/get

(3) Create Ad Groups

After verifying the campaign, you may create ad groups within the campaign with a call to the AdGroup API mutate operation. The endpoint is:

api.citygrid.com/advertising/adgroup/v2/mutate

(4) Create or Edit Places

After successfully creating an ad group, you may wish to create or edit the place data associated with the ad group with the Places Management API. The endpoint is:

api.citygrid.com/content/places/v2/mutate

If the business does not have a physical address, a website url must be assigned to the place using this API.

(5) Create Ads

After successfully creating an ad group, you may create ads within the ad group with a call to the AdGroupAd API mutate operation. The endpoint is:

api.citygrid.com/advertising/adgroupad/v2/mutate

Ads for places without a physical address must have a website url specified via this API; the display url is, however, optional. Ads for places with physical addresses may not be assigned urls through this API.

(6) Associate Categories with Ad Group

After successfully creating adGroupAds, you may associate categories (criteria) with ad groups by creating adGroupCriterions with a call to the AdGroupCriterion API mutate operation. The endpoint is:

api.citygrid.com/advertising/adgroupcriterion/v2/mutate

In order to determine the ids of the categories to pass to this API, you will want to look them up by place or keywords using the Category API get operation. The endpoint is:

api.citygrid.com/content/category/v2/get

The id returned by the Category API is then passed as the adGroupCriterionId to the AdGroupCriterion API.

(7) Associate Geographies with Ad Groups

After successfully creating an adGroupCriterion, adGroupGeos can be added to associate geographic information with a call to the AdGroupGeo API mutate operation. The endpoint is:

api.citygrid.com/advertising/adgroupgeo/v2/mutate

If the ad group's place does not have a physical address, this API must be called to associate geography data with the ad, since there is no business address from which to infer geographical targeting.

(8) Request Reports

Several kind of reports can be generated via API calls to help you fine-tune campaigns. For example, you can get performance reports per campaign at the following endpoint:

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

Reports can also be generated for user actions and call details.

Sandbox

The CityGrid Advertising API Sandbox is a testing and development environment that mirrors the functionality of the actual Advertising APIs. To access the sandbox versions of the APIs, simply change the host domain from api.citygrid.com to sandbox-api.citygrid.com.

Please be aware of the following differences between the sandbox and the actual production APIs:

All data created in the sandbox has no effect on real places or live campaigns.
Report data returned by the performance APIs is dummy data for testing purposes only and does not reflect the actual campaigns' performance.
From time to time the data in the sandbox will be removed; do not use the sandbox to store persistent data.
The sandbox environment does not reflect the performance of the production APIs.

API Summary

For reference, the following table summarizes the relative URLs of the APIs in the suite:

API	Location
Authentication API	`/accounts/user/v2/login`
Campaign API	`/advertising/campaign/v2/get` `/advertising/campaign/v2/mutate`
AdGroup API	`/advertising/adgroup/v2/get` `/advertising/adgroup/v2/mutate`
AdGroupAd API	`/advertising/adgroupad/v2/get` `/advertising/adgroupad/v2/mutate`
AdGroupCriterion API	`/advertising/adgroupcriterion/v2/get` `/advertising/adgroupcriterion/v2/mutate`
AdGroupGeo API	`/advertising/adgroupgeo/v2/get` `/advertising/adgroupgeo/v2/mutate`
Places Management API	`/content/places/v2/mutate`
Category API	`/content/category/v2/get`
Campaign Performance Reporting API	`/advertising/performance/v2/campaign/daily` `/advertising/performance/v2/campaign/actions`
Place Performance Reporting API	`/advertising/performance/v2/places/daily` `/advertising/performance/v2/places/actions`
Call Detail Reporting API v2	`/advertising/performance/v2/adgroup/calldetail`
Offer API	`/advertising/offer/v3/mutate`