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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.ebay.finding">
    <title>Zend_Service_Ebay_Finding</title>

    <sect2 id="zend.service.ebay.finding.introduction">
        <title>Introduction</title>

        <para>
            <classname>Zend_Service_Ebay_Finding</classname> provides a client
            for the <ulink url="http://developer.ebay.com/DevZone/finding/CallRef/index.html">eBay Finding</ulink>.
            Per eBay website, "The Finding API provides programmatic access to
            the next generation search capabilities on the eBay platform. It
            lets you search and browse for items listed on eBay, and provides
            useful metadata to refine searches and enhance the search experience."
        </para>

        <para>
            In order to use <classname>Zend_Service_Ebay_Finding</classname>,
            you should already have an eBay Application ID. To get a key and for
            more information, please visit the
            <ulink url="https://developer.ebay.com/Join/default.aspx">eBay Developers Program</ulink>
            web site.
        </para>
    </sect2>

    <sect2 id="zend.service.ebay.finding.factoring">
        <title>Create a client object</title>

        <para>
            Instantiate a <classname>Zend_Service_Ebay_Finding</classname> object,
            passing it your private keys:
        </para>
        <example id="zend.service.ebay.finding.factoring.sample-1">
            <title>Creating an instance of the eBay Finding service</title>
            <programlisting language="php"><![CDATA[
$finding = new Zend_Service_Ebay_Finding('my-app-id');
]]></programlisting>
        </example>

        <para>
            Instantiate a <classname>Zend_Service_Ebay_Finding</classname> object,
            passing it your private keys and setting options:
        </para>
        <example id="zend.service.ebay.finding.factoring.sample-2">
            <title>Creating an instance of the eBay Finding service</title>
            <programlisting language="php"><![CDATA[
$options = array(Zend_Service_Ebay_Abstract::OPTION_APP_ID    => 'my-app-id',
                 Zend_Service_Ebay_Abstract::OPTION_GLOBAL_ID => 'EBAY-GB');
$finding = new Zend_Service_Ebay_Finding($options);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.ebay.finding.items">
        <title>Finding items</title>

        <para>
            There are five available methods to search items:
            <itemizedlist>
                <listitem>
                    <para>findItemsByKeywords($keywords)</para>
                </listitem>
                <listitem>
                    <para>findItemsByProduct($productId)</para>
                </listitem>
                <listitem>
                    <para>findItemsByCategory($categoryId)</para>
                </listitem>
                <listitem>
                    <para>findItemsAdvanced($keywords)</para>
                </listitem>
                <listitem>
                    <para>findItemsInEbayStores($storeName)</para>
                </listitem>
            </itemizedlist>
        </para>

        <example id="zend.service.ebay.finding.items.sample">
            <title>Many ways to find items</title>
            <programlisting language="php"><![CDATA[
$finding  = new Zend_Service_Ebay_Finding('my-app-id');
$response = $finding->findItemsByKeywords('zend framework book');
foreach ($response->searchResult->item as $item) {
    $item->title;
    $item->listingInfo->buyItNowPrice;
    $item->listingInfo->viewItemURL;

    // inner call, find for items of same current product
    // like $finding->findItemsByProduct($item->productId, $item->attributes('productId', 'type'))
    $response2 = $item->findItemsByProduct($finding);

    // inner call, find for items of same store
    // like $finding->findItemsInEbayStores($item->storeInfo->storeName)
    $response3 = $item->storeInfo->findItems($finding);
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.ebay.finding.keywords-recomendation">
        <title>Keywords Recommendation</title>

        <para>
            This operation checks specified keywords and returns correctly
            spelled keywords for best search results.
        </para>

        <example id="zend.service.ebay.finding.keywords.sample">
            <title>Searching keywords recomendation</title>
            <programlisting language="php"><![CDATA[
// searching keywords
$finding = new Zend_Service_Ebay_Finding('my-app-id');
$result  = $finding->getSearchKeywordsRecommendation('zend');
echo 'Did you mean ' . $result->keyword . '?';

// inner call
// like $finding->findItemsByKeywords($result->keyword)
$result2 = $result->findItems($finding);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.ebay.finding.histogram">
        <title>Histograms</title>

        <para>
            Per eBay website, this operation "category and/or aspect histogram
            information for the eBay category ID you specify. Histograms are
            item counts for the associated category or aspect value. Input
            category ID numbers in the request using the categoryId field".
        </para>

        <example id="zend.service.ebay.finding.histogram.sample">
            <title>Fetching histogram</title>
            <programlisting language="php"><![CDATA[
$finding = new Zend_Service_Ebay_Finding('my-app-id');
$result  = $finding->getHistograms($categoryId);

foreach ($result->categoryHistogramContainer->categoryHistogram as $category) {
    $category->categoryId;
    $category->categoryName;

    // inner call
    // like $finding->findItemsByCategory($category->categoryId);
    $result2 = $category->findItems($finding);
}
]]></programlisting>
        </example>
    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->