Select an API to view Documentation:
This API allows you to search specials for a specific date and location.
/search_specials
Search By Geocode and Radius
| Name | Data Type | Required | Description | ||||||
|---|---|---|---|---|---|---|---|---|---|
| api_key | string | YES | API Key that was given to you at API registration | ||||||
| version | string | YES | Version of the API (Current version = 2) | ||||||
| lat | double | YES | Latitude to use as search center | ||||||
| lng | double | YES | Longitude to use as search center | ||||||
| date | date | YES | Date to search for specials | ||||||
| search_radius | double | NO | Search radius in miles to use for search. Maximum = 25 miles. | ||||||
| page | integer | YES | Page number of result. Results are returned 20 at a time. | ||||||
| search_type | string | NO | Type of search. Options include:
|
||||||
| special_type_id | integer | NO | Special Type ID. To get a list of Special Types, use the Event/Special Type API | ||||||
| keyword | string | NO | Keyword to filter by. This will search business name, and special information for specials on specified date. | ||||||
| verified_only | boolean | NO | If this value is 'true', only return verified specials, and only ones that have been validated in the last 30 days. (default is 'false' - return verified specials, but also ones that may have not been validated in the last 30 days). | ||||||
| exclusive_only | boolean | NO | If true, only returns exclusive content such as One Sweet Finds , Flash Specials, Time-Based Coupons, and Today's Chalks |
Sample Request
http://www.findmespecials.com/api/search_specials?api_key=YOUR_KEY&version=2&lat=32.909078&lng=-96.690931&search_radius=10.0&date=02/24/2010&page=1&search_type=distance
Search by Address:
| Name | Data Type | Required | Description | ||||||
|---|---|---|---|---|---|---|---|---|---|
| api_key | string | YES | API Key that was given to you at API registration | ||||||
| version | string | YES | Version of the API (Current version = 2) | ||||||
| location | string | YES | Address to search | ||||||
| date | date | YES | Date to search for specials | ||||||
| search_radius | double | NO | Search radius in miles to use for search. Maximum = 25 miles. | ||||||
| page | integer | YES | Page number of result. Results are returned 20 at a time. | ||||||
| search_type | string | NO | Type of search. Options include:
|
||||||
| event_type_id | integer | NO | Special Type ID. To get a list of Special Types, use the Event/Special Type API | ||||||
| keyword | string | NO | Keyword to filter by. This will search business name, and special information for specials on specified date. | ||||||
| verified_only | boolean | NO | If this value is 'true', only return verified specials, and only ones that have been validated in the last 30 days. (default is 'false' - return verified specials, but also ones that may have not been validated in the last 30 days). | ||||||
| exclusive_only | boolean | NO | If true, only returns exclusive content such as One Sweet Finds , Flash Specials, Time-Based Coupons, and Today's Chalks |
Sample Request
http://www.findmespecials.com/api/search_specials?api_key=YOUR_KEY&version=2&location=30309&search_radius=10.0&date=02/24/2010&page=1&search_type=distance
Search by Business:
You can retrieve all future specials for a specific business.
| Name | Data Type | Required | Description |
|---|---|---|---|
| api_key | string | YES | API Key that was given to you at API registration |
| version | string | YES | Version of the API (Current version = 2) |
| business_id | integer | YES | Business ID to search |
| page | integer | YES | Page number of result. Results are returned 20 at a time. |
Sample Request
http://www.findmespecials.com/api/search_specials?api_key=YOUR_KEY&version=2&business_id=3&page=1
Response Values
| Response Node | Data Type | Number of times occuring | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| response | Node | 1 | Response body | ||||||||||
| response_header | Node | 1 |
Response summary. Attributes include:
|
||||||||||
| specials | Node | 1 | Container for specials | ||||||||||
| special | Node | 0..page_size | Container for each event/special Attributes include:
|
||||||||||
| special.name | string | 1 for each special | Name of special | ||||||||||
| special.description | string | 1 for each special | Description of special | ||||||||||
| special.date | string | 1 for each special | Date of special. | ||||||||||
| special.start_time | string | 1 for each special | Start time (in local time) of special | ||||||||||
| special.utc_start_time | string | 1 for each special | Start time of special in ISO8601 format (2010-02-25T01:00:00Z) | ||||||||||
| special.end_time | string | 1 for each special | End time (in local time) of special | ||||||||||
| special.utc_end_time | string | 1 for each special | End time of special in ISO8601 format (2010-02-25T01:00:00Z) | ||||||||||
| special.url | string | 1 for each special | Url of special on FindMeEvents | ||||||||||
| special.popularity | integer | 1 for each special | Popularity rating of special | ||||||||||
| special.is_going_on_now | boolean | 1 for each special | boolean (false/true) whether special is going on now | ||||||||||
| special.is_verified | boolean | 1 for each special | boolean (false/true) whether special is verified. (Each special is returned to unverified state every 60 days and is then verified again by our editors). | ||||||||||
| special.offer_type | enumeration (string) | 1 for each special | Type of offer. Options include:
regular - this is a regular special featured - time based special that requires a certificate to be redeemed chalkboard - Chalkboard special flash - a Flash special valid only same day for a certain period of time. one_sweet_find - One Sweet Find. Special with no time period restrictions that requires a certificate to be redeemed. |
||||||||||
| special.is_certificate_required | boolean | 1 for each special | boolean (false/true) whether special requires a user to grab and use a certificate for it to be redeemed. This should be clearly marked in the display to indicate to users they need a certificate. | ||||||||||
| special.repeat_info | string | 1 for each special | If the special repeats, description of when it repeats | ||||||||||
| certificate | Node | 1 for each special (Only if requires certificate redemption) | Container for certificate information. | ||||||||||
| special.certificate.limitations | string | 1 for each certificate (optional) | Any limitations for certificate redemption | ||||||||||
| special.certificate..inventory_left | integer | 1 for each certificate (optional) | Inventory left for certificate. If not present, unlimited inventory. | ||||||||||
| special..certificate.expiration_date | date | 1 for each certificate (optional) | Date that certificate expires. If not present, open ended. This does not take into account user specific expiration dates (expiration days after claim or use). | ||||||||||
| special.business | Node | 1 for each special | Container for business information | ||||||||||
| business.name | string | 1 for each business | Business name | ||||||||||
| business.address | string | 1 for each business | Business Address | ||||||||||
| business.city | string | 1 for each business | Business City | ||||||||||
| business.state | string | 1 for each business | Business State | ||||||||||
| business.zip | string | 1 for each business | Business Zip | ||||||||||
| business.distance | string | 1 for each business | Distance from Geocoded center | ||||||||||
| business.lat | double | 1 for each business | Latitude of business | ||||||||||
| business.lng | double | 1 for each business | Longitude of business | ||||||||||
| business.phone | string | 1 for each business | Business phone number | ||||||||||
| business.website | string | 1 for each business | Business website | ||||||||||
| business.url | string | 1 for each business | Url of Business on FindMeSpecials | ||||||||||
| business.photo_url | string | 1 for each business | URL for Business Photo (75x75 thumbnail) | ||||||||||
| special_type | Node | 1 or 0 for each special | Container for special type information | ||||||||||
| special_type.name | string | 1 for each special type | Name of special type |
Sample Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<response_header current_page="1" page_count="4" page_size="20" specials_count="77" status="OK"/>
<specials>
<special id="1441198">
<name>$2.25 Drafts, $4 Margaritas and More</name>
<description>At the bar only-drafts/reg $3.50, large blue margaritas, mojitos $8.75-$10.50.</description>
<date>02/24/2010</date>
<start_time>10:00 AM</start_time>
<utc_start_time>2010-02-24T15:00:00Z</utc_start_time>
<end_time>8:00 PM</end_time>
<utc_end_time>2010-02-25T01:00:00Z</utc_end_time>
<url>http://www.findmespecials.com/public_events/1441198</url>
<popularity>4</popularity>
<is_going_on_now>false</is_going_on_now>
<offer_type>regular</offer_type>
<is_verified>true</is_verified>
<repeat_info>Repeats Weekly on Monday, Tuesday, Wednesday, Thursday, Friday </repeat_info>
<business id="91002">
<name>Blue Mesa</name>
<address>7700 W Northwest Hwy</address>
<city>Dallas</city>
<state>TX</state>
<zip>75225</zip>
<lat>33.742382</lat>
<lng>-84.373352</lng>
<distance>3.53152092672317</distance>
<phone>(214) 378 8686</phone>
<website>http://www.bluemesagrill.com/</website>
<url>http://www.findmespecials.com/locations/91002</url>
</business>
<special_type id="111">
<name>General Food/Drink</name>
</special_type>
</special>
<special id="1348179">
<name>$10.95 Southwestern Lunch Buffet</name>
<description>Buffet includes: Steak and Chicken fajitas, Grilled salmon, and more.</description>
<date>02/24/2010</date>
<start_time>10:00 AM</start_time>
<utc_start_time>2010-02-24T15:00:00Z</utc_start_time>
<end_time>8:00 PM</end_time>
<utc_end_time>2010-02-25T01:00:00Z</utc_end_time>
<url>http://www.findmespecials.com/public_events/1348179</url>
<popularity>1</popularity>
<is_going_on_now>false</is_going_on_now>
<offer_type>featured</offer_type>
<is_verified>true</is_verified>
<is_certificate_required>true</is_certificate_required>
<certificate special_id="2808295" id="168">
<limitations>One certificate per table.</limitations>
<inventory_left>25</inventory_left>
<expiration_date>02/01/2011</expiration_date>
</certificate>
<business id="91002">
<name>Blue Mesa</name>
<address>7700 W Northwest Hwy</address>
<city>Dallas</city>
<state>TX</state>
<zip>75225</zip>
<lat>33.742388</lat>
<lng>-84.373358</lng>
<distance>3.53152092672317</distance>
<phone>(214) 378 8686</phone>
<website>http://www.bluemesagrill.com/</website>
<url>http://www.findmespecials.com/locations/91002</url>
</business>
<special_type id="111">
<name>General Food/Drink</name>
</special_type>
</special>
</specials>
</response>
