src/Buy/Browse/V1/Api/ItemSummaryApi.php
<?php
/**
* This file is part of the trollandtoad/ebay-sdk-php package.
*
* MIT License
*
* Copyright (c) 2022 Brandon Clothier
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
*/
declare(strict_types=1);
/**
* ItemSummaryApi.
*
* PHP version ^7.2 || ^8.0
*
* @category Class
*
* @author OpenAPI Generator team
*
* @see https://openapi-generator.tech
*/
/**
* Browse API.
*
* <p>The Browse API has the following resources:</p> <ul> <li><b> item_summary: </b> Lets shoppers search for specific items by keyword, GTIN, category, charity, product, or item aspects and refine the results by using filters, such as aspects, compatibility, and fields values.</li> <li><b> search_by_image: </b><a href=\"https://developer.ebay.com/api-docs/static/versioning.html#experimental \" target=\"_blank\"><img src=\"/cms/img/docs/experimental-icon.svg\" class=\"legend-icon experimental-icon\" alt=\"Experimental Release\" title=\"Experimental Release\" /> (Experimental)</a> Lets shoppers search for specific items by image. You can refine the results by using URI parameters and filters.</li> <li><b> item: </b> <ul><li>Lets you retrieve the details of a specific item or all the items in an item group, which is an item with variations such as color and size and check if a product is compatible with the specified item, such as if a specific car is compatible with a specific part.</li> <li>Provides a bridge between the eBay legacy APIs, such as <b> Finding</b>, and the RESTful APIs, which use different formats for the item IDs.</li> </ul> </li> <li> <b> shopping_cart: </b> <a href=\"https://developer.ebay.com/api-docs/static/versioning.html#experimental \" target=\"_blank\"><img src=\"/cms/img/docs/experimental-icon.svg\" class=\"legend-icon experimental-icon\" alt=\"Experimental Release\" title=\"Experimental Release\" /> (Experimental)</a> <a href=\"https://developer.ebay.com/api-docs/static/versioning.html#limited \" target=\"_blank\"> <img src=\"/cms/img/docs/partners-api.svg\" class=\"legend-icon partners-icon\" title=\"Limited Release\" alt=\"Limited Release\" />(Limited Release)</a> Provides the ability for eBay members to see the contents of their eBay cart, and add, remove, and change the quantity of items in their eBay cart. <b> Note: </b> This resource is not available in the eBay API Explorer.</li></ul> <p>The <b> item_summary</b>, <b> search_by_image</b>, and <b> item</b> resource calls require an <a href=\"/api-docs/static/oauth-client-credentials-grant.html\">Application access token</a>. The <b> shopping_cart</b> resource calls require a <a href=\"/api-docs/static/oauth-authorization-code-grant.html\">User access token</a>.</p>
*
* The version of the OpenAPI document: v1.18.0
* Generated by: https://openapi-generator.tech
* OpenAPI Generator version: 5.4.0
*/
/**
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
*/
namespace TNT\Ebay\Buy\Browse\V1\Api;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\RequestOptions;
use GuzzleHttp\ClientInterface;
use GuzzleHttp\Psr7\MultipartStream;
use TNT\Ebay\Buy\Browse\V1\ApiException;
use GuzzleHttp\Exception\GuzzleException;
use TNT\Ebay\Buy\Browse\V1\Configuration;
use GuzzleHttp\Exception\ConnectException;
use GuzzleHttp\Exception\RequestException;
use TNT\Ebay\Buy\Browse\V1\HeaderSelector;
use TNT\Ebay\Buy\Browse\V1\ObjectSerializer;
/**
* ItemSummaryApi Class Doc Comment.
*
* @category Class
*
* @author OpenAPI Generator team
*
* @see https://openapi-generator.tech
*/
class ItemSummaryApi
{
/**
* @var ClientInterface
*/
protected $client;
/**
* @var Configuration
*/
protected $config;
/**
* @var HeaderSelector
*/
protected $headerSelector;
/**
* @var int Host index
*/
protected $hostIndex;
/**
* @param ClientInterface $client
* @param Configuration $config
* @param HeaderSelector $selector
* @param int $hostIndex (Optional) host index to select the list of hosts if defined in the OpenAPI spec
*/
public function __construct(
ClientInterface $client = null,
Configuration $config = null,
HeaderSelector $selector = null,
$hostIndex = 0
) {
$this->client = $client ?: new Client();
$this->config = $config ?: new Configuration();
$this->headerSelector = $selector ?: new HeaderSelector();
$this->hostIndex = $hostIndex;
}
/**
* Set the host index.
*
* @param int $hostIndex Host index (required)
*/
public function setHostIndex($hostIndex): void
{
$this->hostIndex = $hostIndex;
}
/**
* Get the host index.
*
* @return int Host index
*/
public function getHostIndex()
{
return $this->hostIndex;
}
/**
* @return Configuration
*/
public function getConfiguration()
{
return $this->config;
}
/**
* Operation search.
*
* @param string $aspect_filter This field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red. <br /><br />For example, the method below uses the category ID for Women's Clothing. This will return only items for a woman's red shirt.<br /><br /><code>/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}</code> <br /><br />To get a list of the aspect pairs and the category, which is returned in the <b>dominantCategoryId</b> field, set <b>fieldgroups</b> to <code>ASPECT_REFINEMENTS</code>. <br /><br /> <code>/buy/browse/v1/item_summary/search?q=shirt&amp;fieldgroups=ASPECT_REFINEMENTS</code> <br /><br /><span class=\"tablenote\"><b> Note:</b> The pipe symbol is used as a delimiter between aspect filter values. If a value contains a pipe symbol (for example, the brand name 'Bed|Stü'), you must enter a backslash before the pipe character to prevent it from being evaluated as a delimiter. <br /><br />The following example shows the correct format for entering two brand names as aspect filter values, one of which contains a pipe symbol:<br /><br /><code>/buy/browse/v1/item_summary/search?limit=50&category_ids=3034&filter=buyingOptions:{AUCTION|FIXED_PRICE}&aspect_filter=categoryId:3034,Brand:{Bed&bsol;|Stü|Nike}</code></span><br /><br /><b>Required:</b> The category ID is required <i>twice</i>; once as a URI parameter and as part of the <b> aspect_filter</b>. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:AspectFilter (optional)
* @param string $auto_correct A query parameter that enables auto correction.<br /><br /><b>Valid Values:</b> <code>KEYWORD</code> (optional)
* @param string $category_ids <a name=\"category_ids\"></a>The category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs.<br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?category_ids=29792</code> <br /><br /><span class=\"tablenote\"><b> Note: </b>Currently, you can pass in only one category ID per request.</span> <br /> <br />You can also use any combination of the <b> category_Ids</b>, <b> epid</b>, and <b> q</b> fields. This gives you additional control over the result set. <br /><br />For example, let's say you are looking of a toy phone. If you search for \"phone\", the result set will be mobile phones because this is the \"Best Match\" for this search. But if you also include the toy category ID, the results will be what you wanted. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=phone&category_ids=220</code><br /> <br />The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site: <ul> <li>Use the <a href=\"https://pages.ebay.com/sellerinformation/news/categorychanges.html \" target=\"_blank\">Category Changes page</a>.</li> <li>Use the Taxonomy API. For details see <a href=\"/api-docs/buy/buy-categories.html\">Get Categories for Buy APIs</a>. </li> <li>Submit the following method to get the <b> dominantCategoryId</b> for an item. <br /><br /><code>/buy/browse/v1/item_summary/search?q=<em> keyword</em>&fieldgroups=ASPECT_REFINEMENTS </code></li></ul> <span class=\"tablenote\"> <b> Note:</b> If a top-level (L1) category is specified, you <b> must</b> also include the <b> q</b> query parameter.</span> <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $charity_ids The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities.<br /><br /> <b>For example:</b><br /><code>/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469</code><br /><br />The charity ID is the charity's registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called \"Charity Number\". <ul><li>To find the charities eBay supports, you can search for a charity at <a href=\"https://charity.ebay.com/search \" target=\"_blank\">Charity Search </a> or go to <a href=\"https://www.ebay.com/b/Charity/bn_7114598164 \" target=\"_blank\">Charity Shop</a>.</li> <li>To find the charity ID of a specific charity, click on a charity and use the EIN number. For example, the charity ID for <a href=\"https://charity.ebay.com/charity/American-Red-Cross/3843 \" target=\"_blank\">American Red Cross</a>, is <code>530196605</code>.</li></ul> You can also use any combination of the <code>category_Ids</code> and <code>q</code> fields with a <code>charity_Ids</code> to filter the result set. This gives you additional control over the result set. <br /><br /><b>Restriction: </b> This is supported only on the US and GB marketplaces.<br /><br /><b>Maximum: </b> 20 IDs <br /><br /><b>Required:</b> One ID (optional)
* @param string $compatibility_filter This field specifies the attributes used to define a specific product. The service searches for items matching the keyword or matching the keyword and a product attribute value in the title of the item.<br /><br /><span class=\"tablenote\"><b>Note:</b> The only products supported are cars, trucks, and motorcycles.</span><br />For example, if the keyword is <code>brakes</code> and <code>compatibility-filter=Year:2018;Make:BMW</code>, the items returned are items with brakes, 2018, or BMW in the title.<br /><br />The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.compatibilityMatch\"> CompatibilityMatchEnum</a> value that indicates how well the item matches the attributes.<br /><br /><span class=\"tablenote\"><span style=\"color:#478415\"><strong>Tip:</strong></span> See the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#s0-1-21-6-7-7-6-ReturnItemsthatareCompatiblewiththeKeywordandVehicle-9\">Samples</a> section for a detailed example.</span><br /><b>Best Practice:</b> Submit all of the <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attributes</a> for the specific product.<br /><br />To find the attributes and values for a specific marketplace, you can use the <a href=\"/api-docs/commerce/taxonomy/resources/category_tree/methods/getCompatibilityProperties\">getCompatibilityProperties</a> method in the <a href=\"/api-docs/commerce/taxonomy/resources/methods\">Taxonomy API</a>.<br /><br />For more details, see <a href=\"/api-docs/buy/static/api-browse.html#Check\">Check compatibility</a> in the Buy Integration Guide.<br /><br /><span class=\"tablenote\"><b>Note:</b> Testing in Sandbox is only supported using mock data. See <a href=\"/api-docs/buy/static/api-browse.html#sbox-test\">Testing search in the Sandbox</a> for details.</span><br /><b>Required:</b><ul><li><b>q</b> (keyword)</li><li>One fitment supported category ID (such as <code>33559</code> Brakes)</li><li>At least one <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attribute</a> name/value pair</li></ul> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityFilter (optional)
* @param string $epid The ePID is the eBay product identifier of a product from the eBay product catalog. This field limits the results to only items in the specified ePID. <br /><br />The <b> Marketing</b> API <b>getMerchandisedProducts</b> method and the <b>Browse</b> API <b> getItem</b>, <b> getItemByLegacyId</b>, and <b> getItemsByItemGroup</b> calls return the ePID of the product. You can also use the <a href=\"/api-docs/commerce/catalog/resources/product_summary/methods/search\">product_summary/search</a> method in the <b>Catalog</b> API to search for the ePID of the product. <br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?epid=15032</code> <br /><br /><b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $fieldgroups This field is a comma separated list of values that lets you control what is returned in the response. The default is <b> MATCHING_ITEMS</b>, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information.<br /><br /><b>Valid Values:</b> <ul><li><b> ASPECT_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.aspectDistributions\">aspectDistributions</a> container, which has the <b>dominantCategoryId</b>, <b>matchCount</b>, and <b>refinementHref</b> for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be <b>Model Year</b>, <b>Exterior Color</b>, <b>Vehicle Mileage</b>, etc.<br /><br /><span class=\"tablenote\"> <b>Note:</b> ASPECT_REFINEMENTS are category specific.</span></li><li><b>BUYING_OPTION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.buyingOptionDistributions\">buyingOptionDistributions</a> container, which has the <b>matchCount</b> and <b>refinementHref</b> for <b>AUCTION</b>, <b>FIXED_PRICE</b> (Buy It Now), and <b>CLASSIFIED_AD</b> items.</li><li><b>CATEGORY_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.categoryDistributions\">categoryDistributions</a> container, which has the categories that the item is in.</li><li><b>CONDITION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.conditionDistributions\">conditionDistributions</a> container, such as <b>NEW</b>, <b>USED</b>, etc. Within these groups are multiple states of the condition. For example, <b>New</b> can be New without tag, New in box, New without box, etc.</li><li><b>EXTENDED</b> - This returns the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.shortDescription\">shortDescription</a> field, which provides condition and item aspect information and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.itemLocation.city\">itemLocation.city</a> field.</li><li><b>MATCHING_ITEMS</b> - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.</li><li><b>FULL</b> - This returns all the refinement containers and all the matching items.</li></ul>Code so that your app gracefully handles any future changes to this list.<br /><br /><b>Default:</b> MATCHING_ITEMS (optional)
* @param string $filter An array of field filters that can be used to limit/customize the result set. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]</code><br /><br />You can also combine filters. <br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}</code><br /><br /><span class=\"tablenote\"><span style=\"color:#004680\"><strong>Note:</strong></span> Refer to <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html\">Buy API Field Filters</a> for details and examples of all supported filters.</span> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField (optional)
* @param string $gtin This field lets you search by the Global Trade Item Number of the item as defined by <a href=\"https://www.gtin.info \" target=\"_blank\">https://www.gtin.info</a>. You can search only by UPC (Universal Product Code). If you have other formats of GTIN, you need to search by keyword. <br /><br /><b> For example: </b><br/><code> /buy/browse/v1/item_summary/search?gtin=099482432621</code> <br /><br /> <b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $limit The number of items from the result set returned in a single page. <br /><br /><span class=\"tablenote\"><b>Note:</b> If a value is set in the <b>limit</b> field, the value of <b>offset</b> must be either zero or a multiple of the <b>limit</b> value. An error is returned for invalid values of <b>offset</b>.</span> <br /><br /><b>Default:</b> 50 <br /><br /><b>Maximum number of items per page (limit):</b> 200 <br /><br /><b>Maximum number of items in a result set:</b> 10,000 (optional)
* @param string $offset Specifies the number of items to skip in the result set. This is used with the <b>limit</b> field to control the pagination of the output. <br /><br />For example, if <b>offset</b> is 0 and <b>limit</b> is 10, the method will retrieve items 1-10 from the list of items returned; if <b>offset</b> is 10 and <b>limit</b> is 10, the method will retrieve items 11-20 from the list of items returned. <br /><br /><span class=\"tablenote\"><b>Note:</b> The value of <b>offset</b> must be either zero or a multiple of the value set in the <b>limit</b> field. An empty result set is returned for invalid values of <b>offset</b>.</span> <br /><br /><b> Valid Values</b>: 0-10,000 (inclusive) <br /><br /><b>Default:</b> 0 <br /><br /><b>Maximum number of items returned:</b> 10,000 (optional)
* @param string $q A string consisting of one or more keywords that are used to search for items on eBay. The keywords are handled as follows:<ul><li>If the keywords are separated by a space, it is treated as an AND. In the following example, the query returns items that have iphone <b>AND</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=iphone ipad</code><br/><br /></li><li>If the keywords are input using parentheses and separated by a comma, or if they are URL-encoded, it is treated as an OR. In the following examples, the query returns items that have iphone <b>OR</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=(iphone, ipad)</code><br /><br /><code>/buy/browse/v1/item_summary/search?q=%28iphone%2c%20ipad%29</code><br /><br /></li></ul><b>Restriction:</b> The <code>*</code> wildcard character is <b>not</b> allowed in this field.<br /><br /><b>Required:</b> The method must have <b>category_ids</b>, <b>epid</b>, <b>gtin</b>, or <b>q</b> (or any combination of these). (optional)
* @param string $sort The order and field name that is used to sort the items. <br /><br />You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen (<code>-</code>) before the name of the sorting option. If no <b>sort</b> parameter is submitted, the result set is sorted by &quot;<a href=\"https://pages.ebay.com/help/sell/searchstanding.html \" target=\"_blank\">Best Match</a>&quot;.<br /><br />Here are some examples showing how to use the <b>sort</b> query parameter:<br /><ul><li><b><code>sort=distance</code></b> - This sorts by <i>distance</i> in ascending order (shortest distance first). This sorting option is only applicable if the <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html#pickupCountry\">pickup</a> filters are used, and only ascending order is supported.</li><li><b><code>sort=-price</code></b> - This sorts by <i>price + shipping cost</i> in descending order (highest price first). This sorting option (by <i>price</i>) is only guaranteed to work correctly if the <b>X-EBAY-C-ENDUSERCTX</b> request header is used, with the <b>contextualLocation</b> parameter being used to set the delivery country and postal code. Here is an example of how this header would be used to do this (note the URL encoding):<br /><br /><code>X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406</code><br /></li><li><b><code>sort=newlyListed</code></b> - This sorts by <i>listing date</i> (most recently listed/newest items first).</li><li><b><code>sort=endingSoonest</code></b> - This sorts by <i>date/time</i> the listing ends (listings nearest to end date/time first).</li></ul><b>Default:</b> Ascending For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:SortField (optional)
*
* @throws \TNT\Ebay\Buy\Browse\V1\ApiException on non-2xx response
* @throws \InvalidArgumentException
*
* @return \TNT\Ebay\Buy\Browse\V1\Model\SearchPagedCollection
*/
public function search($aspect_filter = null, $auto_correct = null, $category_ids = null, $charity_ids = null, $compatibility_filter = null, $epid = null, $fieldgroups = null, $filter = null, $gtin = null, $limit = null, $offset = null, $q = null, $sort = null)
{
[$response] = $this->searchWithHttpInfo($aspect_filter, $auto_correct, $category_ids, $charity_ids, $compatibility_filter, $epid, $fieldgroups, $filter, $gtin, $limit, $offset, $q, $sort);
return $response;
}
/**
* Operation searchWithHttpInfo.
*
* @param string $aspect_filter This field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red. <br /><br />For example, the method below uses the category ID for Women's Clothing. This will return only items for a woman's red shirt.<br /><br /><code>/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}</code> <br /><br />To get a list of the aspect pairs and the category, which is returned in the <b>dominantCategoryId</b> field, set <b>fieldgroups</b> to <code>ASPECT_REFINEMENTS</code>. <br /><br /> <code>/buy/browse/v1/item_summary/search?q=shirt&amp;fieldgroups=ASPECT_REFINEMENTS</code> <br /><br /><span class=\"tablenote\"><b> Note:</b> The pipe symbol is used as a delimiter between aspect filter values. If a value contains a pipe symbol (for example, the brand name 'Bed|Stü'), you must enter a backslash before the pipe character to prevent it from being evaluated as a delimiter. <br /><br />The following example shows the correct format for entering two brand names as aspect filter values, one of which contains a pipe symbol:<br /><br /><code>/buy/browse/v1/item_summary/search?limit=50&category_ids=3034&filter=buyingOptions:{AUCTION|FIXED_PRICE}&aspect_filter=categoryId:3034,Brand:{Bed&bsol;|Stü|Nike}</code></span><br /><br /><b>Required:</b> The category ID is required <i>twice</i>; once as a URI parameter and as part of the <b> aspect_filter</b>. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:AspectFilter (optional)
* @param string $auto_correct A query parameter that enables auto correction.<br /><br /><b>Valid Values:</b> <code>KEYWORD</code> (optional)
* @param string $category_ids <a name=\"category_ids\"></a>The category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs.<br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?category_ids=29792</code> <br /><br /><span class=\"tablenote\"><b> Note: </b>Currently, you can pass in only one category ID per request.</span> <br /> <br />You can also use any combination of the <b> category_Ids</b>, <b> epid</b>, and <b> q</b> fields. This gives you additional control over the result set. <br /><br />For example, let's say you are looking of a toy phone. If you search for \"phone\", the result set will be mobile phones because this is the \"Best Match\" for this search. But if you also include the toy category ID, the results will be what you wanted. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=phone&category_ids=220</code><br /> <br />The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site: <ul> <li>Use the <a href=\"https://pages.ebay.com/sellerinformation/news/categorychanges.html \" target=\"_blank\">Category Changes page</a>.</li> <li>Use the Taxonomy API. For details see <a href=\"/api-docs/buy/buy-categories.html\">Get Categories for Buy APIs</a>. </li> <li>Submit the following method to get the <b> dominantCategoryId</b> for an item. <br /><br /><code>/buy/browse/v1/item_summary/search?q=<em> keyword</em>&fieldgroups=ASPECT_REFINEMENTS </code></li></ul> <span class=\"tablenote\"> <b> Note:</b> If a top-level (L1) category is specified, you <b> must</b> also include the <b> q</b> query parameter.</span> <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $charity_ids The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities.<br /><br /> <b>For example:</b><br /><code>/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469</code><br /><br />The charity ID is the charity's registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called \"Charity Number\". <ul><li>To find the charities eBay supports, you can search for a charity at <a href=\"https://charity.ebay.com/search \" target=\"_blank\">Charity Search </a> or go to <a href=\"https://www.ebay.com/b/Charity/bn_7114598164 \" target=\"_blank\">Charity Shop</a>.</li> <li>To find the charity ID of a specific charity, click on a charity and use the EIN number. For example, the charity ID for <a href=\"https://charity.ebay.com/charity/American-Red-Cross/3843 \" target=\"_blank\">American Red Cross</a>, is <code>530196605</code>.</li></ul> You can also use any combination of the <code>category_Ids</code> and <code>q</code> fields with a <code>charity_Ids</code> to filter the result set. This gives you additional control over the result set. <br /><br /><b>Restriction: </b> This is supported only on the US and GB marketplaces.<br /><br /><b>Maximum: </b> 20 IDs <br /><br /><b>Required:</b> One ID (optional)
* @param string $compatibility_filter This field specifies the attributes used to define a specific product. The service searches for items matching the keyword or matching the keyword and a product attribute value in the title of the item.<br /><br /><span class=\"tablenote\"><b>Note:</b> The only products supported are cars, trucks, and motorcycles.</span><br />For example, if the keyword is <code>brakes</code> and <code>compatibility-filter=Year:2018;Make:BMW</code>, the items returned are items with brakes, 2018, or BMW in the title.<br /><br />The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.compatibilityMatch\"> CompatibilityMatchEnum</a> value that indicates how well the item matches the attributes.<br /><br /><span class=\"tablenote\"><span style=\"color:#478415\"><strong>Tip:</strong></span> See the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#s0-1-21-6-7-7-6-ReturnItemsthatareCompatiblewiththeKeywordandVehicle-9\">Samples</a> section for a detailed example.</span><br /><b>Best Practice:</b> Submit all of the <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attributes</a> for the specific product.<br /><br />To find the attributes and values for a specific marketplace, you can use the <a href=\"/api-docs/commerce/taxonomy/resources/category_tree/methods/getCompatibilityProperties\">getCompatibilityProperties</a> method in the <a href=\"/api-docs/commerce/taxonomy/resources/methods\">Taxonomy API</a>.<br /><br />For more details, see <a href=\"/api-docs/buy/static/api-browse.html#Check\">Check compatibility</a> in the Buy Integration Guide.<br /><br /><span class=\"tablenote\"><b>Note:</b> Testing in Sandbox is only supported using mock data. See <a href=\"/api-docs/buy/static/api-browse.html#sbox-test\">Testing search in the Sandbox</a> for details.</span><br /><b>Required:</b><ul><li><b>q</b> (keyword)</li><li>One fitment supported category ID (such as <code>33559</code> Brakes)</li><li>At least one <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attribute</a> name/value pair</li></ul> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityFilter (optional)
* @param string $epid The ePID is the eBay product identifier of a product from the eBay product catalog. This field limits the results to only items in the specified ePID. <br /><br />The <b> Marketing</b> API <b>getMerchandisedProducts</b> method and the <b>Browse</b> API <b> getItem</b>, <b> getItemByLegacyId</b>, and <b> getItemsByItemGroup</b> calls return the ePID of the product. You can also use the <a href=\"/api-docs/commerce/catalog/resources/product_summary/methods/search\">product_summary/search</a> method in the <b>Catalog</b> API to search for the ePID of the product. <br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?epid=15032</code> <br /><br /><b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $fieldgroups This field is a comma separated list of values that lets you control what is returned in the response. The default is <b> MATCHING_ITEMS</b>, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information.<br /><br /><b>Valid Values:</b> <ul><li><b> ASPECT_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.aspectDistributions\">aspectDistributions</a> container, which has the <b>dominantCategoryId</b>, <b>matchCount</b>, and <b>refinementHref</b> for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be <b>Model Year</b>, <b>Exterior Color</b>, <b>Vehicle Mileage</b>, etc.<br /><br /><span class=\"tablenote\"> <b>Note:</b> ASPECT_REFINEMENTS are category specific.</span></li><li><b>BUYING_OPTION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.buyingOptionDistributions\">buyingOptionDistributions</a> container, which has the <b>matchCount</b> and <b>refinementHref</b> for <b>AUCTION</b>, <b>FIXED_PRICE</b> (Buy It Now), and <b>CLASSIFIED_AD</b> items.</li><li><b>CATEGORY_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.categoryDistributions\">categoryDistributions</a> container, which has the categories that the item is in.</li><li><b>CONDITION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.conditionDistributions\">conditionDistributions</a> container, such as <b>NEW</b>, <b>USED</b>, etc. Within these groups are multiple states of the condition. For example, <b>New</b> can be New without tag, New in box, New without box, etc.</li><li><b>EXTENDED</b> - This returns the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.shortDescription\">shortDescription</a> field, which provides condition and item aspect information and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.itemLocation.city\">itemLocation.city</a> field.</li><li><b>MATCHING_ITEMS</b> - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.</li><li><b>FULL</b> - This returns all the refinement containers and all the matching items.</li></ul>Code so that your app gracefully handles any future changes to this list.<br /><br /><b>Default:</b> MATCHING_ITEMS (optional)
* @param string $filter An array of field filters that can be used to limit/customize the result set. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]</code><br /><br />You can also combine filters. <br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}</code><br /><br /><span class=\"tablenote\"><span style=\"color:#004680\"><strong>Note:</strong></span> Refer to <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html\">Buy API Field Filters</a> for details and examples of all supported filters.</span> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField (optional)
* @param string $gtin This field lets you search by the Global Trade Item Number of the item as defined by <a href=\"https://www.gtin.info \" target=\"_blank\">https://www.gtin.info</a>. You can search only by UPC (Universal Product Code). If you have other formats of GTIN, you need to search by keyword. <br /><br /><b> For example: </b><br/><code> /buy/browse/v1/item_summary/search?gtin=099482432621</code> <br /><br /> <b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $limit The number of items from the result set returned in a single page. <br /><br /><span class=\"tablenote\"><b>Note:</b> If a value is set in the <b>limit</b> field, the value of <b>offset</b> must be either zero or a multiple of the <b>limit</b> value. An error is returned for invalid values of <b>offset</b>.</span> <br /><br /><b>Default:</b> 50 <br /><br /><b>Maximum number of items per page (limit):</b> 200 <br /><br /><b>Maximum number of items in a result set:</b> 10,000 (optional)
* @param string $offset Specifies the number of items to skip in the result set. This is used with the <b>limit</b> field to control the pagination of the output. <br /><br />For example, if <b>offset</b> is 0 and <b>limit</b> is 10, the method will retrieve items 1-10 from the list of items returned; if <b>offset</b> is 10 and <b>limit</b> is 10, the method will retrieve items 11-20 from the list of items returned. <br /><br /><span class=\"tablenote\"><b>Note:</b> The value of <b>offset</b> must be either zero or a multiple of the value set in the <b>limit</b> field. An empty result set is returned for invalid values of <b>offset</b>.</span> <br /><br /><b> Valid Values</b>: 0-10,000 (inclusive) <br /><br /><b>Default:</b> 0 <br /><br /><b>Maximum number of items returned:</b> 10,000 (optional)
* @param string $q A string consisting of one or more keywords that are used to search for items on eBay. The keywords are handled as follows:<ul><li>If the keywords are separated by a space, it is treated as an AND. In the following example, the query returns items that have iphone <b>AND</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=iphone ipad</code><br/><br /></li><li>If the keywords are input using parentheses and separated by a comma, or if they are URL-encoded, it is treated as an OR. In the following examples, the query returns items that have iphone <b>OR</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=(iphone, ipad)</code><br /><br /><code>/buy/browse/v1/item_summary/search?q=%28iphone%2c%20ipad%29</code><br /><br /></li></ul><b>Restriction:</b> The <code>*</code> wildcard character is <b>not</b> allowed in this field.<br /><br /><b>Required:</b> The method must have <b>category_ids</b>, <b>epid</b>, <b>gtin</b>, or <b>q</b> (or any combination of these). (optional)
* @param string $sort The order and field name that is used to sort the items. <br /><br />You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen (<code>-</code>) before the name of the sorting option. If no <b>sort</b> parameter is submitted, the result set is sorted by &quot;<a href=\"https://pages.ebay.com/help/sell/searchstanding.html \" target=\"_blank\">Best Match</a>&quot;.<br /><br />Here are some examples showing how to use the <b>sort</b> query parameter:<br /><ul><li><b><code>sort=distance</code></b> - This sorts by <i>distance</i> in ascending order (shortest distance first). This sorting option is only applicable if the <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html#pickupCountry\">pickup</a> filters are used, and only ascending order is supported.</li><li><b><code>sort=-price</code></b> - This sorts by <i>price + shipping cost</i> in descending order (highest price first). This sorting option (by <i>price</i>) is only guaranteed to work correctly if the <b>X-EBAY-C-ENDUSERCTX</b> request header is used, with the <b>contextualLocation</b> parameter being used to set the delivery country and postal code. Here is an example of how this header would be used to do this (note the URL encoding):<br /><br /><code>X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406</code><br /></li><li><b><code>sort=newlyListed</code></b> - This sorts by <i>listing date</i> (most recently listed/newest items first).</li><li><b><code>sort=endingSoonest</code></b> - This sorts by <i>date/time</i> the listing ends (listings nearest to end date/time first).</li></ul><b>Default:</b> Ascending For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:SortField (optional)
*
* @throws \TNT\Ebay\Buy\Browse\V1\ApiException on non-2xx response
* @throws \InvalidArgumentException
*
* @return array of \TNT\Ebay\Buy\Browse\V1\Model\SearchPagedCollection, HTTP status code, HTTP response headers (array of strings)
*/
public function searchWithHttpInfo($aspect_filter = null, $auto_correct = null, $category_ids = null, $charity_ids = null, $compatibility_filter = null, $epid = null, $fieldgroups = null, $filter = null, $gtin = null, $limit = null, $offset = null, $q = null, $sort = null)
{
$request = $this->searchRequest($aspect_filter, $auto_correct, $category_ids, $charity_ids, $compatibility_filter, $epid, $fieldgroups, $filter, $gtin, $limit, $offset, $q, $sort);
try {
$options = $this->createHttpClientOption();
try {
$response = $this->client->send($request, $options);
} catch (RequestException $e) {
throw new ApiException("[{$e->getCode()}] {$e->getMessage()}", (int) $e->getCode(), $e->getResponse() ? $e->getResponse()->getHeaders() : null, $e->getResponse() ? (string) $e->getResponse()->getBody() : null, $e);
} catch (ConnectException $e) {
throw new ApiException("[{$e->getCode()}] {$e->getMessage()}", (int) $e->getCode(), null, null, $e);
} catch (GuzzleException $e) {
throw new ApiException("[{$e->getCode()}] {$e->getMessage()}", (int) $e->getCode(), null, null, $e);
}
$statusCode = $response->getStatusCode();
if ($statusCode < 200 || $statusCode > 299) {
throw new ApiException(sprintf('[%d] Error connecting to the API (%s)', $statusCode, (string) $request->getUri()), $statusCode, $response->getHeaders(), (string) $response->getBody());
}
switch ($statusCode) {
case 200:
if ('\TNT\Ebay\Buy\Browse\V1\Model\SearchPagedCollection' === '\SplFileObject') {
$content = $response->getBody(); // Stream goes to serializer.
} else {
$content = (string) $response->getBody();
}
return [
ObjectSerializer::deserialize($content, '\TNT\Ebay\Buy\Browse\V1\Model\SearchPagedCollection', []),
$response->getStatusCode(),
$response->getHeaders(),
];
}
$returnType = '\TNT\Ebay\Buy\Browse\V1\Model\SearchPagedCollection';
if ($returnType === '\SplFileObject') {
$content = $response->getBody(); // Stream goes to serializer.
} else {
$content = (string) $response->getBody();
}
return [
ObjectSerializer::deserialize($content, $returnType, []),
$response->getStatusCode(),
$response->getHeaders(),
];
} catch (ApiException $e) {
switch ($e->getCode()) {
case 200:
$data = ObjectSerializer::deserialize(
$e->getResponseBody(),
'\TNT\Ebay\Buy\Browse\V1\Model\SearchPagedCollection',
$e->getResponseHeaders()
);
$e->setResponseObject($data);
break;
}
throw $e;
}
}
/**
* Operation searchAsync.
*
* @param string $aspect_filter This field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red. <br /><br />For example, the method below uses the category ID for Women's Clothing. This will return only items for a woman's red shirt.<br /><br /><code>/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}</code> <br /><br />To get a list of the aspect pairs and the category, which is returned in the <b>dominantCategoryId</b> field, set <b>fieldgroups</b> to <code>ASPECT_REFINEMENTS</code>. <br /><br /> <code>/buy/browse/v1/item_summary/search?q=shirt&amp;fieldgroups=ASPECT_REFINEMENTS</code> <br /><br /><span class=\"tablenote\"><b> Note:</b> The pipe symbol is used as a delimiter between aspect filter values. If a value contains a pipe symbol (for example, the brand name 'Bed|Stü'), you must enter a backslash before the pipe character to prevent it from being evaluated as a delimiter. <br /><br />The following example shows the correct format for entering two brand names as aspect filter values, one of which contains a pipe symbol:<br /><br /><code>/buy/browse/v1/item_summary/search?limit=50&category_ids=3034&filter=buyingOptions:{AUCTION|FIXED_PRICE}&aspect_filter=categoryId:3034,Brand:{Bed&bsol;|Stü|Nike}</code></span><br /><br /><b>Required:</b> The category ID is required <i>twice</i>; once as a URI parameter and as part of the <b> aspect_filter</b>. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:AspectFilter (optional)
* @param string $auto_correct A query parameter that enables auto correction.<br /><br /><b>Valid Values:</b> <code>KEYWORD</code> (optional)
* @param string $category_ids <a name=\"category_ids\"></a>The category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs.<br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?category_ids=29792</code> <br /><br /><span class=\"tablenote\"><b> Note: </b>Currently, you can pass in only one category ID per request.</span> <br /> <br />You can also use any combination of the <b> category_Ids</b>, <b> epid</b>, and <b> q</b> fields. This gives you additional control over the result set. <br /><br />For example, let's say you are looking of a toy phone. If you search for \"phone\", the result set will be mobile phones because this is the \"Best Match\" for this search. But if you also include the toy category ID, the results will be what you wanted. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=phone&category_ids=220</code><br /> <br />The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site: <ul> <li>Use the <a href=\"https://pages.ebay.com/sellerinformation/news/categorychanges.html \" target=\"_blank\">Category Changes page</a>.</li> <li>Use the Taxonomy API. For details see <a href=\"/api-docs/buy/buy-categories.html\">Get Categories for Buy APIs</a>. </li> <li>Submit the following method to get the <b> dominantCategoryId</b> for an item. <br /><br /><code>/buy/browse/v1/item_summary/search?q=<em> keyword</em>&fieldgroups=ASPECT_REFINEMENTS </code></li></ul> <span class=\"tablenote\"> <b> Note:</b> If a top-level (L1) category is specified, you <b> must</b> also include the <b> q</b> query parameter.</span> <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $charity_ids The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities.<br /><br /> <b>For example:</b><br /><code>/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469</code><br /><br />The charity ID is the charity's registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called \"Charity Number\". <ul><li>To find the charities eBay supports, you can search for a charity at <a href=\"https://charity.ebay.com/search \" target=\"_blank\">Charity Search </a> or go to <a href=\"https://www.ebay.com/b/Charity/bn_7114598164 \" target=\"_blank\">Charity Shop</a>.</li> <li>To find the charity ID of a specific charity, click on a charity and use the EIN number. For example, the charity ID for <a href=\"https://charity.ebay.com/charity/American-Red-Cross/3843 \" target=\"_blank\">American Red Cross</a>, is <code>530196605</code>.</li></ul> You can also use any combination of the <code>category_Ids</code> and <code>q</code> fields with a <code>charity_Ids</code> to filter the result set. This gives you additional control over the result set. <br /><br /><b>Restriction: </b> This is supported only on the US and GB marketplaces.<br /><br /><b>Maximum: </b> 20 IDs <br /><br /><b>Required:</b> One ID (optional)
* @param string $compatibility_filter This field specifies the attributes used to define a specific product. The service searches for items matching the keyword or matching the keyword and a product attribute value in the title of the item.<br /><br /><span class=\"tablenote\"><b>Note:</b> The only products supported are cars, trucks, and motorcycles.</span><br />For example, if the keyword is <code>brakes</code> and <code>compatibility-filter=Year:2018;Make:BMW</code>, the items returned are items with brakes, 2018, or BMW in the title.<br /><br />The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.compatibilityMatch\"> CompatibilityMatchEnum</a> value that indicates how well the item matches the attributes.<br /><br /><span class=\"tablenote\"><span style=\"color:#478415\"><strong>Tip:</strong></span> See the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#s0-1-21-6-7-7-6-ReturnItemsthatareCompatiblewiththeKeywordandVehicle-9\">Samples</a> section for a detailed example.</span><br /><b>Best Practice:</b> Submit all of the <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attributes</a> for the specific product.<br /><br />To find the attributes and values for a specific marketplace, you can use the <a href=\"/api-docs/commerce/taxonomy/resources/category_tree/methods/getCompatibilityProperties\">getCompatibilityProperties</a> method in the <a href=\"/api-docs/commerce/taxonomy/resources/methods\">Taxonomy API</a>.<br /><br />For more details, see <a href=\"/api-docs/buy/static/api-browse.html#Check\">Check compatibility</a> in the Buy Integration Guide.<br /><br /><span class=\"tablenote\"><b>Note:</b> Testing in Sandbox is only supported using mock data. See <a href=\"/api-docs/buy/static/api-browse.html#sbox-test\">Testing search in the Sandbox</a> for details.</span><br /><b>Required:</b><ul><li><b>q</b> (keyword)</li><li>One fitment supported category ID (such as <code>33559</code> Brakes)</li><li>At least one <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attribute</a> name/value pair</li></ul> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityFilter (optional)
* @param string $epid The ePID is the eBay product identifier of a product from the eBay product catalog. This field limits the results to only items in the specified ePID. <br /><br />The <b> Marketing</b> API <b>getMerchandisedProducts</b> method and the <b>Browse</b> API <b> getItem</b>, <b> getItemByLegacyId</b>, and <b> getItemsByItemGroup</b> calls return the ePID of the product. You can also use the <a href=\"/api-docs/commerce/catalog/resources/product_summary/methods/search\">product_summary/search</a> method in the <b>Catalog</b> API to search for the ePID of the product. <br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?epid=15032</code> <br /><br /><b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $fieldgroups This field is a comma separated list of values that lets you control what is returned in the response. The default is <b> MATCHING_ITEMS</b>, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information.<br /><br /><b>Valid Values:</b> <ul><li><b> ASPECT_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.aspectDistributions\">aspectDistributions</a> container, which has the <b>dominantCategoryId</b>, <b>matchCount</b>, and <b>refinementHref</b> for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be <b>Model Year</b>, <b>Exterior Color</b>, <b>Vehicle Mileage</b>, etc.<br /><br /><span class=\"tablenote\"> <b>Note:</b> ASPECT_REFINEMENTS are category specific.</span></li><li><b>BUYING_OPTION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.buyingOptionDistributions\">buyingOptionDistributions</a> container, which has the <b>matchCount</b> and <b>refinementHref</b> for <b>AUCTION</b>, <b>FIXED_PRICE</b> (Buy It Now), and <b>CLASSIFIED_AD</b> items.</li><li><b>CATEGORY_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.categoryDistributions\">categoryDistributions</a> container, which has the categories that the item is in.</li><li><b>CONDITION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.conditionDistributions\">conditionDistributions</a> container, such as <b>NEW</b>, <b>USED</b>, etc. Within these groups are multiple states of the condition. For example, <b>New</b> can be New without tag, New in box, New without box, etc.</li><li><b>EXTENDED</b> - This returns the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.shortDescription\">shortDescription</a> field, which provides condition and item aspect information and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.itemLocation.city\">itemLocation.city</a> field.</li><li><b>MATCHING_ITEMS</b> - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.</li><li><b>FULL</b> - This returns all the refinement containers and all the matching items.</li></ul>Code so that your app gracefully handles any future changes to this list.<br /><br /><b>Default:</b> MATCHING_ITEMS (optional)
* @param string $filter An array of field filters that can be used to limit/customize the result set. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]</code><br /><br />You can also combine filters. <br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}</code><br /><br /><span class=\"tablenote\"><span style=\"color:#004680\"><strong>Note:</strong></span> Refer to <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html\">Buy API Field Filters</a> for details and examples of all supported filters.</span> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField (optional)
* @param string $gtin This field lets you search by the Global Trade Item Number of the item as defined by <a href=\"https://www.gtin.info \" target=\"_blank\">https://www.gtin.info</a>. You can search only by UPC (Universal Product Code). If you have other formats of GTIN, you need to search by keyword. <br /><br /><b> For example: </b><br/><code> /buy/browse/v1/item_summary/search?gtin=099482432621</code> <br /><br /> <b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $limit The number of items from the result set returned in a single page. <br /><br /><span class=\"tablenote\"><b>Note:</b> If a value is set in the <b>limit</b> field, the value of <b>offset</b> must be either zero or a multiple of the <b>limit</b> value. An error is returned for invalid values of <b>offset</b>.</span> <br /><br /><b>Default:</b> 50 <br /><br /><b>Maximum number of items per page (limit):</b> 200 <br /><br /><b>Maximum number of items in a result set:</b> 10,000 (optional)
* @param string $offset Specifies the number of items to skip in the result set. This is used with the <b>limit</b> field to control the pagination of the output. <br /><br />For example, if <b>offset</b> is 0 and <b>limit</b> is 10, the method will retrieve items 1-10 from the list of items returned; if <b>offset</b> is 10 and <b>limit</b> is 10, the method will retrieve items 11-20 from the list of items returned. <br /><br /><span class=\"tablenote\"><b>Note:</b> The value of <b>offset</b> must be either zero or a multiple of the value set in the <b>limit</b> field. An empty result set is returned for invalid values of <b>offset</b>.</span> <br /><br /><b> Valid Values</b>: 0-10,000 (inclusive) <br /><br /><b>Default:</b> 0 <br /><br /><b>Maximum number of items returned:</b> 10,000 (optional)
* @param string $q A string consisting of one or more keywords that are used to search for items on eBay. The keywords are handled as follows:<ul><li>If the keywords are separated by a space, it is treated as an AND. In the following example, the query returns items that have iphone <b>AND</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=iphone ipad</code><br/><br /></li><li>If the keywords are input using parentheses and separated by a comma, or if they are URL-encoded, it is treated as an OR. In the following examples, the query returns items that have iphone <b>OR</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=(iphone, ipad)</code><br /><br /><code>/buy/browse/v1/item_summary/search?q=%28iphone%2c%20ipad%29</code><br /><br /></li></ul><b>Restriction:</b> The <code>*</code> wildcard character is <b>not</b> allowed in this field.<br /><br /><b>Required:</b> The method must have <b>category_ids</b>, <b>epid</b>, <b>gtin</b>, or <b>q</b> (or any combination of these). (optional)
* @param string $sort The order and field name that is used to sort the items. <br /><br />You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen (<code>-</code>) before the name of the sorting option. If no <b>sort</b> parameter is submitted, the result set is sorted by &quot;<a href=\"https://pages.ebay.com/help/sell/searchstanding.html \" target=\"_blank\">Best Match</a>&quot;.<br /><br />Here are some examples showing how to use the <b>sort</b> query parameter:<br /><ul><li><b><code>sort=distance</code></b> - This sorts by <i>distance</i> in ascending order (shortest distance first). This sorting option is only applicable if the <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html#pickupCountry\">pickup</a> filters are used, and only ascending order is supported.</li><li><b><code>sort=-price</code></b> - This sorts by <i>price + shipping cost</i> in descending order (highest price first). This sorting option (by <i>price</i>) is only guaranteed to work correctly if the <b>X-EBAY-C-ENDUSERCTX</b> request header is used, with the <b>contextualLocation</b> parameter being used to set the delivery country and postal code. Here is an example of how this header would be used to do this (note the URL encoding):<br /><br /><code>X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406</code><br /></li><li><b><code>sort=newlyListed</code></b> - This sorts by <i>listing date</i> (most recently listed/newest items first).</li><li><b><code>sort=endingSoonest</code></b> - This sorts by <i>date/time</i> the listing ends (listings nearest to end date/time first).</li></ul><b>Default:</b> Ascending For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:SortField (optional)
*
* @throws \InvalidArgumentException
*
* @return \GuzzleHttp\Promise\PromiseInterface
*/
public function searchAsync($aspect_filter = null, $auto_correct = null, $category_ids = null, $charity_ids = null, $compatibility_filter = null, $epid = null, $fieldgroups = null, $filter = null, $gtin = null, $limit = null, $offset = null, $q = null, $sort = null)
{
return $this->searchAsyncWithHttpInfo($aspect_filter, $auto_correct, $category_ids, $charity_ids, $compatibility_filter, $epid, $fieldgroups, $filter, $gtin, $limit, $offset, $q, $sort)
->then(
function ($response) {
return $response[0];
}
);
}
/**
* Operation searchAsyncWithHttpInfo.
*
* @param string $aspect_filter This field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red. <br /><br />For example, the method below uses the category ID for Women's Clothing. This will return only items for a woman's red shirt.<br /><br /><code>/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}</code> <br /><br />To get a list of the aspect pairs and the category, which is returned in the <b>dominantCategoryId</b> field, set <b>fieldgroups</b> to <code>ASPECT_REFINEMENTS</code>. <br /><br /> <code>/buy/browse/v1/item_summary/search?q=shirt&amp;fieldgroups=ASPECT_REFINEMENTS</code> <br /><br /><span class=\"tablenote\"><b> Note:</b> The pipe symbol is used as a delimiter between aspect filter values. If a value contains a pipe symbol (for example, the brand name 'Bed|Stü'), you must enter a backslash before the pipe character to prevent it from being evaluated as a delimiter. <br /><br />The following example shows the correct format for entering two brand names as aspect filter values, one of which contains a pipe symbol:<br /><br /><code>/buy/browse/v1/item_summary/search?limit=50&category_ids=3034&filter=buyingOptions:{AUCTION|FIXED_PRICE}&aspect_filter=categoryId:3034,Brand:{Bed&bsol;|Stü|Nike}</code></span><br /><br /><b>Required:</b> The category ID is required <i>twice</i>; once as a URI parameter and as part of the <b> aspect_filter</b>. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:AspectFilter (optional)
* @param string $auto_correct A query parameter that enables auto correction.<br /><br /><b>Valid Values:</b> <code>KEYWORD</code> (optional)
* @param string $category_ids <a name=\"category_ids\"></a>The category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs.<br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?category_ids=29792</code> <br /><br /><span class=\"tablenote\"><b> Note: </b>Currently, you can pass in only one category ID per request.</span> <br /> <br />You can also use any combination of the <b> category_Ids</b>, <b> epid</b>, and <b> q</b> fields. This gives you additional control over the result set. <br /><br />For example, let's say you are looking of a toy phone. If you search for \"phone\", the result set will be mobile phones because this is the \"Best Match\" for this search. But if you also include the toy category ID, the results will be what you wanted. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=phone&category_ids=220</code><br /> <br />The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site: <ul> <li>Use the <a href=\"https://pages.ebay.com/sellerinformation/news/categorychanges.html \" target=\"_blank\">Category Changes page</a>.</li> <li>Use the Taxonomy API. For details see <a href=\"/api-docs/buy/buy-categories.html\">Get Categories for Buy APIs</a>. </li> <li>Submit the following method to get the <b> dominantCategoryId</b> for an item. <br /><br /><code>/buy/browse/v1/item_summary/search?q=<em> keyword</em>&fieldgroups=ASPECT_REFINEMENTS </code></li></ul> <span class=\"tablenote\"> <b> Note:</b> If a top-level (L1) category is specified, you <b> must</b> also include the <b> q</b> query parameter.</span> <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $charity_ids The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities.<br /><br /> <b>For example:</b><br /><code>/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469</code><br /><br />The charity ID is the charity's registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called \"Charity Number\". <ul><li>To find the charities eBay supports, you can search for a charity at <a href=\"https://charity.ebay.com/search \" target=\"_blank\">Charity Search </a> or go to <a href=\"https://www.ebay.com/b/Charity/bn_7114598164 \" target=\"_blank\">Charity Shop</a>.</li> <li>To find the charity ID of a specific charity, click on a charity and use the EIN number. For example, the charity ID for <a href=\"https://charity.ebay.com/charity/American-Red-Cross/3843 \" target=\"_blank\">American Red Cross</a>, is <code>530196605</code>.</li></ul> You can also use any combination of the <code>category_Ids</code> and <code>q</code> fields with a <code>charity_Ids</code> to filter the result set. This gives you additional control over the result set. <br /><br /><b>Restriction: </b> This is supported only on the US and GB marketplaces.<br /><br /><b>Maximum: </b> 20 IDs <br /><br /><b>Required:</b> One ID (optional)
* @param string $compatibility_filter This field specifies the attributes used to define a specific product. The service searches for items matching the keyword or matching the keyword and a product attribute value in the title of the item.<br /><br /><span class=\"tablenote\"><b>Note:</b> The only products supported are cars, trucks, and motorcycles.</span><br />For example, if the keyword is <code>brakes</code> and <code>compatibility-filter=Year:2018;Make:BMW</code>, the items returned are items with brakes, 2018, or BMW in the title.<br /><br />The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.compatibilityMatch\"> CompatibilityMatchEnum</a> value that indicates how well the item matches the attributes.<br /><br /><span class=\"tablenote\"><span style=\"color:#478415\"><strong>Tip:</strong></span> See the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#s0-1-21-6-7-7-6-ReturnItemsthatareCompatiblewiththeKeywordandVehicle-9\">Samples</a> section for a detailed example.</span><br /><b>Best Practice:</b> Submit all of the <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attributes</a> for the specific product.<br /><br />To find the attributes and values for a specific marketplace, you can use the <a href=\"/api-docs/commerce/taxonomy/resources/category_tree/methods/getCompatibilityProperties\">getCompatibilityProperties</a> method in the <a href=\"/api-docs/commerce/taxonomy/resources/methods\">Taxonomy API</a>.<br /><br />For more details, see <a href=\"/api-docs/buy/static/api-browse.html#Check\">Check compatibility</a> in the Buy Integration Guide.<br /><br /><span class=\"tablenote\"><b>Note:</b> Testing in Sandbox is only supported using mock data. See <a href=\"/api-docs/buy/static/api-browse.html#sbox-test\">Testing search in the Sandbox</a> for details.</span><br /><b>Required:</b><ul><li><b>q</b> (keyword)</li><li>One fitment supported category ID (such as <code>33559</code> Brakes)</li><li>At least one <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attribute</a> name/value pair</li></ul> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityFilter (optional)
* @param string $epid The ePID is the eBay product identifier of a product from the eBay product catalog. This field limits the results to only items in the specified ePID. <br /><br />The <b> Marketing</b> API <b>getMerchandisedProducts</b> method and the <b>Browse</b> API <b> getItem</b>, <b> getItemByLegacyId</b>, and <b> getItemsByItemGroup</b> calls return the ePID of the product. You can also use the <a href=\"/api-docs/commerce/catalog/resources/product_summary/methods/search\">product_summary/search</a> method in the <b>Catalog</b> API to search for the ePID of the product. <br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?epid=15032</code> <br /><br /><b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $fieldgroups This field is a comma separated list of values that lets you control what is returned in the response. The default is <b> MATCHING_ITEMS</b>, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information.<br /><br /><b>Valid Values:</b> <ul><li><b> ASPECT_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.aspectDistributions\">aspectDistributions</a> container, which has the <b>dominantCategoryId</b>, <b>matchCount</b>, and <b>refinementHref</b> for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be <b>Model Year</b>, <b>Exterior Color</b>, <b>Vehicle Mileage</b>, etc.<br /><br /><span class=\"tablenote\"> <b>Note:</b> ASPECT_REFINEMENTS are category specific.</span></li><li><b>BUYING_OPTION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.buyingOptionDistributions\">buyingOptionDistributions</a> container, which has the <b>matchCount</b> and <b>refinementHref</b> for <b>AUCTION</b>, <b>FIXED_PRICE</b> (Buy It Now), and <b>CLASSIFIED_AD</b> items.</li><li><b>CATEGORY_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.categoryDistributions\">categoryDistributions</a> container, which has the categories that the item is in.</li><li><b>CONDITION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.conditionDistributions\">conditionDistributions</a> container, such as <b>NEW</b>, <b>USED</b>, etc. Within these groups are multiple states of the condition. For example, <b>New</b> can be New without tag, New in box, New without box, etc.</li><li><b>EXTENDED</b> - This returns the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.shortDescription\">shortDescription</a> field, which provides condition and item aspect information and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.itemLocation.city\">itemLocation.city</a> field.</li><li><b>MATCHING_ITEMS</b> - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.</li><li><b>FULL</b> - This returns all the refinement containers and all the matching items.</li></ul>Code so that your app gracefully handles any future changes to this list.<br /><br /><b>Default:</b> MATCHING_ITEMS (optional)
* @param string $filter An array of field filters that can be used to limit/customize the result set. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]</code><br /><br />You can also combine filters. <br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}</code><br /><br /><span class=\"tablenote\"><span style=\"color:#004680\"><strong>Note:</strong></span> Refer to <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html\">Buy API Field Filters</a> for details and examples of all supported filters.</span> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField (optional)
* @param string $gtin This field lets you search by the Global Trade Item Number of the item as defined by <a href=\"https://www.gtin.info \" target=\"_blank\">https://www.gtin.info</a>. You can search only by UPC (Universal Product Code). If you have other formats of GTIN, you need to search by keyword. <br /><br /><b> For example: </b><br/><code> /buy/browse/v1/item_summary/search?gtin=099482432621</code> <br /><br /> <b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $limit The number of items from the result set returned in a single page. <br /><br /><span class=\"tablenote\"><b>Note:</b> If a value is set in the <b>limit</b> field, the value of <b>offset</b> must be either zero or a multiple of the <b>limit</b> value. An error is returned for invalid values of <b>offset</b>.</span> <br /><br /><b>Default:</b> 50 <br /><br /><b>Maximum number of items per page (limit):</b> 200 <br /><br /><b>Maximum number of items in a result set:</b> 10,000 (optional)
* @param string $offset Specifies the number of items to skip in the result set. This is used with the <b>limit</b> field to control the pagination of the output. <br /><br />For example, if <b>offset</b> is 0 and <b>limit</b> is 10, the method will retrieve items 1-10 from the list of items returned; if <b>offset</b> is 10 and <b>limit</b> is 10, the method will retrieve items 11-20 from the list of items returned. <br /><br /><span class=\"tablenote\"><b>Note:</b> The value of <b>offset</b> must be either zero or a multiple of the value set in the <b>limit</b> field. An empty result set is returned for invalid values of <b>offset</b>.</span> <br /><br /><b> Valid Values</b>: 0-10,000 (inclusive) <br /><br /><b>Default:</b> 0 <br /><br /><b>Maximum number of items returned:</b> 10,000 (optional)
* @param string $q A string consisting of one or more keywords that are used to search for items on eBay. The keywords are handled as follows:<ul><li>If the keywords are separated by a space, it is treated as an AND. In the following example, the query returns items that have iphone <b>AND</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=iphone ipad</code><br/><br /></li><li>If the keywords are input using parentheses and separated by a comma, or if they are URL-encoded, it is treated as an OR. In the following examples, the query returns items that have iphone <b>OR</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=(iphone, ipad)</code><br /><br /><code>/buy/browse/v1/item_summary/search?q=%28iphone%2c%20ipad%29</code><br /><br /></li></ul><b>Restriction:</b> The <code>*</code> wildcard character is <b>not</b> allowed in this field.<br /><br /><b>Required:</b> The method must have <b>category_ids</b>, <b>epid</b>, <b>gtin</b>, or <b>q</b> (or any combination of these). (optional)
* @param string $sort The order and field name that is used to sort the items. <br /><br />You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen (<code>-</code>) before the name of the sorting option. If no <b>sort</b> parameter is submitted, the result set is sorted by &quot;<a href=\"https://pages.ebay.com/help/sell/searchstanding.html \" target=\"_blank\">Best Match</a>&quot;.<br /><br />Here are some examples showing how to use the <b>sort</b> query parameter:<br /><ul><li><b><code>sort=distance</code></b> - This sorts by <i>distance</i> in ascending order (shortest distance first). This sorting option is only applicable if the <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html#pickupCountry\">pickup</a> filters are used, and only ascending order is supported.</li><li><b><code>sort=-price</code></b> - This sorts by <i>price + shipping cost</i> in descending order (highest price first). This sorting option (by <i>price</i>) is only guaranteed to work correctly if the <b>X-EBAY-C-ENDUSERCTX</b> request header is used, with the <b>contextualLocation</b> parameter being used to set the delivery country and postal code. Here is an example of how this header would be used to do this (note the URL encoding):<br /><br /><code>X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406</code><br /></li><li><b><code>sort=newlyListed</code></b> - This sorts by <i>listing date</i> (most recently listed/newest items first).</li><li><b><code>sort=endingSoonest</code></b> - This sorts by <i>date/time</i> the listing ends (listings nearest to end date/time first).</li></ul><b>Default:</b> Ascending For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:SortField (optional)
*
* @throws \InvalidArgumentException
*
* @return \GuzzleHttp\Promise\PromiseInterface
*/
public function searchAsyncWithHttpInfo($aspect_filter = null, $auto_correct = null, $category_ids = null, $charity_ids = null, $compatibility_filter = null, $epid = null, $fieldgroups = null, $filter = null, $gtin = null, $limit = null, $offset = null, $q = null, $sort = null)
{
$returnType = '\TNT\Ebay\Buy\Browse\V1\Model\SearchPagedCollection';
$request = $this->searchRequest($aspect_filter, $auto_correct, $category_ids, $charity_ids, $compatibility_filter, $epid, $fieldgroups, $filter, $gtin, $limit, $offset, $q, $sort);
return $this->client
->sendAsync($request, $this->createHttpClientOption())
->then(
function ($response) use ($returnType) {
if ($returnType === '\SplFileObject') {
$content = $response->getBody(); // Stream goes to serializer.
} else {
$content = (string) $response->getBody();
}
return [
ObjectSerializer::deserialize($content, $returnType, []),
$response->getStatusCode(),
$response->getHeaders(),
];
},
function ($exception) {
$response = $exception->getResponse();
$statusCode = $response->getStatusCode();
throw new ApiException(sprintf('[%d] Error connecting to the API (%s)', $statusCode, $exception->getRequest()->getUri()), $statusCode, $response->getHeaders(), (string) $response->getBody(), $exception instanceof \Throwable ? $exception : null);
}
);
}
/**
* Create request for operation 'search'.
*
* @param string $aspect_filter This field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red. <br /><br />For example, the method below uses the category ID for Women's Clothing. This will return only items for a woman's red shirt.<br /><br /><code>/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}</code> <br /><br />To get a list of the aspect pairs and the category, which is returned in the <b>dominantCategoryId</b> field, set <b>fieldgroups</b> to <code>ASPECT_REFINEMENTS</code>. <br /><br /> <code>/buy/browse/v1/item_summary/search?q=shirt&amp;fieldgroups=ASPECT_REFINEMENTS</code> <br /><br /><span class=\"tablenote\"><b> Note:</b> The pipe symbol is used as a delimiter between aspect filter values. If a value contains a pipe symbol (for example, the brand name 'Bed|Stü'), you must enter a backslash before the pipe character to prevent it from being evaluated as a delimiter. <br /><br />The following example shows the correct format for entering two brand names as aspect filter values, one of which contains a pipe symbol:<br /><br /><code>/buy/browse/v1/item_summary/search?limit=50&category_ids=3034&filter=buyingOptions:{AUCTION|FIXED_PRICE}&aspect_filter=categoryId:3034,Brand:{Bed&bsol;|Stü|Nike}</code></span><br /><br /><b>Required:</b> The category ID is required <i>twice</i>; once as a URI parameter and as part of the <b> aspect_filter</b>. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:AspectFilter (optional)
* @param string $auto_correct A query parameter that enables auto correction.<br /><br /><b>Valid Values:</b> <code>KEYWORD</code> (optional)
* @param string $category_ids <a name=\"category_ids\"></a>The category ID is used to limit the results. This field can have one category ID or a comma separated list of IDs.<br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?category_ids=29792</code> <br /><br /><span class=\"tablenote\"><b> Note: </b>Currently, you can pass in only one category ID per request.</span> <br /> <br />You can also use any combination of the <b> category_Ids</b>, <b> epid</b>, and <b> q</b> fields. This gives you additional control over the result set. <br /><br />For example, let's say you are looking of a toy phone. If you search for \"phone\", the result set will be mobile phones because this is the \"Best Match\" for this search. But if you also include the toy category ID, the results will be what you wanted. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=phone&category_ids=220</code><br /> <br />The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site: <ul> <li>Use the <a href=\"https://pages.ebay.com/sellerinformation/news/categorychanges.html \" target=\"_blank\">Category Changes page</a>.</li> <li>Use the Taxonomy API. For details see <a href=\"/api-docs/buy/buy-categories.html\">Get Categories for Buy APIs</a>. </li> <li>Submit the following method to get the <b> dominantCategoryId</b> for an item. <br /><br /><code>/buy/browse/v1/item_summary/search?q=<em> keyword</em>&fieldgroups=ASPECT_REFINEMENTS </code></li></ul> <span class=\"tablenote\"> <b> Note:</b> If a top-level (L1) category is specified, you <b> must</b> also include the <b> q</b> query parameter.</span> <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $charity_ids The charity ID is used to limit the results to only items associated with the specified charity. This field can have one charity ID or a comma separated list of IDs. The method will return all the items associated with the specified charities.<br /><br /> <b>For example:</b><br /><code>/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469</code><br /><br />The charity ID is the charity's registration ID, also known as the Employer Identification Number (EIN). In GB, it is the Charity Registration Number (CRN), commonly called \"Charity Number\". <ul><li>To find the charities eBay supports, you can search for a charity at <a href=\"https://charity.ebay.com/search \" target=\"_blank\">Charity Search </a> or go to <a href=\"https://www.ebay.com/b/Charity/bn_7114598164 \" target=\"_blank\">Charity Shop</a>.</li> <li>To find the charity ID of a specific charity, click on a charity and use the EIN number. For example, the charity ID for <a href=\"https://charity.ebay.com/charity/American-Red-Cross/3843 \" target=\"_blank\">American Red Cross</a>, is <code>530196605</code>.</li></ul> You can also use any combination of the <code>category_Ids</code> and <code>q</code> fields with a <code>charity_Ids</code> to filter the result set. This gives you additional control over the result set. <br /><br /><b>Restriction: </b> This is supported only on the US and GB marketplaces.<br /><br /><b>Maximum: </b> 20 IDs <br /><br /><b>Required:</b> One ID (optional)
* @param string $compatibility_filter This field specifies the attributes used to define a specific product. The service searches for items matching the keyword or matching the keyword and a product attribute value in the title of the item.<br /><br /><span class=\"tablenote\"><b>Note:</b> The only products supported are cars, trucks, and motorcycles.</span><br />For example, if the keyword is <code>brakes</code> and <code>compatibility-filter=Year:2018;Make:BMW</code>, the items returned are items with brakes, 2018, or BMW in the title.<br /><br />The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.compatibilityMatch\"> CompatibilityMatchEnum</a> value that indicates how well the item matches the attributes.<br /><br /><span class=\"tablenote\"><span style=\"color:#478415\"><strong>Tip:</strong></span> See the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#s0-1-21-6-7-7-6-ReturnItemsthatareCompatiblewiththeKeywordandVehicle-9\">Samples</a> section for a detailed example.</span><br /><b>Best Practice:</b> Submit all of the <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attributes</a> for the specific product.<br /><br />To find the attributes and values for a specific marketplace, you can use the <a href=\"/api-docs/commerce/taxonomy/resources/category_tree/methods/getCompatibilityProperties\">getCompatibilityProperties</a> method in the <a href=\"/api-docs/commerce/taxonomy/resources/methods\">Taxonomy API</a>.<br /><br />For more details, see <a href=\"/api-docs/buy/static/api-browse.html#Check\">Check compatibility</a> in the Buy Integration Guide.<br /><br /><span class=\"tablenote\"><b>Note:</b> Testing in Sandbox is only supported using mock data. See <a href=\"/api-docs/buy/static/api-browse.html#sbox-test\">Testing search in the Sandbox</a> for details.</span><br /><b>Required:</b><ul><li><b>q</b> (keyword)</li><li>One fitment supported category ID (such as <code>33559</code> Brakes)</li><li>At least one <a href=\"/api-docs/buy/static/api-browse.html#product-attributes\">product attribute</a> name/value pair</li></ul> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityFilter (optional)
* @param string $epid The ePID is the eBay product identifier of a product from the eBay product catalog. This field limits the results to only items in the specified ePID. <br /><br />The <b> Marketing</b> API <b>getMerchandisedProducts</b> method and the <b>Browse</b> API <b> getItem</b>, <b> getItemByLegacyId</b>, and <b> getItemsByItemGroup</b> calls return the ePID of the product. You can also use the <a href=\"/api-docs/commerce/catalog/resources/product_summary/methods/search\">product_summary/search</a> method in the <b>Catalog</b> API to search for the ePID of the product. <br /><br /><b> For example: </b><br/><code>/buy/browse/v1/item_summary/search?epid=15032</code> <br /><br /><b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $fieldgroups This field is a comma separated list of values that lets you control what is returned in the response. The default is <b> MATCHING_ITEMS</b>, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information.<br /><br /><b>Valid Values:</b> <ul><li><b> ASPECT_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.aspectDistributions\">aspectDistributions</a> container, which has the <b>dominantCategoryId</b>, <b>matchCount</b>, and <b>refinementHref</b> for the various aspects of the items found. For example, if you searched for 'Mustang', some of the aspect would be <b>Model Year</b>, <b>Exterior Color</b>, <b>Vehicle Mileage</b>, etc.<br /><br /><span class=\"tablenote\"> <b>Note:</b> ASPECT_REFINEMENTS are category specific.</span></li><li><b>BUYING_OPTION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.buyingOptionDistributions\">buyingOptionDistributions</a> container, which has the <b>matchCount</b> and <b>refinementHref</b> for <b>AUCTION</b>, <b>FIXED_PRICE</b> (Buy It Now), and <b>CLASSIFIED_AD</b> items.</li><li><b>CATEGORY_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.categoryDistributions\">categoryDistributions</a> container, which has the categories that the item is in.</li><li><b>CONDITION_REFINEMENTS</b> - This returns the <a href=\"#response.refinement.conditionDistributions\">conditionDistributions</a> container, such as <b>NEW</b>, <b>USED</b>, etc. Within these groups are multiple states of the condition. For example, <b>New</b> can be New without tag, New in box, New without box, etc.</li><li><b>EXTENDED</b> - This returns the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.shortDescription\">shortDescription</a> field, which provides condition and item aspect information and the <a href=\"/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.itemLocation.city\">itemLocation.city</a> field.</li><li><b>MATCHING_ITEMS</b> - This is meant to be used with one or more of the refinement values above. You use this to return the specified refinements and all the matching items.</li><li><b>FULL</b> - This returns all the refinement containers and all the matching items.</li></ul>Code so that your app gracefully handles any future changes to this list.<br /><br /><b>Default:</b> MATCHING_ITEMS (optional)
* @param string $filter An array of field filters that can be used to limit/customize the result set. <br /><br /><b> For example: </b><br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50]</code><br /><br />You can also combine filters. <br /><code>/buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal}</code><br /><br /><span class=\"tablenote\"><span style=\"color:#004680\"><strong>Note:</strong></span> Refer to <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html\">Buy API Field Filters</a> for details and examples of all supported filters.</span> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField (optional)
* @param string $gtin This field lets you search by the Global Trade Item Number of the item as defined by <a href=\"https://www.gtin.info \" target=\"_blank\">https://www.gtin.info</a>. You can search only by UPC (Universal Product Code). If you have other formats of GTIN, you need to search by keyword. <br /><br /><b> For example: </b><br/><code> /buy/browse/v1/item_summary/search?gtin=099482432621</code> <br /><br /> <b> Maximum: </b> 1 <br /><br /><b> Required: </b> The method must have <b> category_ids</b>, <b> epid</b>, <b> gtin</b>, or <b> q</b> (or any combination of these) (optional)
* @param string $limit The number of items from the result set returned in a single page. <br /><br /><span class=\"tablenote\"><b>Note:</b> If a value is set in the <b>limit</b> field, the value of <b>offset</b> must be either zero or a multiple of the <b>limit</b> value. An error is returned for invalid values of <b>offset</b>.</span> <br /><br /><b>Default:</b> 50 <br /><br /><b>Maximum number of items per page (limit):</b> 200 <br /><br /><b>Maximum number of items in a result set:</b> 10,000 (optional)
* @param string $offset Specifies the number of items to skip in the result set. This is used with the <b>limit</b> field to control the pagination of the output. <br /><br />For example, if <b>offset</b> is 0 and <b>limit</b> is 10, the method will retrieve items 1-10 from the list of items returned; if <b>offset</b> is 10 and <b>limit</b> is 10, the method will retrieve items 11-20 from the list of items returned. <br /><br /><span class=\"tablenote\"><b>Note:</b> The value of <b>offset</b> must be either zero or a multiple of the value set in the <b>limit</b> field. An empty result set is returned for invalid values of <b>offset</b>.</span> <br /><br /><b> Valid Values</b>: 0-10,000 (inclusive) <br /><br /><b>Default:</b> 0 <br /><br /><b>Maximum number of items returned:</b> 10,000 (optional)
* @param string $q A string consisting of one or more keywords that are used to search for items on eBay. The keywords are handled as follows:<ul><li>If the keywords are separated by a space, it is treated as an AND. In the following example, the query returns items that have iphone <b>AND</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=iphone ipad</code><br/><br /></li><li>If the keywords are input using parentheses and separated by a comma, or if they are URL-encoded, it is treated as an OR. In the following examples, the query returns items that have iphone <b>OR</b> ipad.<br /><br /><code>/buy/browse/v1/item_summary/search?q=(iphone, ipad)</code><br /><br /><code>/buy/browse/v1/item_summary/search?q=%28iphone%2c%20ipad%29</code><br /><br /></li></ul><b>Restriction:</b> The <code>*</code> wildcard character is <b>not</b> allowed in this field.<br /><br /><b>Required:</b> The method must have <b>category_ids</b>, <b>epid</b>, <b>gtin</b>, or <b>q</b> (or any combination of these). (optional)
* @param string $sort The order and field name that is used to sort the items. <br /><br />You can sort items by price, distance, or listing date. To sort in descending order, insert a hyphen (<code>-</code>) before the name of the sorting option. If no <b>sort</b> parameter is submitted, the result set is sorted by &quot;<a href=\"https://pages.ebay.com/help/sell/searchstanding.html \" target=\"_blank\">Best Match</a>&quot;.<br /><br />Here are some examples showing how to use the <b>sort</b> query parameter:<br /><ul><li><b><code>sort=distance</code></b> - This sorts by <i>distance</i> in ascending order (shortest distance first). This sorting option is only applicable if the <a href=\"/api-docs/buy/static/ref-buy-browse-filters.html#pickupCountry\">pickup</a> filters are used, and only ascending order is supported.</li><li><b><code>sort=-price</code></b> - This sorts by <i>price + shipping cost</i> in descending order (highest price first). This sorting option (by <i>price</i>) is only guaranteed to work correctly if the <b>X-EBAY-C-ENDUSERCTX</b> request header is used, with the <b>contextualLocation</b> parameter being used to set the delivery country and postal code. Here is an example of how this header would be used to do this (note the URL encoding):<br /><br /><code>X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406</code><br /></li><li><b><code>sort=newlyListed</code></b> - This sorts by <i>listing date</i> (most recently listed/newest items first).</li><li><b><code>sort=endingSoonest</code></b> - This sorts by <i>date/time</i> the listing ends (listings nearest to end date/time first).</li></ul><b>Default:</b> Ascending For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:SortField (optional)
*
* @throws \InvalidArgumentException
*
* @return \GuzzleHttp\Psr7\Request
*/
public function searchRequest($aspect_filter = null, $auto_correct = null, $category_ids = null, $charity_ids = null, $compatibility_filter = null, $epid = null, $fieldgroups = null, $filter = null, $gtin = null, $limit = null, $offset = null, $q = null, $sort = null)
{
$resourcePath = '/item_summary/search';
$formParams = [];
$queryParams = [];
$headerParams = [];
$httpBody = '';
$multipart = false;
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$aspect_filter,
'aspect_filter', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$auto_correct,
'auto_correct', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$category_ids,
'category_ids', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$charity_ids,
'charity_ids', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$compatibility_filter,
'compatibility_filter', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$epid,
'epid', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$fieldgroups,
'fieldgroups', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$filter,
'filter', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$gtin,
'gtin', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$limit,
'limit', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$offset,
'offset', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$q,
'q', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
// query params
$queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
$sort,
'sort', // param base name
'string', // openApiType
'form', // style
true // explode
) ?? []);
if ($multipart) {
$headers = $this->headerSelector->selectHeadersForMultipart(
['application/json']
);
} else {
$headers = $this->headerSelector->selectHeaders(
['application/json'],
[]
);
}
// For model (json/xml)
if (count($formParams) > 0) {
if ($multipart) {
$multipartContents = [];
foreach ($formParams as $formParamName => $formParamValue) {
$formParamValueItems = is_array($formParamValue) ? $formParamValue : [$formParamValue];
foreach ($formParamValueItems as $formParamValueItem) {
$multipartContents[] = [
'name' => $formParamName,
'contents' => $formParamValueItem,
];
}
}
// For HTTP post (form)
$httpBody = new MultipartStream($multipartContents);
} elseif ($headers['Content-Type'] === 'application/json') {
$httpBody = \GuzzleHttp\json_encode($formParams);
} else {
// For HTTP post (form)
$httpBody = ObjectSerializer::buildQuery($queryParams);
}
}
// this endpoint requires OAuth (access token)
if (! empty($this->config->getAccessToken())) {
$headers['Authorization'] = 'Bearer '.$this->config->getAccessToken();
}
// this endpoint requires OAuth (access token)
if (! empty($this->config->getAccessToken())) {
$headers['Authorization'] = 'Bearer '.$this->config->getAccessToken();
}
$defaultHeaders = [];
if ($this->config->getUserAgent()) {
$defaultHeaders['User-Agent'] = $this->config->getUserAgent();
}
$headers = array_merge(
$defaultHeaders,
$headerParams,
$headers
);
$query = ObjectSerializer::buildQuery($queryParams);
return new Request(
'GET',
$this->config->getHost().$resourcePath.($query ? "?{$query}" : ''),
$headers,
$httpBody
);
}
/**
* Create http client option.
*
* @throws \RuntimeException on file opening failure
*
* @return array of http client options
*/
protected function createHttpClientOption()
{
$options = [];
if ($this->config->getDebug()) {
$options[RequestOptions::DEBUG] = fopen($this->config->getDebugFile(), 'ab');
if (! $options[RequestOptions::DEBUG]) {
throw new \RuntimeException('Failed to open the debug file: '.$this->config->getDebugFile());
}
}
return $options;
}
}