Selecting Fields to Retrieve

With many data retrieval calls that return multiple results (e.g., multiple items), you can reduce the volume of the response payload for a single API call by reducing the number of fields returned in each result.

A standard way to do this is to use a detail control or, for some calls, a granularity level. For example, a particular level might cause the response to include buyer-related data in every result, but no seller-related data. Specify a detail level using the DetailLevel property (or the equivalent outputSelector property) in the call request. Similarly, for the GetSellerList and GetBidderList, the GranularityLevel property of the call request can be used.

Topics:

Specifying Detail Levels and Granularity Levels

Working with the Output Selector

Best Practices for the Output Selector

Using a detail control (or granularity level) is just one way to reduce the size of the response payload for a single API call. For other ways, see Controlling the Amount of Data Returned.

Specifying Detail Levels and Granularity Levels

The schema includes a global list of detail levels that can be used for about 20 Trading API calls. The GetSellerList and GetBidderList calls support an alternative GranularityLevel property. GetSellerList is the only Trading API call that supports both. However, with this call, you can use either DetailLevel or GranularityLevel, but not both at the same time.

If DetailLevel or GranularityLevel applies to a call, the definitions of the levels are consistent across all request types (although the list of fields returned varies per call). For example, if DetailLevel or GranularityLevel applies to a call:

Additional detail level values are also available. See the detail level code list in the schema documentation for a list of the available detail levels.

The DetailLevel property is defined on the abstract type (AbstractRequestType). The GranularityLevel property is defined on a call's request type (e.g., GetSellerListRequestType) rather than on the abstract type.

Note that not all calls support detail levels to vary the output. Most calls only support certain detail levels or none:

If you pass a detail level that exists in the schema but that is not valid for a particular request, eBay ignores it and the request is processed normally. Note that you can specify multiple detail levels in a single request, but you can only specify one granularity level in a single request.

To determine whether a particular call supports detail levels and/or granularity levels (and if so, what the effects are), see the page for that call in the appropriate eBay Developers Program API Reference.

In the SOAP API, this example shows how to specify detail levels in a request. For an example in Java, see the GetSellerListCall.java file in the call folder of the eBay SDK for Java:

eBay SDK for Java

https://go.developer.ebay.com/developers/ebay/documentation-tools/sdks/java

Working with the Output Selector

You can use the OutputSelector field to select the data being retrieved by many "Get" calls in the Trading API, like GetItem, GetSellerEvents, or GetOrders.

The OutputSelector field can make the response of a Trading API call more manageable, especially when the standard call returns a large payload. If you use the OutputSelector field, the output data will include only the fields that you specified in the request.

An example of an application that could use an OutputSelector inclusive filter is a buying application that displays information to users that they need to buy an item. Using OutputSelector tags, the application would specify the following fields in a GetItem call: PictureURL, UserID, BuyItNowPrice, EndTime, and ViewItemURL.

By using OutputSelector filters, you select the fields you want returned in the response. If a field is returned, that field's parent and any child fields are also returned. An OutputSelector field cannot be used to specify a field attribute, e.g. currencyID.

Below is an XML snippet of how you would specify the OutputSelector fields in a GetItem call to return ViewItemURL (the URL where a user can view the listing) and BuyItNowPrice (the price that a potential buyer can purchase an auction item enabled with the Buy It Now feature):

Example: Restricting a GetItem Response to ViewItemURL and BuyItNowPrice
...
<ItemID>4046156497</ItemID>
<OutputSelector>Item.ListingDetails.ViewItemURL</OutputSelector>
<OutputSelector>Item.BuyItNowPrice</OutputSelector>
...

When you specify multiple fields, you can either use separate, repeating OutputSelector tags for each desired field, as above, or one OutputSelector tag with multiple field values delimited with a comma, as below.

Example: Restricting a GetItem Response Using a Comma-Separator
...
<ItemID>4046156497</ItemID>
<OutputSelector>Item.ListingDetails.ViewItemURL,Item.BuyItNowPrice</OutputSelector>
...

Note that unspecified fields are not returned. For example, even if PaginationResult normally would always be in the response, the use of one or more OutputSelector fields will prevent it from being returned, unless PaginationResult is among the fields specified with the OutputSelector field. For more information, see the following Knowledge Base article:

https://ebaydts.com/eBayKBDetails?KBid=1220

You do not have to specify the full path of the field unless the field you are specifying can be returned in multiple containers. If the field you are specifying can be returned in multiple containers, e.g. StartTime in GetItem, then specify the full path, as in the following example:

Example: Using the Full Path to Specify Item.ListingDetails.StartTime in GetItem
...
<ItemID>4046156497</ItemID>
<OutputSelector>Item.ListingDetails.StartTime</OutputSelector>
...

If you decide to specify the full path, do not specify the call request type (e.g., do not specify GetItemRequestType in the OutputSelector field).

If you enter a typo in the field name, an error message is returned, but if you enter an unavailable field, an error message is not returned.

An output selector cannot filter out standard fields from a response, e.g. Timestamp, Ack, Version, and Build. Additionally, an output selector cannot specify that only one attribute set or attribute be returned.

The OutputSelector field is not available for use with the REST API.

The OutputSelector field is supported for most calls that retrieve data. If the OutputSelector field is supported for a call, the OutputSelector field is listed as an input field for the call.

Best Practices for the Output Selector

In API calls, some fields are only returned if a specific detail level or specific "include" element (such as IncludeItemSpecifics in GetItem) is used. If you use an OutputSelector field but do not, for example, use a necessary detail level, then the field specified in your output sector will not be returned. See Specifying Detail Levels and Granularity Levels.

Thus, the OutputSelector field cannot work for a field that would not otherwise be in the response. It is recommended that you make a test call without an OutputSelector, confirm that the desired field is in the response, and then make the call again using an OutputSelector for your desired field.

Note that if you use an OutputSelector tag for a field that occurs multiple times in a response, the field is returned for each instance it would have been returned if an OutputSelector field had not been specified.

Copyright © 2005–2016 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.