eBay Inc. Landscape Lighting 3.7 User's Manual
Contents
1. Chapter 1 Using the REST API 8 Obtaining Tokens and Testing Calls Obtaining a REST Token for the Sandbox To begin testing a REST API application in the Sandbox environment the Sandbox you must use the following steps to obtain a REST token Note that GetSearchResults is supported in the Sandbox but GetSearchResultsExpress is supported only in the production environment Join eBay by registering for an eBay User ID 2 Join the eBay Developers Program Information on joining is available at the following location After you join note the Sandbox keys you receive via email http developer ebay com 3 Create a Sandbox environment test user with the Sandbox User Registration Tool at the following location The Sandbox User Registration Tool creates a test user for the Sandbox test environment Note the user name and password of the test user http developer ebay com DevZone sandboxuser asp 4 With the Sandbox keys you noted in Step 2 and with the user name and password of the test user you noted in Step 3 obtain a REST token for the Sandbox at the following location http developer ebay com tokentool The REST token is used by eBay to identify who makes calls to the REST API The REST token must be specified in the RequestToken parameter in your REST API calls You can use the GetUser call in the unified schema to obtain a user s REST token if one is available For information about GetUser see the following topic2. The lowest price in the Current Price field that any item returned by the Search results should have Maximum distance to use for sorting by distance This is used in proximity searches Maximum number of items matching search criteria to return You can specify up to 400 items per call The valid range for this parameter is 1 to 400 and the default is 100 Valid range for eBay Motors searches 1 to 30 Use Skip to specify the number of items to skip when building the result set Use MaxResults and Skip together to paginate your results set Used with the ModifierCode parameter The SiteIdFilterType parameter is a more current filter than Modifier Used with the Modifier parameter The SiteIdFilterType parameter is a more current filter than Modifier Filter that limits the response to active items whose status has changed since the specified time Version 3 7 Chapter 1 Using the REST API 27 Legacy REST GetSearchResults Input Table 1 5 Legacy GetSearchResults Input Parameters See GetSearchResults Input Parameters on page 10 MotorsGermanySearch able NowAndNew Order PayPal PostalCode Producerad Query Quantity QuantityOp Region RestScript Schema N Y Y N Y N Boolean Boolean String Boolean String String Sering Integer String Integer Boolean Boolean Filter that limits the response according to whether the item is eligible to be listed in se
3. symbol i e Element attribute Version 3 7 3 Chapter 1 Using the REST API 4 Basic REST Input Parameters Repeating Parameters Beginning in early 2007 if parameters in a request repeat you can use the symbol i e Element Number Before early 2007 parameters in a request cannot repeat For example the following URL contains parameters for including descriptions in a search and also for specifying that only items listed with Now and New be returned http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserlId UserName amp Query slipp ers amp SearchFlags 1 SearchInDescription amp SearchFlags 2 NowAndNew amp Version 491 amp UnifiedInput 1 Please note that if you are using the GetPopularKeywords call you cannot specify a CategoryID parameter more than once per call Required Parameters Several input parameters listed in the table below are required in REST API calls Additional information about required REST input parameters is in the Knowledge Base Knowledge Base http developer ebay com DevZone support knowledgebase asp For specifying a site other than the US site which is site 0 in your call include a sitera parameter for the site For more information please see Specifying International Sites on page 7 To learn about the eBay Affiliate Program please see http affiliates ebay com and Affiliate Parameters on page 5 The following
4. GetSearchResults legacy REST input a CompatibilityLevel parameter various problems can occur Recent API versions have more features than older versions and version thresholds are periodically set as the minimum supported version More information is in the unified schema documentation accessible from http developer ebay com support docs Schema The Schema parameter only applies to GetSearchResults For GetSearchResullts if you do not include the UnifiedInput parameter and set it to 1 you must include the Schema parameter and set it to 1 Thus the Schema parameter is required only in the following case In GetSearchResults you are not using the UnifiedInput parameter In such a case the Schema 1 parameter returns data in the unified schema format If omitted in this case or if you set it to 0 the results are returned in the legacy XML API format which is not supported as of June 1 2006 For additional information see Find Items with GetSearchResults on page 9 Error Information The REST API returns error information if a call is invalid Error information is returned within an Errors field The Errors field includes a ShortMessage field and a LongMessage field The ShortMessage field indicates why the error occurred The LongMessage field provides a more verbose message if applicable For additional information see the unified schema documentation on which the REST API is based http developer ebay com
5. GetUser 5 Congratulations You are ready to begin making REST calls in the Sandbox environment See the Sandbox URL for the REST API in Basic REST Input Parameters on page 3 Note The REST token is not the same as the authentication token required to use other eBay APIs Using the REST API in Production After testing your REST calls in the Sandbox environment to get set up in the Sandbox environment see Obtaining a REST Token for the Sandbox on page 8 you are ready to use the production environment To use the REST API in the production environment you must obtain production keys The Sandbox keys described in Obtaining a REST Token for the Sandbox on page 8 do not apply to the production environment To use the REST API in the production environment Join eBay by registering for an eBay User ID Join the eBay Developers Program Submit your application or Web page for certification and note your production keys Information on certification is available at the following location http developer ebay com Version 3 7 Chapter 1 Using the REST API 9 Find Items with GetSearchResults 4 Using your production keys obtain a REST token for an eBay user at the following location http developer ebay com tokentool If you already have obtained a REST token for an eBay user you can retrieve it with the GetUser call For more information see GetUser in the unified schema documentation access
6. on page 8 Server side processing of uploaded XSL files is not available in the Sandbox environment Calls to the eBay REST API that utilize server side processing are made using the following URL http www ebayxslt com ws web apixslt If you make a call to the eBay REST API that utilizes server side processing and omit the UnifiedInput parameter the data returned is in unified schema format whether or not you add the Schema 1 setting For information on the Schema 1 setting see Basic REST Input Parameters on page 3 This section of the REST API Guide contains the following subsections Uploading and Using XSL Files on page 20 Viewing Renaming and Deleting XSL Files on page 21 Uploading and Using XSL Files After you have production keys and at least one production certified application you can upload XSL files to the XML to HTML Transform tool The XML to HTML Transform tool is accessible from a link on the REST Developer Center page http developer ebay com developercenter rest You use the XML to HTML Transform tool by entering a production Developer Id DevId key The Devld key is the first key of the DevId AppId Certld set of keys It is an alphanumberic string After you enter your DevId you can upload the XSL files that eBay servers will use to transform data returned by the REST API The eBay servers will use the Saxon 6 5 2 processor for transformations Each file you upload is associated with a prod
7. Architectural Style wiki page http c2 com cgi wiki RestArchitecturalStyle RESTWiki http rest blueoxen net cgi bin wiki pl FrontPage eBay API Documentation The eBay API documentation is available on the eBay Developers Program Web site eBay Developers Program Web site http developer ebay com Version 3 7 ey Index eBay Affiliate Program 5 eBay REST API required parameters 3 URL for the 3 URL for the Sandbox 3 URL for using transformations 20 using ina web page 14 17 using in an application 14 17 G GetSearchResults output fields 12 GetSearchResults samples 10 H HTTP protocol 29 P production keys 8 R REST additional information on 29 contrasted with SOAP web services 29 REST token how to geta 8 S Sandbox REST API support 8 search query modifiers 12 search results paginating 13 T tracking enabling in the search results 5 transforming data returned 20 U URL size limitation 3 Index Version 3 7 30 ey Index 31 developers program Version 3 7
8. GetSearchResults described in Find Items with GetSearchResults on page 9 Version 3 7 Chapter 1 Using the REST API 16 Retrieve Product Information with GetProducts GetProducts includes input parameters for retrieving the following types of product information m Stock catalog information about a particular DVD digital camera or a variety of other products m Product titles stock photos and Item Specifics URLs to help you create links to additional catalog content on eBay m Up to 200 active items that were listed with a product Up to 20 of the top reviews written by eBay members For example to use the QueryKeywords parameter to search for products that match harry potter you can specify an URL similar to the following http rest api ebay com restapi CallName GetProducts amp RequestToken UserToken amp RequestUserld UserName amp ProductSearch Qu eryKeywords Harry Potter amp ProductSearch Pagination EntriesPerPage 2 amp ProductSearch Pagination Pag eNumber 1 amp Version 505 The response includes two products Each product returns a ProductReferencelID that can be used as input to GetProducts to retrieve reviews items associated with the product or both Some types of products like books also return an ExternalProductID that can be used as an alternative to ProductReferenceID Each product also return an ItemSpecifics node which provides some standard information about the product For example book products usual
9. String Optional value that depends on your tracking partner tracking provider For example if you specify a TrackingPartnerCode of 1 for Commission Junction the Af filiateUserID is your Commission Junction Shopper ID SID Specifying International Sites To specify a site other than the US site which is site 0 in your call include a sitera parameter for the site and for GetSearchResults the searchLocationFilter SearchLocation SiteLocation SiteID parameter The sitera parameter is case sensitive For example to search for items listed on the Germany site you could specify the following http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserId UserName amp Query toy 20boat amp Version 49 1 amp UnifiedInput 1 amp SiteId 77 amp SearchLocationFilter SearchLocation SiteLocation Sit eID SiteImplied Please see the Field Differences for eBay Sites topic in the unified schema documentation for additional information about international sites including the values to use in the site1d parameter http developer ebay com DevZone XML docs WebHelp index htm context eBay_XML_API amp topic FieldDifferences Obtaining Tokens and Testing Calls This section of the REST API Guide contains the following subsections Obtaining a REST Token for the Sandbox on page 8 Using the REST API in Production on page 8 Testing REST Calls Using a Browser on page 9 Version 3 7
10. amp RequestUserlId UserName amp ltemID 123 456789123 amp DestinationPostalCode 40404 amp DestinationCountryCode US amp Version 491 Parameters for GetltemShipping are the same in the REST API as in the unified schema except for the basic REST input parameters For the REST specific input parameters see Basic REST Input Parameters on page 3 For more information about using GetItemShipping including descriptions of the call specific input and output parameters see the following document GetItemShipping General information about the unified schema format is available at the following location http developer ebay com support docs After you have tested your program s ability to handle output you can use your program in production to transform output or you can enable server side processing Server side processing uses your XSL files to format the output for you For more information on server side processing that uses your XSL files see Transforming Data Returned on page 20 Obtain a Category Hierarchy with GetCategories GetCategories retrieves the latest category hierarchy available on a site You can retrieve all categories on the site or one particular category and its subcategories You can use GetCategories to retrieve category information before you use GetCategoryListings see Find Items in a Category with GetCategoryListings on page 13 For example you can specify the ID of the highest level category you want
11. an item will only include the condition attribute if the item s seller filled in the listing s Item Condition in the Item Specifics section of the listing That is the condition attribute is not returned if the seller only put the word New or Used in the listing s title but did not specify the condition in the listing s Item Specifics If 0 or not specified the item condition is not returned Note that this field does not control whether to retrieve only new or used items In some categories you can use a product finder search SearchRequest to only retrieve new or used items When passed with a value of 1 true each item in the result set also includes information about the seller s feedback the positive feedback percentage whether or not the seller has chosen to keep their feedback private and the feedback score When passed with a value of 1 true restricts listings returned to Get It Fast listings Restricts search to the sellers specified Specify the seller s user ID Separate multiple sellers with a comma A maximum of 100 sellers can be listed Cannot be used with ExcludeSellers and PayPal parameters StoreSearch overrides IncludeSellers When passed with a value of 1 true restricts listings returned to only those for which LotSize is 2 or greater Filters items returned by the type of listing Valid values are 1 Auction items only 2 Fixed price items both Fixed Price and Buy It Now 3 All items
12. following sections describe specific aspects of the GetSearchResults call GetSearchResults Samples on page 10 GetSearchResults Input Parameters on page 10 GetSearchResults Query Modifiers on page 12 GetSearchResults Output Fields on page 12 GetSearchResults Samples This section contains REST API samples that use the GetSearchResults call Please substitute your eBay user name and your REST token for userName and UserToken The following URL provides a search of the listing title and description using fuzzy slippers a maximum of 5 results will be returned http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserId UserName amp Query fuzz y 20slippers amp EntriesPerPage 5 amp PageNumber 1 amp SearchFlags SearchInDescription amp Version 491 amp Unifi edInput 1 The following URL uses a Query parameter of kitchen table and sorts the items in the response in ascending order based on whether PayPal is accepted accepted followed by unaccepted http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserId UserName amp Query kitch en 20table amp Order SortByPayPalAsc amp Version 491 amp UnifiedInput 1 GetSearchResults Input Parameters Formerly REST input parameters for GetSearchResults were similar to the legacy XML API input parameters for GetSearchResults Now all applications must be migrated from legacy input pa
13. logic to multiple keywords Requires an exact sequence of words Specified word cannot be present Specified words cannot be present Substitutes for one or more characters Search must find two of three words from a list Concatenates a query string using AND logic with another keyword baseball 20card baseball card baseball card baseball1 20card basebal1l 20 autograph baseball 20 autograph card star baseball 401 20baseball 20autograph 20card 401 S20baseball 20autograph 20card 20 star Items with both the words baseball and card Items with both the words baseball and card Items with either the word baseball or the word card Items with the exact phrase baseball card Note that spaces must be URL encoded as 20 Items that have the word baseball but not autograph Items with the word baseball but not autograph card or star a Items starting with the string baseball Items with two of the three words baseball autograph and card For a 3 out of 4 search use 2 URL encoded as 402 and a list of four words Items with any two of the three words baseball autograph or card in the title plus the word star GetSearchResults Output Fields The output of the GetSearchResults call in the REST API is similar to the output of the GetSearchResults call in the unified schema Please see the following unified sche
14. returned in order to return that category and its subcategories http rest api ebay com restapi CallName GetCategories amp RequestToken UserToken amp RequestUserld UserName amp CategoryParent 200818 amp DetailLevel ReturnAll amp Version 491 GetCategories can return a large amount of data in the response To use this call see the article Best Practices for GetCategories API call in the Developers Program Knowledge Base Although the article applies to the call in the unified schema you can convert the unified schema XML code in the article Version 3 7 Chapter 1 Using the REST API 19 Obtain Keywords with GetPopularKeywords by using an URL instead of XML and adding the necessary REST parameters see Basic REST Input Parameters on page 3 https ebay custhelp com cgi bin ebay cfg php enduser std_adp php p_faqid 597 For a category GetCategories returns the category name its unique ID within the site you specify and meta data that helps you determine where the category fits in the category hierarchy Parameters for GetCategories are the same in the REST API as in the unified schema except for the basic REST input parameters For the REST specific input parameters see Basic REST Input Parameters on page 3 For more information about using GetCategories including descriptions of the call specific input and output parameters see the following document GetCategories General information about the unified
15. support docs Affiliate Parameters If you use affiliate parameters it is possible to obtain affiliate commissions based on calls made by your Web page application or script Affiliate parameters enable the tracking of user activity For more information about the eBay Affiliate Program please see http affiliates ebay com For individual descriptions of the affiliate parameters see Affiliate Parameter Descriptions on page 6 Commissions are generated when users submit bids or do other qualifying actions For example if a user bids on an item after clicking a search result a commission is generated Version 3 7 Chapter 1 Using the REST API 6 Basic REST Input Parameters In the REST API affiliate parameters can be used with the following calls m GetSearchResults see Find Items with GetSearchResults on page 9 m GetSearchResultsExpress see Find Items with GetSearchResultsExpress on page 14 m GetProducts see Retrieve Product Information with GetProducts on page 15 This sample shows how to specify affiliate parameters in GetSearchResults http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserlId UserName amp Query tape amp TrackingPartnerCode MyTrackingPartnerCode amp AffiliateUserID MyAffiliateUserID amp TrackingID MyTrackin gID amp Version 491 amp UnifiedInput 1 This sample shows how to specify affiliate parameters for GetSearchResultsExpress ht
16. to Transform Data Returned 1 Test a production URL without trying to utilize your XSL file using the standard URL for the REST API For more information see Basic REST Input Parameters on page 3 Use the same values for Request Token and RequestUserid that you will use in the call that includes the parameter for transforming data returned 2 Complete your successfully tested production URL so it will result in transformed data returned 2a Replace the http rest api ebay com restapi portion of the URL with http www ebayxslt com ws web apixslt 2b Add filetag FormatInxTML1 to the end of the URL replacing Format Inutmui with the File Tag of the file you uploaded in Step 1 For example the URL for a GetSearchResults call might be similar to this http www ebayxslt com ws web apixsit CallName GetSearchResults amp RequestToken UserToken amp RequestUserId UserName amp Query toy 20boat amp filetag ResultsINHTML amp Version 491 amp UnifiedInput 1 3 Use the completed URL in your browser to make a call to the REST API Viewing Renaming and Deleting XSL Files After you have uploaded XSL files you can view them rename their file tags and delete them as necessary For information on uploading XSL files see Uploading and Using XSL Files on page 20 View an XSL File on page 22 Rename an XSL File Tag on page 22 Delete an XSL File on page 22 Version 3 7 Chapter 1 Using the REST API 22
17. SBN or UPC Only applicable for items with Pre filled Item Information in media categories such as Books and Music In the REST API you can use XPATH for parameters that are containers or have attributes such as the ExternalProductldentifier parameter In the case of ExternalProductldentifier id and type are attributes because ExternalProductIdentifier is defined as lt ExternalProductldentifier id value type Vvalue gt An example of using XPATH is the following search for an ISBN of 0811645169 CallName GetSearchResults amp ExternalProductldentifier type ISBN amp ExternalProductldentifier id 0811645169 Reduces the number of tags returned for items The highest price in the Current Price field that any item returned by the Search results should have Version 3 7 Chapter 1 Using the REST API 26 Legacy REST GetSearchResults Input Table 1 5 Legacy GetSearchResults Input Parameters See GetSearchResults Input Parameters on page 10 IncludeCondition IncludeFeedback IncludeGetItFast IncludeSellers TSLOE ItemTypeFilter LowestPrice MaxDistance MaxResults Modifier ModifierCode ModTimeFrom Y N Boolean Boolean Boolean String Boolean Integer Money Integer ITnteger String String Time When passed with a value of 1 true each item in the result set can also include the item condition attribute e g New or Used if the seller specified it In this case
18. SearchResults amp RequestToken UserToken amp RequestUserlId UserName amp Query toy 20boat amp Schema 1 amp CompatibilityLevel 475 This legacy input sample shows use of a category ID in the request http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserlId UserName amp Category 6 17 amp Query star trek amp Schema 1 amp CompatibilityLevel 475 This legacy input sample shows a search for listing titles and descriptions that contain fuzzy slippers a maximum of 5 results is returned http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserId UserName amp Query fuzz y 20slippers amp MaxResults 5 amp SearchInDescription 1 amp Schema 1 amp CompatibilityLevel 475 Legacy Affiliate Parameters for GetSearchResults This sample shows use of affiliate parameters in GetSearchResults using legacy input parameters http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserld UserName amp Query tape Version 3 7 Chapter 1 Using the REST API 24 Legacy REST GetSearchResults Input amp TrackingProvider MyTrackingProvider amp TrackingId MyTrackingId amp CJSID MyCJSID amp Schema 1 amp Compati bilityLevel 491 All applications must be migrated from legacy input parameters to unified schema input parameters Please see the following section of this guide for the unified schema GetSearchResults input parameters GetS
19. Transforming Data Returned View an XSL File To view an XSL file that you have uploaded 1 5 Enter your production Developer Id DevId in the XML to HTML Transform tool accessible from the REST Developer Center page http developer ebay com developercenter rest If multiple applications are associated with your DevId the applications are displayed From the list of applications select the application with which your XSL file is associated and click Next If only one application is associated with your DevId the REST XSLT Home page is displayed On the REST XSLT Home page the name of your application is displayed Select an XSL file to view by clicking its File Tag Note that the names of the files that is the file names associated with the File Tags are not used to track XSL files After an XSL file is uploaded the file is tracked by a File Tag not by a file name On the View XSL file page you can view the file but you cannot modify it If you want to change the file copy its text to a text file save the file and see Uploading and Using XSL Files on page 20 for information about uploading the file When you are finished viewing the file click Go Back to return to the REST XSLT Home page Rename an XSL File Tag To rename the File Tag of an XSL file that you have uploaded 1 Enter your production Developer Id DevId in the XML to HTML Transform tool accessible from the REST Developer Center page http dev
20. arch results on the mobile de site Filter that limits the response to items listed with Now amp New Specifies the sort order of the returned list of items Default is MetaEndSort Not all values can be used with eBay Motors searches When passed with a value of 1 true restricts items returned to only those where PayPal is accepted as a buyer payment option Default is 0 false Cannot be used with IncludeSellers and ExcludeSellers arguments Applicable when searching sites that support PayPal ignored for sites that do not support PayPal The zip or postal code from which to compute the distance This is required when constraining searches with proximity Exclusive filter to retrieve items that were listed with the specified eBay catalog product If you specify a product ID that is no longer in use eBay will use the product s current ID if available instead with no warning You must specify Productld Query ExternalProductldentifier IncludeSellers or Category in the request Productld cannot be used in combination with Query ExternalProductIdentifier or Category Specifies the search string The search string consists of one or more keywords to search for in the listing title and or description Use characters in the UTF 8 character set The words and and or are treated like any other word Only use and or or the if you are searching for listings containing these words You can use AND or OR logic by inclu
21. ble Express to calculate shipping costs This example also shows the effects of setting HistogramDetails ProductDetails and ItemDetails tO Fine http rest api ebay com restapi CallName GetSearchResultsExpress amp RequestToken UserToken amp RequestUserld UserName amp Que ry garmin gps receiver amp EntriesPerPage 3 amp Version 491 amp DepartmentName Consumer_Electronics amp Hi stogramDetails Fine amp HistogramSort Alphabetical amp ProductDetails Fine amp ProductSort LowestPrice amp ltem Details Fine amp ItemSort LowestTotalCost amp PostalCode 95125 The following sample shows how to search for a book with Pre filled Item Information by using an ISBN as an external product ID You can also use this approach to search for items by UPC Please note that the ExternalProductID query only finds items that were listed with Pre filled Item Information That is if the seller did not pre fill an item s Item Specifics based on a stock catalog product this query will not find the item http rest api ebay com restapi CallName GetSearchResultsExpress amp RequestToken UserToken amp RequestUserlId UserName amp Entri esPerPage 3 amp Version 491 amp ExternalProductIDType ISBN amp ExternalProductIDValue 0439425239 amp Produc tDetails Fine amp ItemDetails Fine amp Condition All Retrieve Product Information with GetProducts You can use GetProducts to retrieve a variety of product information GetProducts retrieves more buying guide details as available than
22. ble to all or most calls see Required Parameters on page 4 The calls available for use in the REST API are the following GetSearchResults To search eBay see Find Items with GetSearchResults on page 9 GetCategoryListings To find items on eBay based on their category see Find Items in a Category with GetCategoryListings on page 13 GetSearchResultsExpress To search eBay Express see Find Items with GetSearchResultsExpress on page 14 GetItem To obtain detailed information about an item see Obtain Item Data with GetItem on page 17 GetItemShipping To obtain estimated shipping cost information for an item see Obtain Shipping Costs with GetltemShipping on page 18 GetCategories To retrieve the latest category hierarchy see Obtain a Category Hierarchy with GetCategories on page 18 GetPopularKeywords To obtain keywords that users have frequently specified when searching eBay see Obtain Keywords with GetPopularKeywords on page 19 Version 3 7 Chapter 1 Using the REST API Basic REST Input Parameters Basic REST Input Parameters This section of the REST API Guide contains the following subsections Root URLs Containers and Repeating Parameters on page 3 Required Parameters on page 4 Error Information on page 5 Affiliate Parameters on page 5 Specifying International Sites on page 7 Root URLs Containers and Repeating Parameters Thi
23. d required parameters Formerly REST input parameters for GetSearchResults were similar to the legacy XML API input parameters for GetSearchResults Now you must begin specifying unified schema parameters for GetSearchResults The unified schema is standardized and uses objects for data exchange Additionally parameters specific to GetSearchResults are not case sensitive All applications must be migrated from legacy input parameters to unified schema input parameters For more information see GetSearchResults Input Parameters on page 10 Version 3 7 Chapter 1 Using the REST API 10 Find Items with GetSearchResults Using GetSearchResults you can filter results using many criteria including category and currency For example an URL similar to the following might be used to search a category 617 for listings with star trek http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserId UserName amp CategoryID 617 amp Query star trek amp Version 491 amp UnifiedInput 1 The keywords can include wildcards The response is an array You can filter the item listings returned using such criteria as the listing category the location whether the item is listed in an eBay Store and the listing type You cannot use GetSearchResults to search or browse eBay Express For information about finding items on eBay Express see Find Items with GetSearchResultsExpress on page 14 The
24. developers program Web Services REST API Guide Version 3 7 Copyright Notice ii Copyright Notice 2004 2007 eBay Inc All rights reserved The information contained in this software manual is proprietary and confidential For information contact Developer Relations developer relations ebay com This manual and the REST API may only be used in accordance with the terms of the Developers Program agreement References to names of people and companies in source code examples or descriptions are for demonstration purposes only and do not refer to any real people or companies eBay and the eBay logo are registered trademarks of eBay Inc All other brands are the property of their respective owners ey Contents Chapter 1 Chapter 2 Using the REST API Introductory Samples Information in this Guide Calls Available in the REST API Basic REST Input Parameters Root URLs Containers and Repeating Parameters Required Parameters Error Information Affiliate Parameters Specifying International Sites Obtaining Tokens and Testing Calls Obtaining a REST Token for the Sandbox Using the REST API in Production Testing REST Calls Using a Browser Find Items with GetSearchResults GetSearchResults Samples GetSearchResults Input Parameters GetSearchResults Query Modifiers GetSearchResults Output Fields Find Items in a Category with GetCategoryListings Find Items with GetSearchResultsExpress GetSearchResultsExpress Sample
25. ding certain modifiers Wildcards e g are also supported Be careful when using spaces before or after modifiers and wildcards or The total number of objects desired If IsLot is also specified then Quantity is the number of lots times the number of objects in each lot Use QuantityOp to specify that you are seeking quantities greater than equal to or less than Quantity An operator that specifies the relationship of the desired quantity to the integer value in Quantity Valid values are It lt le lt eq gt gt and ge gt Numeric ID for a region Limits the search to items listed ina specified region If true 1 specifies to surround the entire search results with document write This is useful in certain situations where you want to use scripting on the result set Defaults to false 0 Specify Schema 1 to return data in the unified schema format If omitted or if you set it to 0 the results are returned in the Legacy XML API format and output in that format is not supported as of June 1 2006 Version 3 7 Chapter 1 Using the REST API 28 Legacy REST GetSearchResults Input Table 1 5 Legacy GetSearchResults Input Parameters See GetSearchResults Input Parameters on page 10 SearchInDescription SearchType SellerBusinessType SitelId SiteIdFilterType Skip StoreID StoreName StoreSearch TotalOnly Boolean N Integer N Integer N nt
26. earchResults Input Parameters on page 10 The following table describes the legacy GetSearchResults affiliate parameters Table 1 4 Legacy GetSearchResults Parameters for Affiliate Tracking TrackingProvider Integer Specifies the third party e g Commission Junction who is your tracking partner tracking provider Depending on your tracking partner specify one of the following values Not all partners are valid for all sites 1 Commission Junction 2 Be Free 3 Affilinet 4 TradeDoubler 5 Mediaplex 6 DoubleClick 7 Allyes 8 BJMT TrackinglId N String Specifies an ID to identify you to your tracking partner tracking provider The value you specify is obtained from your tracking partner For example in the case of Commission Junction this parameter is the PID given to you by Commission Junction CJSID N String Optional value that specifies the Commission Junction Shopper ID SID This parameter is applicable if you used 1 Commission Junction for the TrackingProvider parameter CJSID is a user defined ID number for identifying specific search result placement of Commission Junction affiliates You can specify up to 30 characters plus HTML encoded spaces commas periods and the character but you cannot specify zero or non alpha numeric characters Legacy Input Parameters for GetSearchResults All applications must be migrated from legacy input parameters to unified schema input paramete
27. eger N nteger N nteger N nteger N String N Integer N Boolean If true 1 specifies to search in item titles subtitles and descriptions for the string specified in Query Defaults to false 0 title search only Restricts items returned to selectively only gallery items or gallery and non gallery items Valid values are 0 Search for gallery and non gallery items 1 Search for gallery items only and display a preview thumbnail image of gallery picture Limits the listings to those of a specified type of business Possible values 0 Undefined 1 Private 2 Commercial Specifies the eBay site to be searched and from which to retrieve items meeting the search criteria If not specified then the default US eBay site is searched Allows filtering of category listings by Siteld Specifies the number of items to skip over counting from the first in paginating results Restricts the search to the specified Store Only applicable in the Sandbox You must specify a value in StoreID in the Sandbox if StoreSearch 0 1 or 2 Restricts the search to the specified Store You must specify a value in StoreName if StoreSearch 0 1 or 2 The StoreName parameter is case sensitive The maximum length is 46 Restricts the search to items that are listed in eBay Stores Stores Inventory items and or fixed price and auction items that also appear in a seller s eBay Store Use the StoreSearch value to specify which s
28. eloper ebay com developercenter rest If multiple applications are associated with your DevId the applications are displayed From the list of applications select the application with which your XSL file is associated and click Next If only one application is associated with your DevId the REST XSLT Home page is displayed On the REST XSLT Home page the name of your application is displayed Select an XSL File Tag to change by clicking a current File Tag On the View XSL file page click Rename On the Rename File page enter a new File Tag and click Rename On the View XSL file page the new File Tag is displayed above the Rename button Delete an XSL File To delete an XSL file that you have uploaded 1 Enter your production Developer Id DevId in the XML to HTML Transform tool accessible from the REST Developer Center page http developer ebay com developercenter rest If multiple applications are associated with your DevId the applications are displayed From the list of applications select an application with which your XSL file is associated and click Next If only one application is associated with your DevId the REST XSLT Home page is displayed On the REST XSLT Home page the name of your application is displayed Select an XSL file to delete using the associated checkbox You can select multiple files to delete at once Click Delete The status of the deletion is displayed under the Upload New File button Versi
29. ersion 3 7 Chapter 1 Using the REST API 15 Retrieve Product Information with GetProducts GetSearchResultsExpress in the REST API has many similarities to GetSearchResultsExpress in the unified schema A link to more information which show more ways to use this call is in the following topic This unified schema topic contains detailed information about the call and can answer many questions http developer ebay com DevZone XML docs WebHelp index htm context eBay_XML_API amp topic ExpressSearch The following sample shows how to use the Query parameter to search by keywords http rest api ebay com restapi CallName GetSearchResultsExpress amp RequestToken UserToken amp RequestUserld UserName amp Que ry garmin gps amp EntriesPerPage 3 amp Version 491 The following sample shows how to retrieve all the departments aisles and product types that are currently on Express To make sure all the details are retrieved HistogramDetails is set to Fine http rest api ebay com restapi CallName GetSearchResultsExpress amp RequestToken UserToken amp RequestUserld UserName amp Vers ion 491 amp DepartmentName Express amp HistogramDetails Fine amp HistogramSort Alphabetical The following sample shows how to sort items in the GetSearchResultsExpress response by the lowest total cost which includes the current fixed price plus default shipping costs This request sets ItemSort tO LowestTotalCost and it includes a postal code in Postalcode to ena
30. fPages indicates the total number of pages that could be returned by repeated requests based on what you specified for EntriesPerPage The value in Pagination PageNumber indicates the page number of the data returned in a call Find Items in a Category with GetCategoryListings With GetCategoryListings you can find items on eBay based on a category You can filter results using many criteria such as location whether the item is listed in an ebay Store and the listing type The response is an array For example you could use an URL similar to the following to retrieve items in category 20081 http rest api ebay com restapi CallName GetCategoryListings amp RequestToken UserToken amp RequestUserId UserName amp Categoryl D 200818 amp DetailLevel ReturnAll amp Version 491 You can use GetCategories to retrieve category information before you use GetCategoryListings see Obtain a Category Hierarchy with GetCategories on page 18 Parameters for GetCategoryListings are the same in the REST API as in the unified schema except for the basic REST input parameters For the REST specific input parameters see Basic REST Input Parameters on page 3 For more information about using GetCategoryListings including descriptions of the call specific input and output parameters see the following document GetCategoryListings General information about the unified schema format is available at the following location http developer ebay co
31. ible from the following location http developer ebay com support docs 5 To begin making REST calls in production see the production URL for the REST API in Basic REST Input Parameters on page 3 Testing REST Calls Using a Browser You can make calls to the REST API using a Web page or an application You also can specify an URL in a Web browser A Web browser displays the XML returned by the API If you have uploaded and specified an XSL file see Transforming Data Returned on page 20 a browser may display search results in HTML You can do a test call in the Sandbox environment using a browser Before you do so follow the instructions in Obtaining a REST Token for the Sandbox on page 8 You can make the test call using the following URL Substitute your Sandbox token and Sandbox user values for the UserToken and UserName values The token you use must correspond to the username you use http rest api sandbox ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserlId UserName amp Query toy 20boat amp Version 491 amp UnifiedInput 1 Data is returned as an XML document Find Items with GetSearchResults With GetSearchResults you can use keywords and many other criteria to retrieve items listed on eBay Rich functionality makes GetSearchResults a powerful call for retrieving items Also see the section Basic REST Input Parameters on page 3 for information about URLs used an
32. ics http developer ebay com DevZone XML docs WebHelp index htm context eBay_XML_API amp topic SearchingItemsWithQuery After you have tested your program s ability to handle output you can use your program in production to transform output or you can enable server side processing Server side processing uses your XSL files to format the output for you For more information on server side processing that uses your XSL files see Transforming Data Returned on page 20 Obtain Item Data with GetItem You can use GetItem to obtain detailed information about one item GetItem takes an item ID as input For example you could use an URL similar to the following to obtain detailed information about the item with the item ID of 123456789123 http rest api ebay com restapi CallName GetItem amp RequestToken UserToken amp RequestUserld UserName amp ltemID 1234567891 23 amp Version 491 Optionally you can specify other parameters such as a detail level to modify the data returned For example to use the DetailLevel parameter that is specifically for getting attribute information you could specify an URL similar to the following http rest api ebay com restapi CallName GetItem amp RequestToken UserToken amp RequestUserld UserName amp ltemID 1234567891 23 amp DetailLevel ItemReturnAttributes amp Version 491 Parameters for GetItem are the same in the REST API as in the unified schema except for the REST specific input parameter
33. ly return book specific information such as the author DVDs usually return movie specific information such as the leading role You can use the ProductReferenceID from a product retrieved in the above example as follows to retrieve product reviews and to retrieve items listed with the product http rest api ebay com restapi CallName GetProducts amp RequestToken UserToken amp RequestUserld UserName amp ProductSearch Pr oductReferenceID 44462740 amp IncludeItemArray true amp IncludeReviewDetails true amp Version 505 For samples of GetProducts that are used in the unified schema please see the following location http developer ebay com DevZone XML docs WebHelp index htm context eBay_XML_API amp topic GetProductsSamples Parameters for GetProducts are the same in the REST API as in the unified schema except for the REST specific input parameters For the REST specific input parameters see Basic REST Input Parameters on page 3 For more information about using GetProducts including descriptions of the call specific input and output parameters see the following document GetProducts General information about the unified schema format is available at the following location http developer ebay com support docs Version 3 7 Chapter 1 Using the REST API 17 Obtain Item Data with GetItem The following location contains additional information about using GetProducts in the unified schema as well as links to related top
34. m restapi CallName GetSearchResultsExpress amp RequestToken UserToken amp RequestUserld UserName amp Que ry garmin gps amp EntriesPerPage 3 amp Version 491 Version 3 7 Chapter 1 Using the REST API 2 Calls Available in the REST API Information in this Guide For information about obtaining a string for the Request Token parameter see Obtaining Tokens and Testing Calls on page 7 For parameters required with all REST calls see Required Parameters on page 4 For additional samples see the call sections of this guide such as Find Items with GetSearchResults on page 9 This guide contains the following sections Calls Available in the REST API on page 2 Basic REST Input Parameters on page 3 Obtaining Tokens and Testing Calls on page 7 Find Items with GetSearchResults on page 9 Find Items in a Category with GetCategory Listings on page 13 Find Items with GetSearchResultsExpress on page 14 Retrieve Product Information with GetProducts on page 15 Obtain Item Data with GetItem on page 17 Obtain Shipping Costs with GetltemShipping on page 18 Obtain a Category Hierarchy with GetCategories on page 18 Obtain Keywords with GetPopularKeywords on page 19 Transforming Data Returned on page 20 Legacy REST GetSearchResults Input on page 23 REST Information Sources on page 29 Calls Available in the REST API For the REST parameters applica
35. m support docs After you have tested your programs ability to handle output you can use your program in production to transform output or you can enable server side processing Server side processing uses your XSL files to format the output for you For more information on server side processing that uses your XSL files see Transforming Data Returned on page 20 Version 3 7 Chapter 1 Using the REST API 14 Find Items with GetSearchResultsExpress Find Items with GetSearchResultsExpress You can find items on eBay Express Express using the GetSearchResultsExpress call Specifically you can use GetSearchResultsExpress to do the following m Search for items on Express m Search for eBay catalog products on Express m Search and browse Express product types aisles and departments For example to use the Query parameter to search by keywords you can specify an URL similar to the following http rest api ebay com restapi CallName GetSearchResultsExpress amp RequestToken UserToken amp RequestUserld UserName amp Que ry plates amp EntriesPerPage 3 amp Version 491 For additional samples for this call see GetSearchResultsExpress Samples on page 14 GetSearchResultsExpress retrieves brief details about active items that are listed on eBay Express This call also retrieves eBay catalog products used to pre fill data in these items and a histogram that shows the distribution of items and catalog products across E
36. ma topic for the latest GetSearchResults output fields http developer ebay com DevZone XML docs Reference eBay io_GetSearchResults html Response Information about pagination is in the following section Paginating Search Results on page 13 After you have tested your program s ability to handle output you can use your program in production to transform output or you can enable server side processing Server side processing uses your XSL files to format the output for you For more information on server side processing that uses your XSL files see Transforming Data Returned on page 20 Version 3 7 Chapter 1 Using the REST API 13 Find Items in a Category with GetCategoryListings Paginating Search Results GetSearchResults returns items in pages to reduce the amount of data sent to clients in response to any one call For pagination you use the EntriesPerPage and PageNumber input parameters as in the example with these parameters at GetSearchResults Samples on page 10 EntriesPerPage is the maximum number of ItemType objects that should be returned in the SearchResultItemArray for any given call PageNumber is the number of the page of data to return in the current call default is 1 In the response ItemsPerPage indicates the number of items returned by the current call PaginationResult TotalNumberOfEntries indicates the total number of items matching the search criteria PaginationResult TotalNumberO
37. on 3 7 Chapter 1 Using the REST API 23 Legacy REST GetSearchResults Input Legacy REST GetSearchResults Input Formerly REST input parameters for GetSearchResults were similar to the legacy XML API input parameters for GetSearchResults Now all applications must be migrated from legacy input parameters to unified schema input parameters The unified schema is standardized and uses objects for data exchange This section of the REST API Guide may be applicable until you migrate all applications from legacy input parameters to unified schema input parameters This section contains the following subsections Legacy Samples for GetSearchResults on page 23 Legacy Affiliate Parameters for GetSearchResults on page 23 Legacy Input Parameters for GetSearchResults on page 24 Legacy Samples for GetSearchResults This section contains samples that use legacy GetSearchResults input parameters All applications must be migrated from legacy input parameters to unified schema input parameters Please see the following section of this guide for the unified schema GetSearchResults input parameters GetSearchResults Input Parameters on page 10 Also see the section Root URLs Containers and Repeating Parameters on page 3 This legacy input sample shows use of a Query parameter to search eBay The value of Query is toy boat with the space character HTTP encoded as 20 http rest api ebay com restapi CallName Get
38. ot present If the specified category ID does not match an existing category for the site an invalid category error message is returned Specifies the API version you are using for the call If data returned is different from expected test your call using a higher version such as 491 If 1 true limits the results to Giving Works listings and no other listings If 0 false has no effect on the search results i e the behavior is the same as not sending CharityListing at all Not applicable returns 0 items for eBay Motors international sites and Real Estate and Tickets listings Numeric ID for a currency type Limits the search to just those items listed using a specified currency Not applicable to eBay Motors searches Controls the amount of data returned Specifies the beginning of a time range for when items will end Specifies the end of a time range for when items will end Corresponds to a Site ID If specified returns any error messages in the language associated with the Site ID Excludes the specified sellers from the search Use a seller s User ID Separate multiple sellers with a comma A maximum of 100 sellers can be listed Cannot be used with IncludeSellers and PayPal parameters StoreSearch overrides ExcludeSellers Expands search results when a small set is returned Do not use the Query parameter with this parameter ExternalProductIdentifier only retrieves items that were listed with the specified I
39. pt in the section ea REST GetSearchResults Input on page 23 For information about using unified schema input parameters for GetSearchResults please see Find Items with GetSearchResults on page 9 The System Announcements page is the primary resource for checking the status of issues relating to the Sandbox and the Production servers Please check the System Announcements page before reporting urgent production system issues to eBay Typical issues we announce on this page are latency unavailability known errors and known call failures eBay Developers Program System Announcements Forum http developer ebay com forums General information about the unified schema on which the REST API is based is available at the following location http developer ebay com support docs To learn about the eBay Affiliate Program please see http affiliates ebay com If this link or other links in this guide do not function please close any open browser windows before using them For information about affiliate parameters in call requests see Affiliate Parameters on page 5 Introductory Samples This sample shows how to use a Query parameter to search eBay http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserId UserName amp Query toy 20boat amp Version 491 amp UnifiedInput 1 This sample shows how to use a Query parameter to search eBay Express http rest api ebay co
40. rameters to unified schema input parameters The unified schema is standardized and uses objects for data exchange Version 3 7 Chapter 1 Using the REST API 11 Find Items with GetSearchResults Please make use of the unified schema input format and begin migrating all applications from legacy input parameters to unified schema input parameters To use the unified schema input format include the UnifiedInput parameter and set it to 1 UnifiedInput 1 as in the examples in this guide Descriptions of the UnifiedInput parameter and the related Schema parameter are in the following sections The UnifiedInput and Schema Parameters for GetSearchResults on page 11 and Required Parameters on page 4 Input parameters for GetSearchResults are the same in the REST API as in the unified schema except for the REST specific input parameters For the REST specific input parameters see Basic REST Input Parameters on page 3 For more information about using GetSearchResults including descriptions of the call specific input and output parameters see the following unified schema document GetSearchResults General information about the unified schema format is available at the following location http developer ebay com support docs The following location contains additional information about using GetSearchResults in the unified schema as well as links to related topics http developer ebay com DevZone XML docs WebHelp inde
41. rs Please see the following section of this guide for the unified schema GetSearchResults input parameters GetSearchResults Input Parameters on page 10 Formerly REST input parameters for GetSearchResults were similar to the Legacy XML API input parameters for GetSearchResults Now you can specify unified schema parameters for GetSearchResults The unified schema is standardized and uses objects for data exchange Until you migrate all REST applications from legacy input parameters to unified schema input parameters this section of the REST API Guide may be applicable to GetSearchResults calls because this section contains information about legacy GetSearchResults input Version 3 7 Chapter 1 Using the REST API 25 Legacy REST GetSearchResults Input The following table describes major legacy input parameters for GetSearchResults in the REST API Table 1 5 Legacy GetSearchResults Input Parameters See GetSearchResults Input Parameters on page 10 Category CompatibilityLevel CharityListing Currency DetailLevel EndTimeFrom EndTimeTo ErrorLanguage ExcludeSellers ExpandSearch ExternalProductIden tifier Granularitylevel HighestPrice Y a zid z Z Integer String Boolean nteger nteger ime m ime nteger String Boolean Meta Tag String Money Numeric ID of the category to be searched Defaults to all categories if zero 0 is specified or the tag is n
42. s For the REST specific input parameters see Basic REST Input Parameters on page 3 For more information about using Getltem including descriptions of the call specific input and output parameters see the following document GetItem General information about the unified schema format is available at the following location http developer ebay com support docs After you have tested your program s ability to handle output you can use your program in production to transform output or you can enable server side processing Server side processing uses your XSL files to format the output for you For more information on server side processing that uses your XSL files see Transforming Data Returned on page 20 Version 3 7 Chapter 1 Using the REST API 18 Obtain Shipping Costs with GetItemShipping Obtain Shipping Costs with GetItemShipping You can use GetItemShipping to obtain estimated shipping cost information for an item To use GetltemShipping include the applicable item ID The data returned is similar to the data returned by the Shipping Calculator on the eBay site Note that the shipping insurance cost can only be determined after the final price of the item is determined For example using item ID 123456789123 you could specify destination information in an URL similar to the following for estimated shipping cost information http rest api ebay com restapi CallName GetItemShipping amp RequestToken UserToken
43. s Retrieve Product Information with GetProducts Obtain Item Data with GetItem Obtain Shipping Costs with GetItemShipping Obtain a Category Hierarchy with GetCategories Obtain Keywords with GetPopularKeywords Transforming Data Returned Uploading and Using XSL Files Viewing Renaming and Deleting XSL Files Legacy REST GetSearchResults Input Legacy Samples for GetSearchResults Legacy Affiliate Parameters for GetSearchResults Legacy Input Parameters for GetSearchResults Additional Resources REST Information Sources Contents OO WAANN UY BRWWNDN FE FE NNN NN NN FP RP RP RP RP RP PRP RPP eB RWWWrRFODUOAAN UA KRWNN OO N N O oO Version 3 7 Index eBay API Documentation Contents 29 Version 3 7 iv Chapter 1 Using the REST API 1 eh Introductory Samples Chapter 1 Using the REST API With the eBay REST API you can use an URL for simple or complex searches of millions of item listings Moreover you can use an URL to get detailed information about individual item listings Most calls to the REST API are from a Web page application or script You can use the REST API to integrate eBay functionality into your Web sites and applications For the calls available in the REST API please see Calls Available in the REST API on page 2 Note The REST API can receive unified schema input parameters for GetSearchResults The samples in this document have been eae to show the unified schema input parameters exce
44. s section contains the following subsections Root URLs on page 3 Containers on page 3 Repeating Parameters on page 4 Root URLs To make a call to the REST API in the production environment which contains live eBay data use the following root URL http rest api ebay com restapi Additionally if a call is supported in the Sandbox test environment you can make a test call to the following root URL http rest api sandbox ebay com restapi Here is an example of a GetSearchResults request that uses the REST API The value of Query is toy boat with the space character HTTP encoded as 20 http rest api ebay com restapi CallName GetSearchResults amp RequestToken UserToken amp RequestUserld UserName amp Query toy 20boat amp Version 491 amp UnifiedInput 1 The overall size of the string after the in the URL must be no larger than 2071 characters If you access the REST API through a proxy the proxy may place further size limitations on the URL Containers Input parameters in the REST API can contain other parameters and can have attributes Note In GetSearchResults if an input parameter is unique among all of the possible input parameters for the call then you do not need to specify the parameter container You can use XPATH to specify parameters that are containers or have attributes Nested Parameters Use the symbol i e Parent Child Attributes Use the
45. schema format is available at the following location http developer ebay com support docs Obtain Keywords with GetPopularKeywords Using GetPopularKeywords you can obtain a list of keywords that users have frequently specified when searching eBay The list is regularly updated Optionally you can specify a category ID for keywords relating to a specific category Please note that you cannot specify the CategoryID parameter more than once per call To use the CategoryID parameter to obtain frequently used keywords you could specify an URL similar to the following http rest api ebay com restapi CallName GetPopularKeywords amp RequestToken UserToken amp RequestUserld UserName amp Category ID 20081 amp Version 491 The following sample shows how to obtain frequently used keywords for a category and its subcategories http rest api ebay com restapi CallName GetPopularKeywords amp RequestToken UserToken amp RequestUserlId UserName amp Category ID 58058 amp IncludeChildCategories true amp Version 491 Parameters for GetPopularKeywords are the same in the REST API as in the unified schema except for the basic REST input parameters For the REST specific input parameters see Basic REST Input Parameters on page 3 For more information about using GetPopularKeywords including descriptions of the call specific input and output parameters see the following document GetPopularKeywords General information about the unified
46. schema format is available at the following location http developer ebay com support docs Version 3 7 Chapter 1 Using the REST API 20 Transforming Data Returned After you have tested your programs ability to handle output you can use your program in production to transform output or you can enable server side processing Server side processing uses your XSL files to format the output for you For more information on server side processing that uses your XSL files see Transforming Data Returned on page 20 Transforming Data Returned Using the XML to HTML Transform tool you can enable processing that transforms the XML returned by the REST API This server side processing is done using XSL files that you upload You access your uploaded XSL files using a link on the REST Developer Center page http developer ebay com developercenter rest on the eBay Developers Program site You can use your uploaded XSL files to efficiently transform data returned into formats that meet your needs and the needs of your users Server side transformation of data returned in the REST API can remove the need for you to manage formatting and other transformations of data returned thus providing you with enhanced flexibility and lower costs To enable server side processing of your uploaded XSL files you must have production keys and at least one production certified application For more information see Using the REST API in Production
47. table describes the required input parameters Table 1 1 Required REST Input Parameters CallName The name of the API call RequestToken The REST token of an eBay user This token corresponds to a specific eBay user See Obtaining a REST Token for the Sandbox for information on how to retrieve this value RequestUserld The user name of the eBay user whose REST token is specified in the RequestToken parameter The RequestUserld parameter is mandatory UnifiedInput The UnifiedInput parameter applies only to GetSearchResults For GetSearchResults if you include this parameter and set it to 1 it indicates you are using unified schema input For more information see Find Items with GetSearchResults on page 9 If you include the UnifiedInput parameter and set it to 1 you do not need to specify the Schema parameter If you do not include the UnifiedInput parameter and set it to 1 you must include the Schema parameter and set it to 1 Version 3 7 Chapter 1 Using the REST API 5 Basic REST Input Parameters Table 1 1 Required REST Input Parameters Version Specifies the API version you are using for the call If the data returned is different from expected test your call using a higher version such as the minimum of 475 for GetSearchResultsExpress The Version parameter replaces the CompatibilityLevel parameter the CompatibilityLevel parameter is deprecated If you do not use a Version parameter or for
48. tore items to return Using StoreSearch forces SearchInDescription true 0 Within a single store for all items use with StoreName 1 Within a single store for auction items use with StoreName 2 Within a single store for Buy It Now items use with StoreName 3 Across all stores for Buy It Now items Filter to return only the total quantity of matching items Count HasMoreltems PageNumber GrandTotal without returning the item data or buying guide data Version 3 7 sd Chapter 2 Additional Resources 29 eh REST Information Sources Chapter 2 Additional Resources In each REST call you provide the input parameters in the request URL the parameters are part of the HTTP request The response contains the requested data in XML format This contrasts with other Web service architectures such as those that use SOAP in which clients submit data to the service as an XML document Unlike other eBay APIs the REST API uses HTTP instead of HTTPS This is because unlike other eBay APIs the REST API is used to access only publicly accessible data REST Information Sources The following contain additional information on the REST architecture REST Discussion Mailing List http groups yahoo com group rest discuss Roy Thomas Fielding s PhD Dissertation http www1 ics uci edu fielding pubs dissertation top Building Web Services the REST Way http www xfront com REST Web Services html REST
49. tp rest api ebay com restapi CallName GetSearchResultsExpress amp RequestToken UserToken amp RequestUserId UserName amp Que ry tape amp TrackingPartnerCode MyTrackingPartnerCode amp AffiliateUserID MyAffiliateUserID amp TrackingID M yTrackingID amp Version 491 If you use affiliate parameters with GetSearchResults or GetSearchResultsExpress the REST API returns a modified version of the ViewItemURL string The modified version of the ViewItemURL string includes information for tracking user activity Affiliate Parameter Descriptions This section contains a table that describes the affiliate parameters Table 1 2 Parameters for Affiliate Tracking TrackingPartnerCode Integer Specifies the third party e g Commission Junction who is your tracking partner tracking provider Depending on your tracking partner specify one of the following values Not all partners are valid for all sites 1 Commission Junction 2 Be Free 3 Affilinet 4 TradeDoubler 5 Mediaplex 6 DoubleClick 7 Allyes 8 BJIMT Version 3 7 Chapter 1 Using the REST API Obtaining Tokens and Testing Calls 7 Table 1 2 Parameters for Affiliate Tracking TrackingID String Specifies an ID to identify you to your tracking partner tracking provider The value you specify is obtained from your tracking partner For example in the case of Commission Junction the TrackingID is the PID given to you by Commission Junction AffiliateUserID N
50. uction certified application A maximum of 20 XSL files can be associated with one production certified application Version 3 7 Chapter 1 Using the REST API 21 Transforming Data Returned The smaller the size of an XSL file the better will be its performance in transforming data returned The maximum size for an uploaded XSL file is 2 MB but a maximum size of 1 MB is recommended Step 1 Upload an XSL File 1 Enter your production Developer Id DevId in the XML to HTML Transform tool accessible from the REST Developer Center page http developer ebay com developercenter rest 2 If multiple applications are associated with your DevId the applications are displayed From the list of applications select an application with which to associate your XSL file and click Next If only one application is associated with your DevId the REST XSLT Home page is displayed 3 On the REST XSLT Home page the name of your application is displayed Click Upload New File 4 Onthe Upload A New File page specify a unique File Tag such as FormatInHTML1 and the file path of an XSL file and then click Upload After the upload completes the status of the upload including any associated error messages is displayed under the Upload button 5 Click Go Back to return to the REST XSLT Home page The File Tag of the file you uploaded is listed in the File Tag column of the table that displays information about your XSL files Step 2 Use an XSL File
51. x htm context eBay_XML_API amp topic SearchingItemsWithQuery The UnifiedInput and Schema Parameters for GetSearchResults For GetSearchResults to use unified schema input include the UnifiedInput parameter and set it to 1 All applications must be migrated from legacy input parameters to unified schema input parameters If you do not include the UnifiedInput parameter and set it to 1 you must include the Schema parameter and set it to 1 The Schema parameter has the following characteristics m Schema applies only to GetSearchResults m Schema sets the output format to the unified schema format m If the UnifiedInput parameter is omitted or set to 0 and Schema is omitted or set to 0 output is in the Legacy XML API format unsupported as of June 1 2006 If you specify UnifiedInput 1 in your input then the Schema parameter is unnecessary the output format automatically will be in the unified schema format Version 3 7 GetSearchResults Query Modifiers You can use the following modifiers in a GetSearchResults query Chapter 1 Using the REST API 12 Find Items with GetSearchResults Table 1 3 GetSearchResults Query Operators and Punctuation Space between words Comma between words no parentheses Comma between words in parentheses Quoted words word word word word sign URL encoded as 40 Applies AND logic to multiple keywords Applies AND logic to multiple keywords Applies OR
52. xpress departments aisles and or product types Parameters such as ItemDetails control the fields to retrieve GetSearchResultsExpress is not available in the Sandbox Parameters for GetSearchResultsExpress are the same in the REST API as in the unified schema except for the REST specific input parameters For the REST specific input parameters see Basic REST Input Parameters on page 3 For more information about using GetSearchResultsExpress including descriptions of the call specific input and output parameters see the following document GetSearchResultsExpress General information about the unified schema format is available at the following location http developer ebay com support docs The following location contains additional information about using GetSearchResultsExpress in the unified schema as well as links to related topics http developer ebay com DevZone XML docs WebHelp index htm context eBay_XML_API amp topic ExpressSearch After you have tested your program s ability to handle output you can use your program in production to transform output or you can enable server side processing Server side processing uses your XSL files to format the output for you For more information on server side processing that uses your XSL files see Transforming Data Returned on page 20 GetSearchResultsExpress Samples You can use the GetSearchResultsExpress call in many ways to obtain data from eBay Express V
Download Pdf Manuals
Related Search