eBay Landscape Lighting 3.7 User Manual
Web Services
REST API Guide
Version 3.7
Copyright Notice
Copyright Notice ii
© 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.
Contents iii
Contents
Chapter 1: Using the REST API 1
Chapter
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 GetSearchResults 9
GetSearchResults Samples 10
GetSearchResults Input Parameters 10
GetSearchResults Query Modifiers 12
GetSearchResults Output Fields 12
Find Items in a Category with GetCategoryListings 13
Find Items with GetSearchResultsExpress 14
GetSearchResultsExpress Samples 14
Retrieve Product Information with GetProducts 15
Obtain Item Data with GetItem 17
Obtain Shipping Costs with GetItemShipping 18
Obtain a Category Hierarchy with GetCategories 18
Obtain Keywords with GetPopularKeywords 19
Transforming Data Returned 20
Uploading and Using XSL Files 20
Viewing, Renaming, and Deleting XSL Files 21
Legacy REST GetSearchResults Input 23
Legacy Samples for GetSearchResults 23
Legacy Affiliate Parameters for GetSearchResults 23
Legacy Input Parameters for GetSearchResults 24
Chapter 2: Additional Resources 29
REST Information Sources 29
Ver si on 3.7
Contents iv
eBay API Documentation 29
Index 30
Ver si on 3.7
Chapter 1
Chapter 1: Using the REST API 1
Introductory Samples
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 updated to show the unified schema input parameters (except in the section “Legacy 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:
Chapter 1
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&RequestToken=UserToken&RequestUserId=UserName&Query=toy
%20boat&Version=491&UnifiedInput=1
This sample shows how to use a Query parameter to search eBay Express:
http://rest.api.ebay.com/
restapi?CallName=GetSearchResultsExpress&RequestToken=UserToken&RequestUserId=UserName&Que
ry=garmin+gps&EntriesPerPage=3&Version=491
Ver si on 3.7
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 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 GetCategoryListings” 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 GetItemShipping” 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
Chapter 1: Using the REST API 2
Calls Available in the REST API
Calls Available in the REST API
For the REST parameters applicable 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 GetItemShipping” 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.
Ver si on 3.7
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 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:
Chapter 1: Using the REST API 3
Basic REST Input Parameters
Additionally, if a call is supported in the Sandbox (test) environment, you can make a test call to the
following root URL:
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:
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
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).
http://rest.api.ebay.com/restapi
http://rest.api.sandbox.ebay.com/restapi
http://rest.api.ebay.com/restapi?CallName=GetSearchResults&RequestToken
=UserToken&RequestUserId=UserName&Query=toy%20boat&Version=491&UnifiedInput=1
: In GetSearchResults, if an input parameter is unique among all of the possible input parameters for the call, then you
Attributes. Use the “@” symbol (i.e., Element@attribute).
Ver si on 3.7
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=UserToken&RequestUserId=UserName&Query=slipp
ers&SearchFlags(1)=SearchInDescription&SearchFlags(2)=NowAndNew&Version=491&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
Chapter 1: Using the REST API 4
Basic REST Input Parameters
For specifying a site other than the US site (which is site 0) in your call, include a SiteId 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 table describes the required input parameters.
Table 1-1 Required REST Input Parameters
Parameter Description
CallName The name of the API call.
RequestToken The REST token of an eBay user. This token corresponds to
RequestUserId The user name of the eBay user whose REST token is
UnifiedInput The UnifiedInput parameter applies only to
a specific eBay user. See “Obtaining a REST Token for the
Sandbox
specified in the RequestToken parameter. The
RequestUserId parameter is mandatory.
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.
” for information on how to retrieve this value.
Ver si on 3.7
Chapter 1: Using the REST API 5
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
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 GetSearchResults, 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.
Basic REST Input Parameters
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/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
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.
Ver si on 3.7
http://affiliates.ebay.com. For
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=GetSearchResults&RequestToken=UserToken&RequestUserId=UserName&Query=tape
&TrackingPartnerCode=MyTrackingPartnerCode&AffiliateUserID=MyAffiliateUserID&TrackingID=MyTrackin
gID&Version=491&UnifiedInput=1
This sample shows how to specify affiliate parameters for GetSearchResultsExpress:
http://rest.api.ebay.com/
restapi?CallName=GetSearchResultsExpress&RequestToken=UserToken&RequestUserId=UserName&Que
ry=tape&TrackingPartnerCode=MyTrackingPartnerCode&AffiliateUserID=MyAffiliateUserID&TrackingID=M
yTrackingID&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
Parameter Required? Data Type Purpose
TrackingPartnerCode N 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
Ver si on 3.7
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
AffiliateUserID N String Optional value that depends on your tracking partner (tracking
Specifying International Sites
To specify a site other than the US site (which is site 0) in your call, include a SiteId parameter for the
site and, for GetSearchResults, the
parameter. The
SiteId parameter is case sensitive.
For example, to search for items listed on the Germany site, you could specify the following:
SearchLocationFilter.SearchLocation.SiteLocation.SiteID
Chapter 1: Using the REST API 7
Obtaining Tokens and Testing Calls
(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.
provider).
For example, if you specify a TrackingPartnerCode of 1 for
Commission Junction, the AffiliateUserID is your
Commission Junction Shopper ID (SID).
http://rest.api.ebay.com/
restapi?CallName=GetSearchResults&RequestToken=UserToken&RequestUserId=UserName&Query=toy
%20boat&Version=491&UnifiedInput=1&SiteId=77&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
http://developer.ebay.com/DevZone/XML/docs/WebHelp/
index.htm?context=eBay_XML_API&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
SiteId parameter:
Ver si on 3.7
Loading...