eBay Half Finding API
|
This document explains how to make a Half Finding API call. It provides an overview of the formats and parameters you can use with the Finding API.
This document provides information on the following topics:
The Half Finding API provides search functions that is complementary to the function provided by FindHalfProducts in the Shopping API, which searches the Half.com stock catalog for information about specific products, such as a particular CD or a particular book. FindHalfProducts returns product IDs and a few items associated with that particular product. You can use the product ID from that call as input to the findHalfItems call. (The findHalfItems call returns many items per product, up to the current maximum of 1500 items per product.)
However, use of the findHalfProducts call is not strictly required in order to use findHalfItems, as there are scenarios where the user knows the ISBN number or the UPC (universal product code) and directly supplies either of these as the productID to the findHalfItems request.
The Half Finding service supports a couple of request and response formats:
The HTTP GET call method passes values in the URL using name-value (NV) pairs.
Here's an example of a URL-style name-value pair request (wrapped for readability):
https://svcs.ebay.com/services/half/HalfFindingService/v1?OPERATION-NAME=findHalfItems &X-EBAY-SOA-SERVICE-NAME=HalfFindingService &SERVICE-VERSION=1.0.0 &GLOBAL-ID=EBAY-US &X-EBAY-SOA-SECURITY-APPNAME=YourAppID &RESPONSE-DATA-FORMAT=XML &REST-PAYLOAD &productID=9780065023572 &productID.@type=ISBN
The call response for Http GET is in XML format only.
The HTTP POST call method also supports the use of SOAP format requests. SOAP versions 1.1 and 1.2 are both supported.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://www.ebay.com/marketplace/half/v1/services"> <soap:Header/> <soap:Body> <ser:findHalfItemsRequest> <ser:productID type="Reference">30549257</ser:productID> <ser:paginationInput> <ser:pageNumber>4</ser:pageNumber> <ser:entriesPerPage>20</ser:entriesPerPage> </ser:paginationInput> </ser:findHalfItemsRequest> </soap:Body> </soap:Envelope>
The call response for SOAP requests is in SOAP format only.
The following are the headers required by this call:
| URL Parameter | Header Value | Required? | Description |
|---|---|---|---|
| OPERATION-NAME | X-EBAY-SOA-OPERATION-NAME | Yes | The operation name, for example findHalfItems. |
| N/A | X-EBAY-SOA-MESSAGE-PROTOCOL | Conditionally | If you make a SOAP request, you must use this header to specify the protocol you are using. Allowable values are "SOAP12" for SOAP Version 1.2 and SOAP11 for SOAP Version 1.1. |
| X-EBAY-SOA-SECURITY-APPNAME | X-EBAY-SOA-SECURITY-APPNAME | Yes | This is the application ID (AppID) for the service consumer. You obtain an AppID by joining the eBay Developers Program. |
| X-EBAY-SOA-SERVICE-NAME | X-EBAY-SOA-SERVICE-NAME | No | The name of the eBay API you are using. Specify "HalfFindingService". |
| GLOBAL-ID | X-EBAY-SOA-GLOBAL-ID | No | The unique identifier for a combination of site, language, and territory. For example, EBAY-US (the default) is the global ID that corresponds to the eBay US site. The global ID you specify must correspond to an eBay site with a valid site ID. Refer to eBay Site ID to Global ID Mapping. In addition, Global ID Values contains a complete list of the eBay global IDs. |
| MESSAGE-ENCODING | X-EBAY-SOA-MESSAGE-ENCODING | Conditionally | Specifies the message encoding (e.g., ISO-8859-1). The default encoding is UTF-8. When submitting requests in any format other than UTF-8, you must specify the message encoding. |
| RESPONSE-DATA-FORMAT | X-EBAY-SOA-RESPONSE-DATA-FORMAT | No | If you use a URL (HTTP GET) request, use this parameter to specify the output format as XML or NV (name value pairs). URL requests do not support SOAP responses. If you use a URL, and you do not specify RESPONSE-DATA-FORMAT, the output format will be XML. If you use the HTTP POST method, the output data (response data) will be in the same format as the input data. |
| REST-PAYLOAD | N/A | No | If you use a URL, use this parameter to separate the payload part of the URL from the standard headers. Requires no value; anything appearing after this header will be considered part of the call payload. This parameter is ignored in HTTP POST requests. |
| SERVICE-VERSION | X-EBAY-SOA-SERVICE-VERSION | No | The API version your application supports (e.g., 1.0.0). |
Currently, Half Finding API requests may be sent only to the eBay Production API Gateway URI (endpoint), not to the eBay Sandbox. You specify the endpoint in the request.
https://svcs.ebay.com/services/half/HalfFindingService/v1
Note: The service endpoint contains the major version for the service (e.g., v1). When updating to subsequent major releases, you must update the version in the service endpoint, as well. |
Each Half Finding API call consists of the following elements:
X-EBAY-SOA-SECURITY-APPNAME header or X-EBAY-SOA-SECURITY-APPNAME URL parameter. Similarly, you must always specify the call name in the X-EBAY-SOA-OPERATION-NAME header or OPERATION-NAME URL parameter. Other headers are optional or conditionally required.If you are using a URL (and the HTTP GET method), input must be in the NV (Name-Value Pair)
format. Use the RESPONSE-DATA-FORMAT header to specify that data is returned in one
of the following formats: NV or XML. The following example (wrapped for readability) shows
standard Finding API parameters. RESPONSE-DATA-FORMAT specifies XML
for XML output.
https://svcs.ebay.com/services/half/HalfFindingService/v1?OPERATION-NAME=findHalfItems &X-EBAY-SOA-SERVICE-NAME=HalfFindingService &SERVICE-VERSION=1.0.0 &GLOBAL-ID=EBAY-US &X-EBAY-SOA-SECURITY-APPNAME=YourAppID &RESPONSE-DATA-FORMAT=XML &REST-PAYLOAD &productID=9780065023572 &productID.@type=ISBN
The following example shows standard Half Finding API headers for an HTTP POST call. In the
example, the X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12 header specifyies that you are using
SOAP Version 1.2.
X-EBAY-SOA-SERVICE-NAME: HalfFindingService X-EBAY-SOA-OPERATION-NAME: findHalfItems X-EBAY-SOA-SERVICE-VERSION: 1.0.0 X-EBAY-SOA-GLOBAL-ID: EBAY-US X-EBAY-SOA-SECURITY-APPNAME: MyAppID X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12
This section spells out the syntax requirements for the supported request and response formats. In most cases, the syntax for the various formats is standard and only the rules that aren't standard or are potentially tricky are explained.
Name-value requests/responses follows the syntax rules for the query string part of a URI. The query string is the portion of the URI that follows the endpoint. The query string is separated from the endpint by a question mark ("?"). The query string consists of a series of name-value pairs separated by ampersands ("&"). The name always precedes the value and they are separated by an equals sign ("=").
The following sections outline syntax rules specific to the name-value request/response format.
Attributes require a special syntax when used in name-value requests. The findHalfItems call requires the use of an attribute to specify the product ID (e.g., <productId type=ISBN>1234567890</productId>). In URL/NV requests (and responses) are attributes preceded by an at sign ("@"). For example, the product ID would be specified as in the following example:
...&productId.@type=ISBN&productId=1234567890...
The SOAP request/response format follows standard SOAP syntax conventions. Please see SOAP Syntax on w3schools.com for more information.
You can use the Production environment (with the
https://svcs.ebay.com/services/half/HalfFindingService/v1 endpoint) to test calls to the Finding API.
Although the Production environment has live data, Half Finding Service calls do not alter item data or user data.
You can download the latest version of the WSDL for the Finding API with the following link:
http://developer.ebay.com/webservices/half-finding/latest/HalfFindingService.wsdl
Alternatively, you can access a particular version of the Finding schema using a URL with the following format (where VERSION is the version identifier of the release):
http://developer.ebay.com/webservices/half-finding/VERSION/HalfFindingService.wsdl
The version identifier is the version number of a particular schema (a release number).
For example, you can access version 1.0.0 of the WSDL version of the schema at the following URL:
http://developer.ebay.com/webservices/half-finding/1.0.0/HalfFindingService.wsdl
Share tips or code samples related to this call or topic. Questions or observations are welcome, too.
eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.
© 2009–2011 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.