Offers API

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
#Offers Detail

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.

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 the updates made from Version 1 of the Offers APIs:

Support added for SSL
Endpoint URLs now 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.
- Added listing_id.
- Added i (impression_id).
- Added tag_op.
- Changed expiresbefore to expires_before.
- Changed customer_hasbudget to has_budget.
- Removed Accept header.
- Removed X-Publisher header.
- Removed X-Version header.
- Removed X-Placement header.
Changes to offers search response:
- Added impression_id.
- Added start_date.
- Added redemption_type.
- Added expiration_date.
- Added popularity.
- Added face_value.
- Added discount_value.
- Added location element.
- Added terms.
- Added business_hours.
- Added tags element.
- Added tag under tags element.
- Added "primary" attribute to tags.
- Added offer_type.
- Added offer_source.
- Added redemption_url.
- 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.
- Added tagop.illegal
- Added tagop.overspecified.
- Added tag.out.of.range.
- Changed geography.not.found to geocode.failure.
- Removed publisher.invalid.
Changes to detail requests:
- Added i (impression_id).
Changes to detail response:
- Added face_value.
- Added discount_value.
- Added primary attribute to tag.
Changes to detail response error codes.

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.

Offers Search consists of the following endpoints:

Where
Latitude and Longitude

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 HTTPS Endpoint

The following endpoint supports HTTPS GET:

https://api.citygridmedia.com/content/offers/v2/search/where

Where 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 sporting%20goods; plumbers	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 Pasadena,%20CA Cambridge,MA 1%20Main,Miami,FL	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 (yyyy-mm-ddThh:mi or yyyy-mm-dd)	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 (yyyy-mm-ddThh:mi or yyyy-mm-dd)		2007-08-01T23:12 2008-11-02
has_budget	Whether or not to filter the results of matching offers to customers with budget.	No	false true	true	false
sort	Sort criterion for the results.	No	dist relevance startdate expirydate popularity alpha		relevance
source	Source where offer was obtained.	No			Citysearch.com
type	Type of offers to display.	No	percentoff free dollarsoff gift buy1get1 purchase other gift printablecoupon groupbuy dailydeal		free	parameter is case insensitive, spaces removed Acceptable parameters: "percent off", "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 true	false	true	Enabling histograms will decrease performance.
format	The desired format for the results.	No	json xml pbuf	xml	json	json = javascript object notation xml = extensible markup language pbuf = Google's Protocol Buffers
callback	The name of (your own) JavaScript function in which the JSON response should be wrapped.	No			display cache
publisher	The publisher code that identifies you.	Yes			acme
placement	An optional parameter 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 parameter to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement parameter 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
i	An optional parameter for grouping API calls for tracking purposes. The parameter name is shortened from impression_id.	No				The value should be set when making subsequent calls that are related to a previously made call. The user should never supply their own generated value for the impression_id.
tag_op	An optional parameter that determines how the tags are grouped together in the search.	No	and or	and	or	In case that a list of tags is used for the search, the mentioned field defines whether you retrieve the deals that contain each one of the tags from the list (tag_op=and) or retrieve all the offers that contain at least one item of the list (tag_op=or). This search should not contain the what parameter as part of the query. The max quantity of tags in the search when using the "or" operation is 10, otherwise an error is displayed.

See the Specifying Where section in the Places API topic for more information on how to use the where endpoint.

Where 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 restaurants in Los Angeles	https://api.citygridmedia.com/content/offers/v2/search/where?what=sushi&where=los angeles,ca&publisher=test
Find offers for spas in Boston, viewing results 1-3	https://api.citygridmedia.com/content/offers/v2/search/where?what=spa&where=Boston,ma&page=1&rpp=3&publisher=test

Search Using Latitude and Longitude

The latlon endpoint allows you to search for offers using a geographic region defined by latitude and longitude.

LatLon HTTPS Endpoint

The following endpoint supports HTTPS GET:

https://api.citygridmedia.com/content/offers/v2/search/latlon

LatLon 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 sporting%20goods; plumbers	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 (yyyy-mm-ddThh:mi or yyyy-mm-dd)	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 (yyyy-mm-ddThh:mi or yyyy-mm-dd)		2007-08-01T23:12 2008-11-02
has_budget	Whether or not to filter the results of matching offers to customers with budget.	No	false true	true	false
sort	Sort criterion for the results.	No	dist relevance startdate expirydate popularity alpha		relevance
source	Source where offer was obtained.	No			Citysearch.com
type	Type of offers to display.	No	percentoff free dollarsoff gift buy1get1 purchase other		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 true	false	true	Enabling histograms will decrease performance.
format	The desired format for the results.	No	json xml pbuf	xml	json	json = javascript object notation xml = extensible markup language pbuf = Google's Protocol Buffers
callback	The name of (your own) JavaScript function in which the JSON response should be wrapped.	No			display cache
publisher	The publisher code that identifies you.	Yes			acme
placement	An optional parameter 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 parameter to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement parameter 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
i	An optional parameter for grouping API calls for tracking purposes. The parameter name is shortened from impression_id.	No				The value should be set when making subsequent calls that are related to a previously made call. The user should never supply their own generated value for the impression_id.
tag_op	An optional parameter that determines how the tags are grouped together in the search.	No	and or	and	or	In case that a list of tags is used for the search, the mentioned field defines whether you retrieve the deals that contain each one of the tags from the list (tag_op=and) or retrieve all the offers that contain at least one item of the list (tag_op=or). This search should not contain the what parameter as part of the query. The max quantity of tags in the search when using the "or" operation is 10, otherwise an error is displayed.

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 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	https://api.citygridmedia.com/content/offers/v2/search/latlon?what=sushi&lat=34.03&lon=-118.28&radius=5&publisher=test

Search Response

The Offers Search results are returned in either XML, JSON, or Google's Protocol Buffers.

The following table describes the response elements:

Element	Parent Element	Attributes	Description
results		rpp - Number of results requested per page page - Current page of results last_hit - Position of the last result in this page of results out of the total number of hits first_hit - Position of first result in this page of results out of the total number of hits total_hits - Total number of hits that matched the search query_id - Generated id associated with the search	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.
offer_type	offers		The type of the offer. (e.g. free, percent off, etc.) percentoff free dollarsoff gift buy1get1 purchase other gift printablecoupon groupbuy dailydeal
offer_source	offers		The source the offer came from.
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_url	offers		The URL to redeem 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.
face_value	offer		The real price of the offer
discount_value	offer		The price of the offer with the discount applied.
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 - tag id primary - whether the id is the primary tag id	individual tag that is associated with the listing primary=true if the tag id is the primary tag id, false if not
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 that give the number of results for each tag.

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

XML search responses are structured as follows:

<?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>
            <offer_type></offer_type>
            <offer_source></offer_source>
            <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_url></redemption_url>
            <terms></terms>
            <image_url></image_url>
            <start_date></start_date>
            <expiration_date></expiration_date>
            <popularity></popularity>
            <face_value></face_value>
            <discount_value></discount_value>
            <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="" primary="false"></tag>
                        <tag id="" primary="false"></tag>
                    </tags>
                </location>
            </locations>
        </offer>
    </offers>
</results>

JSON Response

JSON search responses are structured as follows:

{
    "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",
                "offer_type" : "free",
                "offer_source" : "citysearch",
                "id" : 1,
                "reference_id" : "1",
                "impression_id" : "",
                "title" : "",
                "description" : "",
                "redemption_type_id" : 1,
                "redemption_type" : "",
                "redemption_url" : "citysearch.com",
                "terms" : "",
                "image_url" : "",
                "start_date" : "",
                "expiration_date" : "",
                "popularity" : 10,
                "face_value" : "",
                "discount_value" : "",
                "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" : "",
                                "primary" : false
                            },
                            {
                                "id" : 5678,
                                "name" : "",
                                "primary" : false
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

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 this proto file. 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.

Search Error Reporting

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.

Error Codes

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.
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.
tagop.illegal	The parameter tag_op value was not "and" or "or"
tagop.overspecified	What parameter, one or more tag parameters, and tag_op parameter with value of "or" supplied
tag.out.of.range	Tag_op parameter with value of "or" and limit of allowed tag parameters exceeded

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

The Offers Detail API provides programmatic access to CityGrid's local search engine, delivering offers, deals, and coupons for specific listings.

Detail HTTPS Endpoint

The following endpoint supports HTTPS GET:

https://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 pbuf	xml	json	json = javascript object notation xml = extensible markup language pbuf = Google's Protocol Buffers
callback	The name of (your own) JavaScript] function in which the JSON response should be wrapped.	No			display cache
publisher	The publisher code that identifies you.	Yes			acme
placement	An optional parameter 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 parameter to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement parameter 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.
i	An optional parameter for grouping API calls for tracking purposes. The parameter name is shortened from impression_id.	No				The value should be set when making subsequent calls that are related to a previously made call. The user should never supply their own generated value for the impression_id.

Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).

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 cg_64232690	https://api.citygridmedia.com/content/offers/v2/detail?id=cg_64232690&publisher=test
Look up Offer with id cg_64232690for a specific Place with id 41453536	https://api.citygridmedia.com/content/offers/v2/detail?id=cg_64232690&location_id=41453536&publisher=test

Detail Response

The Offers Detail results are returned in either XML, JSON, or Google's Protocol Buffers.

The following table describes the response elements:

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.
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.
face_value	offer		The real price of the offer
discount_value	offer		The price of the offer with the discount applied.
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	id - tag id primary - whether the id is the primary tag id	The id and name of a tag that is associated with the business, and whether the tag is the primary tag or not.

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

XML detail responses are structured as follows:

<?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>
    <image_url></image_url>
    <start_date></start_date>
    <expiration_date></expiration_date>
    <popularity></popularity>
    <face_value></face_value>
    <discount_value></discount_value>
    <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="" primary="false"></tag>
	    </tags>
	</location>
    </locations>
</offer>

JSON Response

JSON detail responses are structured as follows:

{
    "attribution_logo": "",
    "attribution_text": "",
    "attribution_source": "",
    "id": "",
    "reference_id": "",
    "impression_id": "",
    "title": "",
    "terms": "",
    "description": "",
    "redemption_type_id": "",
    "redemption_type": "",
    "image_url": "",
    "start_date": "",
    "expiration_date": "",
    "popularity": "",
    "face_value" : "",
    "discount_value" : "",
    "locations": [ {
        "id": "",
        "infousa_id": "",
        "rating": "",
        "name": "",
        "address": {
            "street": "",
            "city": "",
            "state": "",
            "postal_code": ""
        },
        "phone": "",
        "latitude": "",
        "longitude": "",
        "business_hours": "",
        "tags": [
        {
            "id": ,
            "name": "",
            "primary": false
        }
        ]
    } ]
}

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 this proto file. 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.

Detail Error Reporting

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.

Error Codes

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"
        }
    ]
}

CityGrid V2

Offers API

Introduction

Contents

Audience

Version 2 Updates

Offers Search

Search Using Where

Where HTTPS Endpoint

Where Request

Where Usage Examples

Search Using Latitude and Longitude

LatLon HTTPS Endpoint

LatLon Request

Notes

LatLon Usage Examples

Search Response

XML Response

JSON Response

Notes

Protocol Buffers Response

Spelling Suggestions

Histograms

Search Error Reporting

Error Codes

XML Error Response

JSON Error Response

Offers Detail

Detail HTTPS Endpoint

Detail Request

Detail Usage Examples

Detail Response

XML Response

JSON Response

Notes

Protocol Buffers Response

Detail Error Reporting

Error Codes

XML Error Response

JSON Error Response