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:
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:
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.
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:
developerTokenheader should contain the token you received during registration.
authTokenheader should contain an authentication token such as "c65ce5b3e17bb9a2a3ef02d31b35471b" which is received from an initial call to the Authentication API.
Acceptheader in a request specifies the desired format of the response; this is typically
application/xml. The reporting APIs additionally support
Content-Typeheader should specify the media type of the request body (for POST requests). This is typically
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
with the following sample request headers:
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
with the following sample request headers:
and a request body of the form:
In addition to the HTTP status code, responses contain metadata with
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:
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.
The first call in a session must be to the Authentication API login operation to obtain an authentication token. The login endpoint is:
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:
After successfully creating a campaign, you may verify the campaign with a call to the Campaign API get operation. The endpoint is:
(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:
(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:
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:
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:
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:
(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:
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:
Reports can also be generated for user actions and call details.
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
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.
For reference, the following table summarizes the relative URLs of the APIs in the suite: