XML API Guide: Including Pictures in an Item Listing

Pictures of an item can be used to make the item more appealing to prospective buyers and to give buyers a better idea of what the item looks like. Pictures are associated with an item by specifying the URLs for the pictures as part of the item definition at listing time.

Picture files may be stored on the eBay site (using eBay Picture Services or Picture Manager) or on a site of the seller's choice. If the pictures are stored on eBay, then generally one to twelve pictures may be used for the item. You cannot directly upload pictures with the API. However, the eBay SDK for Java and the eBay SDK for .NET offer a Picture Service library for this purpose, as described in this Knowledge Base article about the eBay SDK for .NET:

For the US eBay Motors site (for all vehicle listings), and for the eBay Canada site for motors, the picture pack of a listing can contain up to 24 photos.

If the picture host is other than eBay Picture Services, then up to six images may be used.

eBay Picture Services offer a number of special effects that can optionally be used when displaying the images in an item's listing, such as super-sizing an image or displaying multiple pictures in a slide show.

Using eBay Picture Services and the optional special effects are fee-based. Pictures for an item may also be hosted at eBay Picture Services (EPS) without using the special effects feature. For more information on eBay Picture Services, see the eBay site help page at the URL below.

Associating Images with an Item

With compatibility levels 439 and higher, data for pictures is stored in the Item.PictureDetails element. The picture URL in PictureURL and GalleryURL is parsed to determine which pictures are hosted on the eBay site, and which pictures are hosted elsewhere. Different rules may apply for pictures that are not hosted on the eBay site. For previous compatibility levels, picture data is stored in the Item.SiteHostedPicture element for pictures stored on eBay, and the Item.VendorHostedPicture element when pictures are hosted at other than eBay Picture Services or Picture Manager.

The PictureDetails.PictureURL property holds a URL for one image. The PictureDetails.PhotoDisplay property indicates any eBay Picture Services special effects that the seller desires (see the schema documentation for PhotoDisplayCodeType for a list of its values).

If you set PictureDetails.GalleryType and no image is specified in PictureDetails.GalleryURL, the image specified in the first PictureURL field will be used for the gallery thumbnail in most cases (see Including Pictures in the Search Results Gallery for exceptions). The PictureDetails.GalleryType property specifies whether the item appears in the Gallery, is Gallery Plus, or is Gallery Featured (see the schema documentation for GalleryTypeCodeType for a list of its values).


Note: The Gallery Plus feature requires that the picture specified in PictureDetails.GalleryURL or PictureDetails.PictureURL be hosted through the eBay Picture Service (EPS). One EPS gallery image is included with the Gallery Plus fee.

When defining a new item, use the properties of Item.PictureDetails to specify the image data for the new item. The API does not intrinsically provide the ability to upload image files to EPS. The files used for the new item must have already been uploaded to EPS and only the URLs are specified in PictureURL or GalleryURL.

Using a Stock Photo in an Item Listing

eBay provides stock catalog information, including stock photos, for some commonly sold items (e.g., a black iPod Nano). To include a stock photo and other stock information (also called Pre-filled Item Information) in an item listing, you need to specify the catalog product ID in your listing request, and then specify additional fields to configure the catalog data you want to use. There are three main ways to find a catalog product ID:

If you are listing in media categories (Books, Music, Movies, or Video Games) or event ticket categories, you can use Item.ExternalProductID to specify an industry-standard value (e.g., an ISBN) or ticket keywords, and eBay will use that information to look for a matching product in the catalog for you.

If you are listing in other categories that support Pre-filled Item Information, you need to execute a series of calls to determine determine the correct catalog product ID to use.

If you know of an existing listing on the eBay Web site that was listed with the same Pre-filled Item Information that you want to use, pass the listing's item ID in GetItem with a detail level of ItemReturnAttributes or ReturnAll. This will retrieve the product ID that was used in the listing.

Once you have identified a catalog product, you can include the product's stock photo in your listing by setting Item.ProductListingDetails.IncludeStockPhotoURL to true. If a stock photo is available, it is used at the top of the View Item page and in the Item Specifics section of the listing.

If you also include Item.PictureDetails.PictureURL, the stock photo only appears in the Item Specifics section of the listing. Other pictures you specify appear in a separate section of the listing. If you set IncludeStockPhotoURL to false, the stock photo does not appear in the listing at all. In GetItem and related calls, the URL of the stock photo will be returned in StockPhotoURL.

Including Pictures in the Description and Using a Camera Icon

When a seller lists an item on the eBay site using the Sell Your Item (SYI) page and the item has the picture in the description, there is an option to indicate this when a buyer look at the listing on search and listings pages. This option is labeled "The description already includes a picture URL for my item" and is in the "Your own Web hosting" tab of the "Add pictures" section of the SYI page. When the entry for the item appears on a search page, a small camera icon appears in the row for the item—even if the item does not have a URL for an image in the Item.PictureDetails.PictureURL property for the item.

There is no specific AddItem input property in the API to enable this camera icon. But there is a workaround that allows an application to enable this option. This section describes what an application needs to do to enable the camera icon for item listings that only have an image in the item description.

The current design of AddItem uses logic that will only generate the camera icon if an application submits a valid image URL in the PictureDetails.PictureURL property. But if the only image for the item is embedded in the description, there would be no value for the PictureURL property. To enable the camera icon, the application needs to specify a specific clear-image URL for PictureDetails.PictureURL. The eBay site will detect this specific clear-image URL and display the camera icon when the item is displayed in a search page. The URL that must be passed in PictureDetails.PictureURL when AddItem is executed is:

Of course, the application does still need to specify a picture in the description. This is done by including an <img> HTML construct in the Item.Description property (that is, HTML to display an image embedded in the description), with the source being a URL to the image. For example:

<HTML><CENTER><B>eBay API Test Auction: Testing Picture URL icon work-around</B><BR><img src="http://pics.ebaystatic.com/aw/pics/homepage/v2/logo_171x102.gif"></CENTER> </HTML>

Retrieving Pictures with Item Data

With compatibility levels 439 and higher, data for pictures is stored in the Item.PictureDetails element. For previous compatibility levels, picture data is stored in the Item.SiteHostedPicture element for pictures stored on eBay, and the Item.VendorHostedPicture element when pictures are hosted at other than eBay Picture Services.

When item data is retrieved using such calls as GetSellerList and GetItem, the same data elements are used to convey the picture data as are used at listing time. The With compatibility levels 439 and higher, the Item.PictureDetails property will contain the picture data. For previous compatibility levels, the Item.SiteHostedPicture property will contain the picture data if the pictures are hosted on eBay Picture Services and the Item.VendorHostedPicture property will have the data if they are hosted on some other location. An application will check the Item.PictureDetails property to determine whether it has picture data. If this element returns a null value, then there are no pictures associated with the item.

If the data retrieved for an item listing does contain data for associated pictures, then the same child elements of Item.PictureDetails are used to get the data as are used to specify the data at listing time. (See Associating Images with an Item.)

Photo Fees

The value returned in the Fees object (returned by such calls as AddItem and RelistItem for newly listed or relisted items) for photos indicates the fee (if any) associated with the use of eBay Picture Services. This service allows you to have one to six photos of the item (more for eBay Motors items) accessible with the item's listing on eBay. The value represents the fees associated with the Photo Service feature that allows a seller to provide photos as a slide show or super-sized photos for the item.

For more information on eBay Picture Services, see the eBay site help page at the URL below.


Selling Items on eBay > Describing Items in a Listing > Including Pictures in an Item Listing
http://developer.ebay.com/DevZone/XML/docs/WebHelp/DescribingListing-Including_Pictures_in_an_Item_Listing.html
© 2004–2007 eBay Inc. All rights reserved.	Version 497