Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

...

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.

...

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.

...

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. 

...