documentation/manual/en/module_specs/Zend_Service_Twitter_Search.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.service.twitter.search">
   4     <title>Zend_Service_Twitter_Search</title>
   5
   6     <sect3 id="zend.service.twitter.search.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Service_Twitter_Search</classname> provides a client for the
  11             <ulink url="http://apiwiki.twitter.com/Search+API+Documentation">Twitter Search
  12             <acronym>API</acronym></ulink>. The Twitter Search service is use to search Twitter.
  13             Currently, it only returns data in Atom or <acronym>JSON</acronym> format, but a full
  14             <acronym>REST</acronym> service is in the future, which will support
  15             <acronym>XML</acronym> responses.
  16         </para>
  17     </sect3>
  18
  19     <sect3 id="zend.service.twitter.search.trends">
  20         <title>Twitter Trends</title>
  21
  22         <para>
  23             Returns the top ten queries that are currently trending on Twitter. The response
  24             includes the time of the request, the name of each trending topic, and the url to the
  25             Twitter Search results page for that topic. Currently the search <acronym>API</acronym>
  26             for trends only supports a <acronym>JSON</acronym> return so the function returns
  27             an array.
  28         </para>
  29
  30         <programlisting language="php"><![CDATA[
  31 $twitterSearch  = new Zend_Service_Twitter_Search();
  32 $twitterTrends  = $twitterSearch->trends();
  33
  34 foreach ($twitterTrends as $trend) {
  35     print $trend['name'] . ' - ' . $trend['url'] . PHP_EOL
  36 }
  37 ]]></programlisting>
  38
  39         <para>
  40             The return array has two values in it:
  41         </para>
  42
  43         <itemizedlist>
  44             <listitem>
  45                 <para>
  46                     <code>name</code> is the name of trend.
  47                 </para>
  48             </listitem>
  49
  50             <listitem>
  51                 <para>
  52                     <code>url</code> is the <acronym>URL</acronym> to see the tweets for
  53                     that trend.
  54                 </para>
  55             </listitem>
  56         </itemizedlist>
  57     </sect3>
  58
  59     <sect3 id="zend.service.twitter.search.search">
  60         <title>Searching Twitter</title>
  61
  62         <para>
  63             Using the search method returns tweets that match a specific query. There are a number
  64             of <ulink url="http://search.twitter.com/operators">Search Operators</ulink> that you
  65             can use to query with.
  66         </para>
  67
  68         <para>
  69             The search method can accept six different optional <acronym>URL</acronym> parameters
  70             passed in as an array:
  71         </para>
  72
  73         <itemizedlist>
  74             <listitem>
  75                 <para>
  76                     <code>lang</code> restricts the tweets to a given language. <code>lang</code>
  77                     must be given by an
  78                     <ulink url="http://en.wikipedia.org/wiki/ISO_639-1">ISO 639-1 code</ulink>.
  79                 </para>
  80             </listitem>
  81
  82             <listitem>
  83                 <para>
  84                     <code>rpp</code> is the number of tweets to return per page, up to a maximum
  85                     of 100.
  86                 </para>
  87             </listitem>
  88
  89             <listitem>
  90                 <para>
  91                     <code>page</code> specifies the page number to return, up to a maximum of
  92                     roughly 1500 results (based on rpp * page).
  93                 </para>
  94             </listitem>
  95
  96             <listitem>
  97                 <para>
  98                     <code>since_id</code> returns tweets with status IDs greater than the given ID.
  99                 </para>
 100             </listitem>
 101
 102             <listitem>
 103                 <para>
 104                     <code>show_user</code> specifies whether to add "&gt;user&lt;:" to the
 105                     beginning of the tweet. This is useful for readers that do not display Atom's
 106                     author field. The default is "<constant>FALSE</constant>".
 107                 </para>
 108             </listitem>
 109
 110             <listitem>
 111                 <para>
 112                     <code>geocode</code> returns tweets by users located within a given radius of
 113                     the given latitude/longitude, where the user's location is taken from their
 114                     Twitter profile. The parameter value is specified by
 115                     "latitude,longitude,radius", where radius units must be specified as either
 116                     "mi" (miles) or "km" (kilometers).
 117                 </para>
 118             </listitem>
 119         </itemizedlist>
 120
 121         <example id="zend.service.twitter.search.search.json">
 122             <title>JSON Search Example</title>
 123
 124             <para>
 125                 The following code sample will return an array with the search results.
 126             </para>
 127
 128             <programlisting language="php"><![CDATA[
 129 $twitterSearch  = new Zend_Service_Twitter_Search('json');
 130 $searchResults  = $twitterSearch->search('zend', array('lang' => 'en'));
 131 ]]></programlisting>
 132         </example>
 133
 134         <example id="zend.service.twitter.search.search.atom">
 135             <title>ATOM Search Example</title>
 136
 137             <para>
 138                 The following code sample will return a <classname>Zend_Feed_Atom</classname>
 139                 object.
 140             </para>
 141
 142             <programlisting language="php"><![CDATA[
 143 $twitterSearch  = new Zend_Service_Twitter_Search('atom');
 144 $searchResults  = $twitterSearch->search('zend', array('lang' => 'en'));
 145 ]]></programlisting>
 146         </example>
 147     </sect3>
 148
 149     <sect3 id="zend.service.twitter.search.accessors">
 150         <title>Zend-specific Accessor Methods</title>
 151
 152         <para>
 153             While the Twitter Search <acronym>API</acronym> only specifies two methods,
 154             <classname>Zend_Service_Twitter_Search</classname> has additional methods that may be
 155             used for retrieving and modifying internal properties.
 156         </para>
 157
 158         <itemizedlist>
 159             <listitem>
 160                 <para>
 161                     <methodname>getResponseType()</methodname> and
 162                     <methodname>setResponseType()</methodname>
 163                     allow you to retrieve and modify the response type of the search between
 164                     <acronym>JSON</acronym> and Atom.
 165                 </para>
 166             </listitem>
 167         </itemizedlist>
 168     </sect3>
 169 </sect2>
 170 <!--
 171 vim:se ts=4 sw=4 et:
 172 -->