API Method /demands/search

This function handles demand search. It performs the requested search, returning the results as an XML file. See the search box at http://eventful.com/demand for an example interface.

Arguments

authentication
This method controls access via authentication.
keywords string
The search keywords. (optional)
location string
A location name to use in filtering the search results. Locations in the form "San Diego", "San Diego, TX", "London, United Kingdom", and "Calgary, Alberta, Canada" are accepted, as are postal codes ("92122"). (optional)
count_only boolean
If count_only is set, an abbreviated version of the output will be returned. Only total_items and search_time elements are included in the result. (optional)
sort_order string
One of 'relevance', 'name', 'category', 'member_count', 'performer', or 'created' (optional)
sort_direction string
One of 'ascending' or 'descending'. Default is 'ascending'. (optional)
page_size integer
The desired number of results per page. Maximum 100, defaults to 20. (optional)
page_number integer
The desired page number. (optional)

Example Request

Here's an example search URL:

http://api.eventful.com/rest/demands/search?...&keywords=wil+wheaton

Output Parameters

Output from this function is an XML block with the following constructs:
total_items integer
The total number of demands matching this search. This can be an approximation if we wish.
page_size integer
The number of demands per "page" returned.
page_count integer
The number of "pages" of output.
page_number integer
The current "page" number.
page_items integer
The number of demands returned in this block. This is not necessarly the same as page_size. The last page, for instance, will probably not be a full page.
first_item integer
The item number of the first element on this page.
last_item integer
The item number of the last element on this page.
search_time float
The fractional number of seconds it took to satisfy this query.
demands array
An array of page_items demands. Each demand entry has the following structure:
id string
The unique ID for this demand.
description string
The demand description.
status string
The current status of the demand. (e.g. 'demanded', 'criticalmass')
location string
member_count integer
The number of members who have joined this demand to date.
user_is_member boolean
If an authenticated user is specified, this is set true if the user has joined this demand.
comment_count integer
The number of comments on this demand.
created datetime
The date & time the demand was initially created. (e.g. '2006-03-17 16:55:00')
creator string
The username of the demand's creator.
performer struct
A performer entry with the following structure:
id string
The performer ID for this demand.
name string
The name of this performer.
image struct
An image entry

Example XML Response

<?xml version="1.0" encoding="UTF-8"?>
<search version="0.2">
  <total_items>76</total_items>
  <page_size>10</page_size>
  <page_count>8</page_count>
  <page_number>1</page_number>
  <page_items>10</page_items>
  <first_item>1</first_item>
  <last_item>10</last_item>
  <search_time>0.002</search_time>
  <demands>
    <demand>
      <id>D0-001-000000119-6</id>
      <description>Sketch comedy, stand-up, poker, readings...</description>
      <status>demanded</status>
      <location>Baltimore, Maryland, USA</location>
      <member_count>4</member_count>
      <user_is_member>0</user_is_member>
      <comment_count>1</comment_count>
      <created>2006-03-14 06:51:42</created>
      <creator>fferret</creator>
      <performer>
        <id>P0-001-000000567-9</id>
        <name>Wil Wheaton</name>
      </performer>
      <image>
        <caption/>
        <thumb>
          <url>http://images.evdb.com/images/thumb/I0-001/000/070/464-6.jpg</url>
          <width>48</width>
          <height>48</height>
        </thumb>
        <small>
          <url>http://images.evdb.com/images/small/I0-001/000/070/464-6.jpeg</url>
          <width>48</width>
          <height>58</height>
        </small>
        <medium>
          <url>http://images.evdb.com/images/medium/I0-001/000/070/464-6.jpeg</url>
          <width>128</width>
          <height>154</height>
        </medium>
      </image>
      <events/>
    </demand>
    ...
  </demands>
</search>

Error Codes

This method may return these errors in an error document:

Authentication error
The specified user was not found or provided invalid credentials.
Missing parameter
Either the 'keywords' or 'location' parameter is required.