repo_zf1/documentation/manual/en/module_specs/Zend_Service_Twitter_Search.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.service.twitter.search">
    <title>Zend_Service_Twitter_Search</title>

    <sect3 id="zend.service.twitter.search.introduction">
        <title>Introduction</title>

        <para>
            <classname>Zend_Service_Twitter_Search</classname> provides a client for the
            <ulink url="http://apiwiki.twitter.com/Search+API+Documentation">Twitter Search
            <acronym>API</acronym></ulink>. The Twitter Search service is use to search Twitter.
            Currently, it only returns data in Atom or <acronym>JSON</acronym> format, but a full
            <acronym>REST</acronym> service is in the future, which will support
            <acronym>XML</acronym> responses.
        </para>
    </sect3>

    <sect3 id="zend.service.twitter.search.trends">
        <title>Twitter Trends</title>

        <para>
            Returns the top ten queries that are currently trending on Twitter. The response
            includes the time of the request, the name of each trending topic, and the url to the
            Twitter Search results page for that topic. Currently the search <acronym>API</acronym>
            for trends only supports a <acronym>JSON</acronym> return so the function returns
            an array.
        </para>

        <programlisting language="php"><![CDATA[
$twitterSearch  = new Zend_Service_Twitter_Search();
$twitterTrends  = $twitterSearch->trends();

foreach ($twitterTrends as $trend) {
    print $trend['name'] . ' - ' . $trend['url'] . PHP_EOL
}
]]></programlisting>

        <para>
            The return array has two values in it:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>name</code> is the name of trend.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>url</code> is the <acronym>URL</acronym> to see the tweets for
                    that trend.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.service.twitter.search.search">
        <title>Searching Twitter</title>

        <para>
            Using the search method returns tweets that match a specific query. There are a number
            of <ulink url="http://search.twitter.com/operators">Search Operators</ulink> that you
            can use to query with.
        </para>

        <para>
            The search method can accept six different optional <acronym>URL</acronym> parameters
            passed in as an array:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>lang</code> restricts the tweets to a given language. <code>lang</code>
                    must be given by an
                    <ulink url="http://en.wikipedia.org/wiki/ISO_639-1">ISO 639-1 code</ulink>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>rpp</code> is the number of tweets to return per page, up to a maximum
                    of 100.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>page</code> specifies the page number to return, up to a maximum of
                    roughly 1500 results (based on rpp * page).
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>since_id</code> returns tweets with status IDs greater than the given ID.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>show_user</code> specifies whether to add "&gt;user&lt;:" to the
                    beginning of the tweet. This is useful for readers that do not display Atom's
                    author field. The default is "<constant>FALSE</constant>".
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>geocode</code> returns tweets by users located within a given radius of
                    the given latitude/longitude, where the user's location is taken from their
                    Twitter profile. The parameter value is specified by
                    "latitude,longitude,radius", where radius units must be specified as either
                    "mi" (miles) or "km" (kilometers).
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.service.twitter.search.search.json">
            <title>JSON Search Example</title>

            <para>
                The following code sample will return an array with the search results.
            </para>

            <programlisting language="php"><![CDATA[
$twitterSearch  = new Zend_Service_Twitter_Search('json');
$searchResults  = $twitterSearch->search('zend', array('lang' => 'en'));
]]></programlisting>
        </example>

        <example id="zend.service.twitter.search.search.atom">
            <title>ATOM Search Example</title>

            <para>
                The following code sample will return a <classname>Zend_Feed_Atom</classname>
                object.
            </para>

            <programlisting language="php"><![CDATA[
$twitterSearch  = new Zend_Service_Twitter_Search('atom');
$searchResults  = $twitterSearch->search('zend', array('lang' => 'en'));
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.service.twitter.search.accessors">
        <title>Zend-specific Accessor Methods</title>

        <para>
            While the Twitter Search <acronym>API</acronym> only specifies two methods,
            <classname>Zend_Service_Twitter_Search</classname> has additional methods that may be
            used for retrieving and modifying internal properties.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getResponseType()</methodname> and
                    <methodname>setResponseType()</methodname>
                    allow you to retrieve and modify the response type of the search between
                    <acronym>JSON</acronym> and Atom.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->