Skip to end of metadata
Go to start of metadata

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.

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 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:

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:

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.

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:

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.

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:

JSON Response

JSON search responses are structured as follows:

Notes

If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:

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:

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:

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:

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:

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.

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:

JSON Response

JSON detail responses are structured as follows:

Notes

If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:

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:

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:

Labels
  • None