Web Services REST API Guide Version 3.
Copyright Notice 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.
Contents Contents Chapter 1: Chapter Using the REST API 1 Introductory Samples 1 Information in this Guide 2 Calls Available in the REST API 2 Basic REST Input Parameters 3 Root URLs, Containers, and Repeating Parameters Required Parameters 4 Error Information 5 Affiliate Parameters 5 Specifying International Sites 7 Obtaining Tokens and Testing Calls 7 Obtaining a REST Token for the Sandbox 8 Using the REST API in Production 8 Testing REST Calls Using a Browser 9 Find Items wit
Contents Index eBay API Documentation 29 30 Version 3.
Chapter 1: Using the REST API Introductory Samples Chapter 1 Using the REST API Chapter 1 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.
Chapter 1: Using the REST API Calls Available in the REST API Information in this Guide For information about obtaining a string for the RequestToken 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).
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 This section contains the following subsections: “Root URLs” on page 3 “Containers” on page 3 “Repeating Pa
Chapter 1: Using the REST API 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.
Chapter 1: Using the REST API Basic REST Input Parameters Table 1-1 Required REST Input Parameters Parameter Description 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.
Chapter 1: Using the REST API Basic REST Input Parameters In the REST API, affiliate parameters can be used with the following calls: GetSearchResults (see “Find Items with GetSearchResults” on page 9) GetSearchResultsExpress (see “Find Items with GetSearchResultsExpress” on page 14) GetProducts (see “Retrieve Product Information with GetProducts” on page 15) This sample shows how to specify affiliate parameters in GetSearchResults: http://rest.api.ebay.
Chapter 1: Using the REST API Obtaining Tokens and Testing Calls Table 1-2 Parameters for Affiliate Tracking Parameter TrackingID Required? N Data Type Purpose 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.
Chapter 1: Using the REST API 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: 1 Join eBay by registering for an eBay User ID. 2 Join the eBay Developers Program.
Chapter 1: Using the REST API 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, accessible from the following location: http://developer.ebay.
Chapter 1: Using the REST API 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&RequestToken=UserToken&RequestUserId=UserName&CategoryID =617&Query=star+trek&Version=491&UnifiedInput=1 The keywords can include wildcards. The response is an array.
Chapter 1: Using the REST API 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.
Chapter 1: Using the REST API Find Items with GetSearchResults GetSearchResults Query Modifiers You can use the following modifiers in a GetSearchResults query: Table 1-3 GetSearchResults Query Operators and Punctuation Modifier Purpose Example of Usage in REST API Returns Space between words Applies AND logic to multiple keywords. baseball%20card Items with both the words "baseball" and "card". Comma between words, no parentheses Applies AND logic to multiple keywords.
Chapter 1: Using the REST API 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.
Chapter 1: Using the REST API Find Items with GetSearchResultsExpress Find Items with GetSearchResultsExpress You can find items on eBay Express (“Express”) using the GetSearchResultsExpress call.
Chapter 1: Using the REST API 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.
Chapter 1: Using the REST API Retrieve Product Information with GetProducts GetProducts includes input parameters for retrieving the following types of product information: Stock catalog information about a particular DVD, digital camera, or a variety of other products Product titles, stock photos, and Item Specifics URLs to help you create links to additional catalog content on eBay Up to 200 active items that were listed with a product Up to 20 of the top reviews written by eBay member
Chapter 1: Using the REST API Obtain Item Data with GetItem The following location contains additional information about using GetProducts 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&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.
Chapter 1: Using the REST API 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 GetItemShipping, 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.
Chapter 1: Using the REST API 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.
Chapter 1: Using the REST API Transforming Data Returned 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.
Chapter 1: Using the REST API 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).
Chapter 1: Using the REST API Transforming Data Returned View an XSL File To view 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). 2 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.
Chapter 1: Using the REST API 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.
Chapter 1: Using the REST API Legacy REST GetSearchResults Input &TrackingProvider=MyTrackingProvider&TrackingId=MyTrackingId&CJSID=MyCJSID&Schema=1&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: “GetSearchResults Input Parameters” on page 10. The following table describes the legacy GetSearchResults affiliate parameters.
Chapter 1: Using the REST API 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) Parameter Required? Category Y/N Data Type Purpose Integer Numeric ID of the category to be searched. Defaults to all categories if zero (0) is specified or the tag is not present.
Chapter 1: Using the REST API Legacy REST GetSearchResults Input Table 1-5 Legacy GetSearchResults Input Parameters (See “GetSearchResults Input Parameters” on page 10) Parameter IncludeCondition Required? N Data Type Purpose Boolean 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.
Chapter 1: Using the REST API Legacy REST GetSearchResults Input Table 1-5 Legacy GetSearchResults Input Parameters (See “GetSearchResults Input Parameters” on page 10) Parameter Required? Data Type Purpose MotorsGermanySearch able N Boolean Filter that limits the response according to whether the item is eligible to be listed in search results on the mobile.de site. NowAndNew N Boolean Filter that limits the response to items listed with Now & New.
Chapter 1: Using the REST API Legacy REST GetSearchResults Input Table 1-5 Legacy GetSearchResults Input Parameters (See “GetSearchResults Input Parameters” on page 10) Parameter Required? Data Type Purpose SearchInDescription N Boolean If true (1), specifies to search in item titles, subtitles, and descriptions for the string specified in Query.
Chapter 2: Additional Resources REST Information Sources Chapter 2 Additional Resources Chapter 2 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).
Index Index E 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 in a 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 get a 8 S Sandbox REST API support 8 search query modifiers 12 search results paginating 13 T tracking enabli
Index Version 3.
