Select an API to view Documentation: 


This API allows you to search events for a specific date and location.



/search_events



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 events
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:
distance:Sort results by distance.
rating:Sort results by rating.
now:Only events going on now, sorted by distance.
event_type_id integer NO Event Type ID. To get a list of Event Types, use the Event/Special Type API
keyword string NO Keyword to filter by. This will search business name, and event information for events 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
exclude_external boolean NO If this flag is true, it will exclude external events populated from Ticketmaster or Stubhub, and will only include events manually added into FindMeEvents.

Sample Request

http://www.findmespecials.com/api/search_events?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&exclude_external=true


 

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 events
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:
distance:Sort results by distance.
rating:Sort results by rating.
now:Only events going on now, sorted by distance.
event_type_id integer NO Event Type ID. To get a list of Event Types, use the Event/Special Type API
keyword string NO Keyword to filter by. This will search business name, and event information for events 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
exclude_external boolean NO If this flag is true, it will exclude external events populated from Ticketmaster or Stubhub, and will only include events manually added into FindMeEvents.

Sample Request

http://www.findmespecials.com/api/search_events?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 events 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_events?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:
status:Response Status.
page_count:Number of pages available in result.
page_size:Number of results per page
event_count:Total number of events available in result.
current_page:Current returned page.
events Node 1 Container for events
event Node 0..page_size Container for each event/event
Attributes include:
id:ID for event.
event.name string 1 for each event Name of event
event.description string 1 for each event Description of event
event.date string 1 for each event Date of event.
event.start_time string 1 for each event Start time (in local time) of event
event.utc_start_time string 1 for each event Start time of event in ISO8601 format (2010-02-25T01:00:00Z)
event.end_time string 1 for each event End time (in local time) of event
event.utc_end_time string 1 for each event End time of event in ISO8601 format (2010-02-25T01:00:00Z)
event.url string 1 for each event Url of event on FindMeSpecials
event.popularity integer 1 for each event Popularity rating of event
event.is_going_on_now boolean 1 for each event boolean (false/true) whether event is going on now
event.is_verified boolean 1 for each event boolean (false/true) whether event is verified. (Each event is returned to unverified state every 60 days and is then verified again by our editors).
event.offer_type enumeration (string) 1 for each event Type of offer. Options include:

regular - this is a regular event
featured - time based event that requires a certificate to be redeemed
chalkboard - Chalkboard event
flash - a Flash event valid only same day for a certain period of time.
one_sweet_find - One Sweet Find. Event with no time period restrictions that requires a certificate to be redeemed.
event.is_certificate_required boolean 1 for each event boolean (false/true) whether event 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.
event.repeat_info string 1 for each event If the event repeats, description of when it repeats
event.is_external boolean 1 for each event Specifies whether the event was populated externally (through Ticketmaster/Stubhub)
certificate Node 1 for each event (Only if requires certificate redemption) Container for certificate information.
event.certificate.limitations string 1 for each certificate (optional) Any limitations for certificate redemption
event.certificate..inventory_left integer 1 for each certificate (optional) Inventory left for certificate. If not present, unlimited inventory.
event..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).
event.business Node 1 for each event 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 FindMeEvents
business.photo_url string 1 for each business URL for Business Photo (75x75 thumbnail)
event_type Node 1 or 0 for each event Container for event type information
event_type.name string 1 for each event type Name of event type

 

Sample Response

      
    <?xml version="1.0" encoding="UTF-8"?>
    <response>
      <response_header current_page="1" page_count="4" page_size="20" events_count="77" status="OK"/>
      <events>
        <event id="1441198">
          <name>Music Trivia</name>
          <description>Music Trivia with bar tab prizes</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.findmeevents.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>
          <is_external>false</is_external>
          <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.findmeevents.com/locations/91002</url>
          </business>
         <event_type id="111">
            <name>General Food/Drink</name>
         </event_type>
        </event>
        <event id="1348179">
          <name>Flight of the Conchords</name>
          <description>Flight of the conchords</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.findmeevents.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>
          <is_external>true</is_external>
          <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.findmeevents.com/locations/91002</url>
          </business>
          <event_type id="111">
             <name>General Food/Drink</name>
          </event_type>
        </event>
      </events>
    </response>