/
Offers API
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'html' is unknown.

Offers API

Apr 15, 2014

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:

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