Introduction
The CityGrid Offers API enables developers to create applications that access deals and offers in the CityGrid network. Examples of applications that could use the Offers API include:
- Applications that display offers for restaurants in a specified neighborhood
- Applications that display offers for refrigerators in a given metropolitan area
- Applications that display free offers only
If you qualify as a CityGrid partner, you may use Places that Pay, which allows you to get paid when using the Offers API. Use Impression Tracking to notify CityGrid about impressions and references.
The Offers API consists of two endpoint categories:
Offers Search allows you to find multiple offers by "what" and "where", but does not return detailed information about each offer. Offers Detail allows you to obtain information about a particular offer, such as location, how to redeem, start and expiration dates, etc.
Table of Contents
Audience
The Offers API is intended for developers of Web and mobile applications who want to give their applications the ability to display offers for listings.
Version 2 Updates
The following are changes for version 2, updated from version 1:
- New endpoint URLs that begin with:
http://api.citygridmedia.com/content/offers/v2/search
. - Changes to search requests:
- Added format
- Added publisher
- Added placement
- Added startdate
- Added source
- Added type
- Added popularity
- Added histograms
- Changed expiresbefore to expires_before
- Changed customer_hasbudget to has_budget
- Removed Accept
- Removed X-Publisher
- Removed X-Version
- Removed X-Placement
- Changes to offers search response:
- Added impression_id.
- Added start_date.
- Added redemption_type.
- Added expiration_date.
- Added popularity.
- Added location element.
- Added terms.
- Added redemption_code.
- Added business_hours.
- Added tags element.
- Added tag under tags element.
- Changed offer_description to description.
- Changed offer_id to id.
- Changed offer_title to title.
- Changed infousaId to infousa_id.
- Removed cs_rating.
- Removed listing_name.
- Removed listing_id.
- Changes to search response error codes
- Added latitude.illegal.
- Added longitude.illegal.
- Added radius.illegal.
- Added startdate.illegal.
- Added expiresbefore.illegal.
- Added popularity.illegal.
- Added sort.illegal.
- Added type.illegal.
- Added tag.illegal.
- Added date.past.
- Added internal.error.
- Changed geography.not.found to geocode.failure.
- Removed publisher.invalid.
Offers Search
The Offers Search API provides programmatic access to CityGrid's local search engine, delivering offers, deals, and coupons together with metadata including URIs for subsequent refinement and expansion searches.
There are two endpoints:
Search Using Where
The where endpoint allows you to search for offers using a place name or zip code. It is useful for free-form text and broad geographical region-based searches.
Where Search HTTP Endpoint
The following endpoint supports HTTP GET:
http://api.citygridmedia.com/content/offers/v2/search/where
Where Search Request
The following query string parameters are used with the Offers API search where endpoint:
Parameter |
Description |
Required |
Valid Values |
Default |
Examples |
Notes |
---|---|---|---|---|---|---|
what |
Search term text. |
No |
|
|
pizza |
Supply this parameter to find user lists containing business and event profiles associated with this text. |
where |
The geographic location. |
Yes |
A zip code, city-state pair, or street address (Spaces are optional following the comma between a city and state). |
|
91011 |
Address-based search is performed when this parameter starts with a number and contains non-numeric characters; it is much slower than searching a named region. |
tag |
Restricts search to listings with the given tag ID. |
No |
An integer. |
|
1722 |
Tag IDs are internal CityGrid identifiers and subject to change. This parameter should only be used in queries that are obtained as "refinement urls" from previous searches. |
rpp |
Results per page. |
No |
Positive integer between 1 and 50 inclusive. |
20 |
20 |
The maximum number of matching offers to return in a response. |
start_date |
Filters to return offers with date same or equal to this date. |
No |
A date specified in ISO 8601 format |
2010-10-01 |
|
|
expires_before |
Restricts the search to offers expiring before and including this given date. |
No |
A date specified in ISO 8601 format |
|
2007-08-01T23:12 |
|
has_budget |
Whether or not to filter the results of matching offers to customers with budget. |
No |
false |
true |
false |
|
sort |
Sort criterion for the results. |
No |
dist |
|
relevance |
|
source |
Source where offer was obtained. |
No |
|
|
Citysearch.com |
|
type |
Type of offers to display. |
No |
percentoff |
|
free |
|
popularity |
Return offers that have the minimum # of clicks specified. |
No |
An integer greater or equal than 0. |
|
100 |
|
histograms |
Include histograms in the results. |
No |
false |
false |
true |
Enabling histograms will decrease performance. |
format |
The desired format for the results. |
No |
json |
xml |
json |
json = javascript object notation |
callback |
The name of (your own) JavaScript function in which the JSON response should be wrapped. |
No |
|
|
display |
|
publisher |
The publisher code that identifies you. |
Yes |
|
|
acme |
|
placement |
An optional property for storing additional information you would like CityGrid Media to log for this view. |
No |
|
|
|
An example: if you run a search engine marketing campaign for, say, Google and Yahoo!, you can set the placement property to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement property to values such as "home_page" or "search" (all up to you). CityGrid will organize reports for you by placement. |
exclude_tag |
Exclude results containing this tag id |
No |
An integer. |
|
1722 |
You may exclude more than one tag id by specifying exclude_tag more than once in your URL, ex. exclude_tag=1722&exclude_tag=1684 |
See the Specifying Where section in the Places API topic for more information on how to use the where endpoint.
Where Search Usage Examples
The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.
Usage |
URL |
---|---|
Find offers for Italian restaurants in Chicago |
|
Find offers for spas in Boston, viewing results 6-10 |
Search Using Latitude and Longitude
The latlon endpoint allows you to search for offers using a geographic region defined by latitude and longitude.
LatLon Search HTTP Endpoint
The following endpoint supports HTTP GET:
http://api.citygridmedia.com/content/offers/v2/search/latlon
LatLon Search Request
The following query string parameters are used with the Offers API search latlon endpoint:
Parameter |
Description |
Required |
Valid Values |
Default |
Examples |
Notes |
---|---|---|---|---|---|---|
what |
Search term text. |
No |
|
|
pizza |
Supply this parameter to find user lists containing business and event profiles associated with this text. |
tag |
Restricts search to listings with the given tag ID. |
No |
An integer. |
|
1722 |
Tag IDs are internal CityGrid identifiers and subject to change. This parameter should only be used in queries that are obtained as "refinement urls" from previous searches. |
lat |
Latitude of the center of a circle for a geographic search. |
See Notes below |
|
|
37.65056 |
|
lon |
Longitude of the center of a circle to search. |
See Notes below |
|
|
-119.03639 |
|
lat2 |
Second latitude used when performing a manual box search. |
See Notes below |
|
|
37.65056 |
lat2 and lon2 represents the lower right corner of the box. |
lon2 |
Second longitude used when performing a manual box search. |
See Notes below |
|
|
-119.03639 |
lat2 and lon2 represents the lower right corner of the box. |
radius |
Radius of a circle search. |
See Notes below |
Positive number between 1 and 50 inclusive. |
5 |
7.5 |
If larger than 50 it defaults to 50. |
rpp |
Results per page. |
No |
Positive integer between 1 and 50 inclusive. |
20 |
20 |
The maximum number of matching offers to return in a response. |
start_date |
Filters to return offers with date same or equal to this date. |
No |
A date specified in ISO 8601 format |
2010-10-01 |
|
|
expires_before |
Restricts the search to offers expiring before and including this given date. |
No |
A date specified in ISO 8601 format |
|
2007-08-01T23:12 |
|
has_budget |
Whether or not to filter the results of matching offers to customers with budget. |
No |
false |
true |
false |
|
sort |
Sort criterion for the results. |
No |
dist |
|
relevance |
|
source |
Source where offer was obtained. |
No |
|
|
Citysearch.com |
|
type |
Type of offers to display. |
No |
percentoff |
|
free |
|
popularity |
Return offers that have the minimum # of clicks specified. |
No |
An integer greater or equal than 0. |
|
100 |
|
histograms |
Include histograms in the results. |
No |
false |
false |
true |
Enabling histograms will decrease performance. |
format |
The desired format for the results. |
No |
json |
xml |
json |
json = javascript object notation |
callback |
The name of (your own) JavaScript function in which the JSON response should be wrapped. |
No |
|
|
display |
|
publisher |
The publisher code that identifies you. |
Yes |
|
|
acme |
|
placement |
An optional property for storing additional information you would like CityGrid Media to log for this view. |
No |
|
|
|
An example: if you run a search engine marketing campaign for, say, Google and Yahoo!, you can set the placement property to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement property to values such as "home_page" or "search" (all up to you). CityGrid will organize reports for you by placement. |
exclude_tag |
Exclude results containing this tag id |
No |
An integer. |
|
1722 |
You may exclude more than one tag id by specifying exclude_tag more than once in your URL, ex. exclude_tag=1722&exclude_tag=1684 |
Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).
Notes
In order to specify a geography inside which to search for offers, you must use one of the following searches:
- Point-Radius (specify lat, lon, and radius)
- Box (specify lat, lon, lat2, and lon2)
For more details, see the Specifying the Geography section in the Places API topic.
LatLon Search Usage Examples
The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.
Usage |
URL |
---|---|
Find offers for sushi in latitude 34.03N, longitude118.28W |
Search Response
The Offers Search results are returned in either XML, JSON, or Google's Protocol Buffers.
The following table describes the return XML elements (or JSON objects/keys):
Element |
Parent Element |
Attributes |
Description |
---|---|---|---|
results |
|
rpp - Number of results requested per page |
Metadata regarding the search results. |
uri |
results |
|
Request URL processed. |
did_you_mean |
results |
|
Spelling suggestions if what parameter was provided and not enough results were retrieved. |
regions |
results |
|
Because the geographic region provided in the where parameter contains free-form text, its value may be ambiguous. This is a collection of interpretations. |
region |
regions |
type - The type of geography this region represents (e.g. city, neighborhood) |
|
name |
region |
|
Name of the region. |
latitude |
region |
|
Latitude associated with the region. |
longitude |
region |
|
Longitude associated with the region. |
default_radius |
region |
|
Approximate radius for the region. Represents the value used for the radius if an address or intersection is used as a value for the where parameter. |
offers |
results |
|
Collection of offers. |
offer |
offers |
|
An offer. |
attribution_logo |
offer |
|
Logo of content provider of offer. |
attribution_text |
offer |
|
Name of content provider of offer. |
attribution_source |
offer |
|
ID of content provider of offer. |
id |
offer |
|
Unique identifier for this offer. |
reference_id |
offer |
|
An internal secondary identifier for the business used for tracking. |
impression_id |
offer |
|
The internal impression id generated for tracking. |
title |
offer |
|
Short summary title for the offer. |
description |
offer |
|
Detailed description of offer. |
redemption_type_id |
offer |
|
Internal id associated with the redemption_type. |
redemption_type |
offer |
|
Possible values are Print, Online, or Both |
redemption_code |
offer |
|
Redemption Code of the offer. |
terms |
offer |
|
Details the Terms and Conditions of the offer. |
image_url |
offer |
|
The image url of offer on CityGrid. |
start_date |
offer |
|
Date when offer is valid. |
expiration_date |
offer |
|
Date/Time when offer expires. |
popularity |
offer |
|
The # of clicks for a month period calculated everyday overnight. |
locations |
offer |
|
The location(s) associated with the offer. |
location |
locations |
|
Details about the business associated with the offer. |
id |
location |
|
The CityGrid identifier for the business. |
infousa_id |
location |
|
The InfoUSA identifier for this business listing. |
rating |
location |
|
Rating of the business. |
name |
location |
|
The name of the business. |
address |
location |
|
The address of the business. |
business_hours |
location |
|
The business the listing operates |
tags |
location |
|
list of tags that are associated with the listing |
tag |
tags |
id |
individual tag that is associated with the listing |
street |
address |
|
Address of business. |
city |
address |
|
City of business. |
state |
address |
|
State of business. |
postal_code |
address |
|
Zip of business. |
phone |
location |
|
Phone of business. |
latitude |
location |
|
Latitude of business. |
longitude |
location |
|
Longitude of business. |
image_url |
location |
|
The image url of business. |
histograms |
results |
name |
Each non-empty successful response contains a set of zero or more histograms |
Character data is required to be escaped, so you will likely see the character entities ", &, >, <, and '.
If you specify a location ID in addition to an offer ID, the locations result will contain only one location, the one for the location ID specified.
If you do not specify a location ID , locations will contain all locations associated with the offer, in no specific order.
XML Response
The following is an example of an XML response with blank data.
<?xml version="1.0" encoding="utf-8"?> <results total_hits="" rpp="" query_id="" page="" last_hit="" first_hit=""> <uri></uri> <did_you_mean></did_you_mean> <regions> <region type=""> <name></name> <latitude></latitude> <longitude></longitude> <default_radius></default_radius> </region> </regions> <histograms> <histogram name=""> <items> <item count="" name=""> <url></url> <tag_ids> <tag_id></tag_id> </tag_ids> </item> </items> </histogram> </histograms> <offers> <offer> <attribution_logo></attribution_logo> <attribution_text></attribution_text> <attribution_source></attribution_source> <id></id> <reference_id></reference_id> <impression_id></impression_id> <title></title> <description></description> <redemption_type_id></redemption_type_id> <redemption_type></redemption_type> <redemption_code></redemption_code> <terms></terms> <image_url></image_url> <start_date></start_date> <expiration_date></expiration_date> <popularity></popularity> <locations> <location> <id></id> <infousa_id></infousa_id> <rating></rating> <name></name> <address> <street></street> <city></city> <state></state> <postal_code></postal_code> </address> <phone></phone> <latitude></latitude> <longitude></longitude> <image_url></image_url> <business_hours></business_hours> <tags> <tag id=""></tag> <tag id=""></tag> </tags> </location> </locations> </offer> </offers> </results>
JSON Response
The following is an example of a JSON response with blank data:
{ "results" : { "query_id" : "", "uri" : "", "first_hit" : 1, "last_hit" : 2, "total_hits" : 2, "page" : 1, "rpp" : 20, "did_you_mean" : "", "regions" : [ { "type" : "", "name" : "", "latitude" : 34.10, "longitude" : -118.41, "default_radius" : 22.44 } ], "histograms" : [ { "name" : "", "items" : [ { "count" : 14, "name" : "", "uri" : "", "tag_ids" : [ { "tag_id" : 11379 } ] } ] } ], "offers" : [ { "attribution_logo" : "", "attribution_text" : "", "attribution_source" : "1", "id" : 1, "reference_id" : "1", "impression_id" : "", "title" : "", "description" : "", "redemption_type_id" : 1, "redemption_type" : "", "redemption_code" : "", "terms" : "", "image_url" : "", "start_date" : "", "expiration_date" : "", "popularity" : 10, "locations" : [ { "id" : 1, "infousa_id" : 1, "rating" : 6.0, "name" : "", "address" : { "street" : "", "city" : "", "state" : "", "postal_code" : "" }, "phone" : "", "latitude" : 34.09, "longitude" : -118.31, "image_url" : "", "business_hours" : "", "tags" : [ { "id" : 1234, "name" : "" }, { "id" : 5678, "name" : "" } ] } ] } ] } }
Notes
If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:
callback_name({"results": {...}})
Protocol Buffers Response
Google's Protocol Buffers is a format that can easily be processed by applications written in Java, C++, or Python. To use the protocol buffer format, run the protocol buffer compiler for your language on the following .proto file: offerSearch.proto. The generated classes can then be used to populate, serialize, and read protocol buffer messages.
See Google's Tutorials for information on how to compile .proto files and use the generated classes.
Spelling suggestions
A query may return spelling suggestions if it appears that the user might have misspelled a word or listing. Spelling suggestions will appear in a did_you_mean element. For example, a query containing what=computr+parts
yields:
<did_you_mean>computer parts</did_you_mean>
Histograms
Histograms provide information on how many listings are in given groups and categories.
Histograms Optional
The histograms feature will be disabled by default. If you require histograms as part of the response, then include the query parameter histograms=true in the query. Generating histograms requires additional processing and may slow down the query, so if they're not needed, leave this turned off.
Each non-empty successful response contains a set of zero or more histograms that give the number of results for each tag. Each histogram also contains uris to carry out refinement searches. For example, a search for "restaurants" around Portland, OR, will return items such as "Date Spot", "Organic", "Sea Food", etc.
The refinement URI contains a tag parameter. The value of this parameter is valid for only a short period of time and should not be relied on for anything but a subsequent search.
Error Codes
CityGrid Media provides error codes, rather than error messages. This allows you to customize the text and language for display. If a request can not be completed for any reason, an error document will be returned with a set of mnemonic error codes to help you troubleshoot the error.
A complete list of error codes follows:
Code |
Description |
---|---|
publisher.required |
The publisher parameter is missing. |
latitude.illegal |
The lat parameter was not a valid number. |
longitude.illegal |
The lon parameter was not a valid number. |
radius.illegal |
The radius parameter was not a valid number. |
radius.out.of.range |
The radius parameter was less than 1. |
rpp.out.of.range |
The rpp parameter was not in the range 1 - 25. |
page.out.of.range |
The page parameter was less than 1. |
geography.underspecified |
Neither where, lat nor lon parameters were supplied. |
geography.overspecified |
Both where and one of lat or lon parameters were supplied. |
geocode.failure |
The geocoder could not find a match for the supplied where parameter. |
startdate.illegal |
The parameter startdate was not a date in the form "yyyy-mm-dd". |
expiresbefore.illegal |
The parameter expiresbefore was not a date in the form "yyyy-mm-dd". |
popularity.illegal |
The parameter popularity was not an integer. |
sort.illegal |
The parameter sort contained an unknown value. |
type.illegal |
The parameter type contained an unknown value. |
tag.illegal |
The parameter tag was not an integer. |
date.past |
The parameter expiresbefore is in the past. |
search.region.type.illegal |
The parameter regiontype contained an unknown value. |
internal.error |
An internal problem with the service occurred. |
XML Error Response
In the XML response, the error codes are contained within errors and error tags.
Element |
Parent Element |
Description |
---|---|---|
errors |
|
Root node. A Collection of errors. |
error |
errors |
An error code. See the table of error codes above. |
For example, a request without the required publisher parameter returns the following XML:
<?xml version="1.0" encoding="UTF-8"?> <errors> <error>publisher.required</error> </errors>
JSON Error Response
In the JSON response, the error codes are values paired with error keys, as part of an errors array.
For example, a request without the required publisher parameter returns the following JSON:
{ "errors": [ { "error": "publisher.required" } ] }
Offers Detail
Introduction
The Offers Detail API provides programmatic access to CityGrid's local search engine, delivering offers, deals, and coupons for specific listings.
Detail HTTP Endpoints
The following endpoint supports HTTP GET:
http://api.citygridmedia.com/content/offers/v2/detail
Detail Request
The following query string parameters are used with the Offers API detail endpoint:
Parameter |
Description |
Required |
Valid Values |
Default |
Examples |
Notes |
---|---|---|---|---|---|---|
id |
The CityGrid ID of the offer to retrieve. |
Yes |
Postive integer |
|
1722 |
|
format |
The desired format for the results. |
No |
json |
xml |
json |
json = javascript object notation |
callback |
The name of (your own) JavaScript] function in which the JSON response should be wrapped. |
No |
|
|
display |
|
publisher |
The publisher code that identifies you. |
Yes |
|
|
acme |
|
placement |
An optional property for storing additional information you would like CityGrid Media to log for this view. |
No |
|
|
|
An example: if you run a search engine marketing campaign for, say, Google and Yahoo!, you can set the placement property to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement property to values such as "home_page" or "search" (all up to you). CityGrid will organize reports for you by placement. |
location_id |
The location ID of the offers to retrieve. |
No |
Positive integer |
|
45096544 |
Guarantees offer retrieved has location data of the location ID specified, as long as the offer with the given offer ID and location id exists. If this is not provided the location associated with the offer may not be the expected result. |
Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).
Detail Response
The Offers Detail results are returned in either XML, JSON, or Google's Protocol Buffers.
The following table describes the return XML elements (or JSON objects/keys):
Element |
Parent Element |
Attributes |
Description |
---|---|---|---|
offer |
|
|
An offer. |
attribution_logo |
offer |
|
Logo of content provider of offer. |
attribution_text |
offer |
|
Name of content provider of offer. |
attribution_source |
offer |
|
ID of content provider of offer. |
id |
offer |
|
Unique identifier for this offer. |
reference_id |
offer |
|
An internal secondary identifier for the business used for tracking. |
impression_id |
offer |
|
The internal impression id generated for tracking. |
title |
offer |
|
Short summary title for the offer. |
description |
offer |
|
Detailed description of offer. |
redemption_type_id |
offer |
|
Internal id associated with the redemption_type. |
redemption_type |
offer |
|
Possible values are Print, Online, or Both. |
redemption_code |
offer |
|
Redemption Code of the offer. |
terms |
offer |
|
Details the Terms and Conditions of the offer. |
image_url |
offer |
|
The image URL of offer on CityGrid. |
start_date |
offer |
|
Date when offer is valid. |
expiration_date |
offer |
|
Date/Time when offer expires. |
popularity |
offer |
|
The # of clicks for a month period calculated everyday overnight. |
locations |
offer |
|
The location(s) associated with the offer. |
location |
locations |
|
Details about the business associated with the offer. |
id |
location |
|
The CityGrid identifier for the business. |
infousa_id |
location |
|
The InfoUSA identifier for this business listing. |
rating |
location |
|
Rating of the business. |
name |
location |
|
The name of the business. |
address |
location |
|
The address of the business. |
street |
address |
|
Address of business. |
city |
address |
|
City of business. |
state |
address |
|
State of business. |
postal_code |
address |
|
Zip of business. |
phone |
location |
|
Phone of business. |
latitude |
location |
|
Latitude of business. |
longitude |
location |
|
Longitude of business. |
image_url |
location |
|
The image url of business. |
business_hours |
location |
|
The business hour of the business. |
tags |
location |
|
List of the tags associated with the business. |
tag |
tags |
|
The id and name of a tag that is associated with the business. |
Character data is required to be escaped, so you will likely see the character entities ", &, >, <, and '.
If you specify a location ID in addition to an offer ID, the locations result will contain only one location, the one for the location ID specified.
If you do not specify a location ID , locations will contain all locations associated with the offer, in no specific order.
XML Response
The following is an example of an XML response with blank data.
<?xml version="1.0" encoding="UTF-8"?> <offer> <attribution_logo></attribution_logo> <attribution_text></attribution_text> <attribution_source></attribution_source> <id></id> <reference_id></reference_id> <impression_id></impression_id> <title></title> <terms></terms> <description></description> <redemption_type_id></redemption_type_id> <redemption_type></redemption_type> <redemption_code></redemption_code> <image_url></image_url> <start_date></start_date> <expiration_date></expiration_date> <popularity></popularity> <locations> <location> <id></id> <infousa_id></infousa_id> <rating></rating> <name></name> <address> <street></street> <city></city> <state></state> <postal_code></postal_code> </address> <phone></phone> <latitude></latitude> <longitude></longitude> <image_url></image_url> <business_hours></business_hours> <tags> <tag id=""></tag> </tags> </location> </locations> </offer>
JSON Response
The following is an example of a JSON response with blank data:
{ "attribution_logo": "", "attribution_text": "", "attribution_source": "", "id": "", "reference_id": "", "impression_id": "", "title": "", "terms": "", "description": "", "redemption_type_id": "", "redemption_type": "", "redemption_code": "", "image_url": "", "start_date": "", "expiration_date": "", "popularity": "", "locations": [ { "id": "", "infousa_id": "", "rating": "", "name": "", "address": { "street": "", "city": "", "state": "", "postal_code": "" }, "phone": "", "latitude": "", "longitude": "", "business_hours": "", "tags": [ { "id": "", "name: "" } ] } ] }
Notes
If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:
callback_name({"results": {...}})
Protocol Buffers Response
Google's Protocol Buffers is a format that can easily be processed by applications written in Java, C++, or Python. To use the protocol buffer format, run the protocol buffer compiler for your language on the following .proto file: offerDetail.proto. The generated classes can then be used to populate, serialize, and read protocol buffer messages.
See Google's Tutorials for information on how to compile .proto files and use the generated classes.
Error Codes
CityGrid Media provides error codes, rather than error messages. This allows you to customize the text and language for display. If a request can not be completed for any reason, an error document will be returned with a set of mnemonic error codes to help you troubleshoot the error.
A complete list of error codes follows:
Code |
Description |
---|---|
publisher.required |
The publisher parameter is missing. |
offer.id.underspecified |
The parameter id was not supplied. |
offer.id.not.found |
No offer exists for the supplied id value. |
id.illegal |
The parameter id was not an integer. |
locationid.illegal |
The parameter locationid was not an integer. |
internal.error |
An internal problem with the service occurred. |
XML Error Response
In the XML response, the error codes are contained within errors and error tags.
Element |
Parent Element |
Description |
---|---|---|
errors |
|
Root node. A Collection of errors. |
error |
errors |
An error code. See the table of error codes above. |
For example, a request without the required publisher parameter returns the following XML:
<?xml version="1.0" encoding="UTF-8"?> <errors> <error>publisher.required</error> </errors>
JSON Error Response
In the JSON response, the error codes are values paired with error keys, as part of an errors array.
For example, a request without the required publisher parameter returns the following JSON:
{ "errors": [ { "error": "publisher.required" } ] }
Detail Usage Examples
The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.
Usage |
URL |
---|---|
Look up Offer with ID 71935262 |
http://api.citygridmedia.com/content/offers/v2/detail?id=71935262&publisher=test |
Look up Offer with ID 71935262 for a specific Place with ID 602842232 |