...
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 | 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 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 | 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). |
...