Advertising by CityGrid

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:

1 Introduction
2 Key Concepts
3 API Conventions
- 3.1 HTTP Requests
  - 3.1.1 HTTP GET Requests
  - 3.1.2 HTTP POST Requests
- 3.2 HTTP Responses
- 3.3 Data Type Conventions
4 Advertising APIs Walk-Through
- 4.1 (1) Authenticate
- 4.2 (2) Create a Campaign
- 4.3 (3) Create Ad Groups
- 4.4 (4) Create or Edit Places
- 4.5 (5) Create Ads
- 4.6 (6) Associate Categories with Ad Group
- 4.7 (7) Associate Geographies with Ad Groups
- 4.8 (8) Request Reports
5 Sandbox
6 API Summary

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.