Summary of the content on the page No. 1
Web Services
REST API Guide
Version 3.7
Summary of the content on the page No. 2
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 re
Summary of the content on the page No. 3
Contents iii Contents Chapter Chapter 1: 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 3 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 with GetSearc
Summary of the content on the page No. 4
Contents iv eBay API Documentation 29 Index 30 Version 3.7
Summary of the content on the page No. 5
Chapter 1: Using the REST API 1 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. For the calls available in the REST API, pl
Summary of the content on the page No. 6
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 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). This guide contains the following sections: “Calls Available in the REST API” on p
Summary of the content on the page No. 7
Chapter 1: Using the REST API 3 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
Summary of the content on the page No. 8
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&RequestToken=UserT
Summary of the content on the page No. 9
Chapter 1: Using the REST API 5 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. If you do not use a Version parameter (or, for Ge
Summary of the content on the page No. 10
Chapter 1: Using the REST API 6 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.com/ restapi?CallName=GetSearchResul
Summary of the content on the page No. 11
Chapter 1: Using the REST API 7 Obtaining Tokens and Testing Calls Table 1-2 Parameters for Affiliate Tracking Parameter Required? Data Type Purpose TrackingID 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, the TrackingID is the PID given to you by Commission Junction. AffiliateUserID N String Optional value that depends on your tracking par
Summary of the content on the page No. 12
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: 1 Join eBay by registering for an eBay User ID. 2 Join the eBay Developers Program. Information on joining is availabl
Summary of the content on the page No. 13
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, accessible from the following location: http://developer.ebay.com/support/docs/ 5 To begin making REST calls in production, see
Summary of the content on the page No. 14
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&RequestToken=UserToken&RequestUserId=UserName&CategoryID =617&Query=star+trek&Version=491&UnifiedInput=1 The keywords can include wildcards. The response
Summary of the content on the page No. 15
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 Sche
Summary of the content on the page No. 16
Chapter 1: Using the REST API 12 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 Applies AND logic baseball%20card Items with both the words words to multiple "baseball" and "card". keywords. Comma between Applies AND logic baseball,card Items with both the words words, no to multipl
Summary of the content on the page No. 17
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 fo
Summary of the content on the page No. 18
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: Search for items on Express Search for eBay catalog products on Express Search and browse Express product types, aisles, and departments For example, to use the Query parameter to search by keywords, you can specify an UR
Summary of the content on the page No. 19
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&topic=ExpressSearch The fo
Summary of the content on the page No. 20
Chapter 1: Using the REST API 16 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 memb
