The Product Finder Meta-Data Model

Before reading this section, you should be familiar with the basic definitions of attributes, characteristics, and products as described in Working with Attribute-Based Features.

When you use GetProductFinderCall, the product finder meta-data is returned as an XML string in the ProductFinderData field. This enables you to use the Product Finder XSL stylesheet to render the meta-data.

If you are using the Product Finder XSL stylesheet as part of your solution, it may be helpful to focus on these topics of this section:

ProductFinder Elements

AttributeList.Attribute Elements

SortAttributes Elements

If you are not using the Product Finder XSL stylesheet, it may be useful to examine the PresentationInstruction Elements for hints on how to render the attributes.

Important: eBay strongly recommends that you avoid directly modifying the XML returned from GetProductFinderCall, except where described in Working with the Product Finder XSL Stylesheet. Any other direct changes to the XML document returned from this call are not supported.

ProductFinder Elements

The ProductFinderData XML string contains an eBay.ProductFinders node that in turn contains zero or more ProductFinder nodes. Table 23-10 describes the nodes that are returned in a ProductFinder node.

Elements in the Product Finder model can specify XML attributes (not to be confused with item attributes). In the table below, the XML attributes (e.g., id) are described in bulleted lists within the "Meaning/Notes" column.

Table 23-10 ProductFinder Content

Element	Data Type	Meaning/Notes
ProductFinder	Container	Contains a list of search criteria and other identifying information associated with a product finder. Multiple ProductFinder elements can be returned. id (integer): Numeric identifier for the product finder ID. Unique across all sites. Mode (string): Indicates the mode in which you can search. Possible values: Advance = You can input values to perform the search Simple = Selecting a link performs the search BuySide (boolean): Possible values: 1 (true) = The product finder can be used as input to GetSearchResults to search for listings with Item Specifics on the eBay site. 0 (false) or not present = The product finder can be used as input to GetProductSearchResults to search for catalog data (Pre-filled Item Information) that a seller might want to include in a listing.
...AttributeList	Container	Contains the list of attributes that define the choice of search criteria within a characteristic set. At least one attribute is always returned in the list. The order in which Attribute nodes are returned within this node is not significant and may vary for different requests. See AttributeList.Attribute Elements for details about the format of these attributes.
...PresentationInstruction	Container	Contains hints about how to display a product finder in a graphical user interface. The instructions are identified in child elements (see PresentationInstruction Elements). Future versions of the presentation instructions may not be backward compatible. They are included in the API primarily for use with eBay's Product Finder XSL stylesheet to render a product finder. If you are not using the Product Finder XSL and you choose to use the presentation instructions, avoid hard-coding the values in your application because the rules can be subject to change. Check for updates to the meta-data on a daily basis to assure you are in sync with eBay's current version. It is also a good idea to keep a backup of the last version of the meta-data that you downloaded, so that you can revert to the last version if necessary. Note: Different product finders can return different combinations of presentation instructions, including XML attributes. Some presentation instruction elements may include additional XML attributes that are not documented. These are usually specific to one particular product finder and are used internally at eBay. Applications can ignore this internal information.
..SortAttributes	Container	Contains a list of attributes that can be used as keys for sorting catalog search results. See SortAttributes Elements for details about the format of these attributes.
...Title	String	The canonical name of the product finder (e.g., "Digital Cameras").

AttributeList.Attribute Elements

The AttributeList element contains the list of attributes that define the choice of search criteria within a characteristic set. At least one attribute is always returned in the list.

Table 23-11 describes the elements contained in the AttributeList.Attribute node in the Product Finder XML.

Table 23-11 AttributeList.Attribute Content

Element	Data Type	Meaning/Notes
Attribute	Container	Contains the meta-data and values associated with a single searchable attribute. A searchable attribute is a product aspect or feature that can be used as a criterion in a search for catalog content or Item Specifics. For example, "Manufacturer"" might be a criterion for searching a catalog for Pre-filled Item Information related to cell phones. Multiple Attribute nodes can appear within an AttributeList node. id (integer): Unique identifier for the attribute within the characteristics set associated with this product finder. parentAttrId (integer): Unique identifier for this attribute's parent attribute. Applicable for child attributes in Type 1 (VVC) and Type 2 (VVP) dependencies only. See Characteristic Parent-Child Relationships (Dependencies).
Attribute.InputFields	Container	A container for input fields that are used to render a given attribute. The XSL uses InputFields in combination with PresentationInstruction to draw the input form variables.
...InputFields.Input	Container	Used by the Product Finder XSL. Indicates the nature of the data being rendered. For example, allows for separate fields to be rendered for a single attribute (while the presentation instructions control how the widgets appear.) Also contains the value to use as the default value (if any). dataType (string): Specifies the subcomponent of a date. This only applies to date attributes. Allows for separate text fields or drop-down lists to be rendered for each date subcomponent. Possible values: M = Month D = Day Y = Year id (integer): Unique identifier for the default attribute within the characteristics set associated with this product finder. name (string): In most cases, you should not directly access this data from your application. For text-entry fields, the name XML attribute has a "t" prefix. For all other attributes, the name XML attribute has an "a" prefix. See Parsing the POST Data for additional information. rangeType (string): Indicates that the input field represents the high or low end in a range (e.g., a price range). Allows for separate text fields to be rendered for each subcomponent of the range. Possible values: L = Low end of the range H = High end of the range
...InputFields.Input.Value	Container	Contains the default value to show in the form. (See ValueList for all possible values). id (integer): The ID associated with the input field value. This can match any of the ValueList.Value.id values for the given attribute. If Input.Value is not specified and the Input.name XML attribute (and/or presentation instruction) indicates that this is a text-entry field, you should assume the value ID is -3 when this attribute is used as input to GetProductSearchResults or GetSearchResults. For all other values, the value ID is indicated in Value.id.
...InputFields.Input.Value.Name	String	The human-readable name to display in the input field.
Attribute.Label	String	The human-readable label to display when presenting the attribute to a user. Not necessarily the same as the attribute's label as defined in the characteristic set (i.e., the label could be overridden by the catalog).
Attribute.ValueList	Container	Contains a list of one or more valid values that the user can select for the searchable attribute. count (integer): The quantity of Value nodes within the ValueList.
...ValueList.Value	Container	A value that the user can search against. id (integer): Identifier for the value. Possible ID values: -3 = User can enter an arbitrary value -24 = Any or "-" (initial dash to present as a default) -100 = Value not specified (null) ID = Identifier for a pre-defined value. Unique within the characteristics set (e.g., 10256) If ValueList.Value is not specified and the Input.name XML attribute (and/or presentation instruction) indicates that this is a text-entry field, you should assume the value ID is -3 when this attribute is used as input to GetProductSearchResults or GetSearchResults. For all other values, the value ID is indicated in Value.id.
...ValueList.Value.Name	String	The human-readable name for the value (e.g., the name of the cell phone model). Max length varies per attribute. Max column size in database is 60. For buy-side product finders, do not use this predefined name as input to GetSearchResultsCall. Instead, pass the numeric value from ValueList.Value.id as input to GetSearchResultsCall (in the ValueID field).
Attribute.Dependency	Container	The value list (if any) to be presented for the specified child attribute (childAttrId) if the specified parent value (parentValueId) is selected. This list is defined within the meta-data of the parent characteristic (see Characteristic Parent-Child Relationships (Dependencies)). count (integer): The quantity of Value nodes within the list. childAttrId (integer): The ID of the child attribute (e.g., 37 for Event Type 2) whose values this dependency list can affect. parentValueId (integer): The value ID in the parent attribute's ValueList (e.g., 1001 for "Concerts", in the Event Type attribute's value list) which will cause this dependency list to be used. type (integer): The impact on the specified child attribute (childAttrId) if the specified parentValueId is selected. These dependency types have the same meaning as the dependencies defined in the Attributes model. Possible values: 1 = Value-to-Value Client (VVC): The child's value list changes via client. 2 = Value-to-Value Post (VVP): The child's value list changes via server post. 3 = Value-to-Value Selective Post (VVSP): The child's value list changes via client or post. 4 = Value-to-Attribute (VA): The child's visibility and listing validity changes. 5 = Value-to-Meta (VM): The child's required status changes.
...Dependency.Value	Container	A value that the user can search against. Container node for the Name element. id (integer): Identifier for the dependent attribute's value. Possible ID values: -3 = User can enter an arbitrary value -24 = "-" (initial dash to present as a default) -100 = Value not specified (null) ID = Identifier for a pre-defined value. Unique within the characteristics set (e.g., 10256)
...Dependency.Value.Name	String	The human-readable name for the dependent attribute's value. Max length varies per attribute. Max column size in database is 60.

PresentationInstruction Elements

The PresentationInstruction node provides hints about how to display a product finder in a graphical user interface.

Future versions of the presentation instructions may not be backward compatible. They are included in the API primarily for use with the Product Finder XSL stylesheet to render a product finder. If you are not using the Product Finder XSL and you choose to use the presentation instructions, avoid hard-coding the values in your application because the rules can be subject to change. Check for updates to the meta-data on a daily basis to assure you are in sync with eBay's current version. It is also a good idea to keep a backup of the last version of the meta-data that you downloaded, so that you can revert to the last version if necessary.

Please note that different product finders can return different combinations of presentation instructions, including XML attributes. Some presentation instruction elements may include additional XML attributes that are not documented. These are usually specific to one particular product finder and are used internally at eBay. Applications can ignore this internal information.

Table 23-12 describes the elements contained in the PresentationInstruction node in the Product Finder XML.

Table 23-12 PresentationInstruction Content

Element	Data Type	Meaning/Notes
DomainName	String	The well-known name of the characteristic set (e.g., "PDAs/Handheld PCs"). (The term domain is maintained in the eBay code for historical reasons. A domain is equivalent to a characteristic set.)
Row	Container	Contains one or more Widget elements. The Product Finder XSL stylesheet renders Row elements from top to bottom in the order that they appear in the XML.
Row.Widget	Container	Contains presentation instructions related to one or more attributes. Widget elements within the same Row element are displayed side-by-side. type (string): The nature of the widget. Possible values: combine = Simple checkbox for the label (no separate value) date = Date selector (see Input below) normal = Input or selection element numeric_range_single = Numeric range selector text_message = Plain text (read-only)
...Attribute	Container	Contains the presentation instructions for one attribute. id (integer): The attribute ID align (string): Alignment of the attribute (including label and values) within its table cell (e.g., left, right, center). quadrant (string): The layout of the attribute name in relation to the input element. Possible values: top = Above the attribute input control bottom = Below the attribute input control left = To the left of the attribute input control right = To the right of the attribute input control hide (boolean): If True (1), the widget is initially hidden when the product finder is presented to the user.
...Attribute.Input	Container	The type of control to use when presenting the attribute. To maintain a look and feel that is consistent with eBay and familiar to eBay users, your application should present the attribute using the specified type of input element. align (string): Alignment of the label within its table cell (e.g., left, right, center). color (string): Color of the label text in hexadecimal (e.g., #000000 for black). columns (integer): Number of columns in which to display check boxes or radio buttons. face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system). maxlength (integer): Number of characters that can be entered for a textfield. size (integer): Font size of values within type=dropdown, multiple, or single. type (string): The type of input element to use. Possible values include: dropdown = A drop-down list. Can contain an "Other" value. textfield = Text-entry box (for a single string) single = A combo box that permits one value to be selected. radio = A set of radio button(s). Only a single selection is allowed. multiple = A list box that permits multiple values to be selected. checkbox = A set of check box(es). Multiple values can be selected.
...Attribute.Label	String	Instructions for presenting the attribute's display name. Some instructions are only applicable for applications with graphical user interfaces. align (string): Alignment of the label within its table cell (e.g., left, right, center). color (string): Color of the label text in hexadecimal (e.g., #000000 for black). face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system). size (integer): The relative size of the font given the base size font is 3.
...Attribute.LabelMax	String	Instructions for the text to use for a text field that identifies the high end of a range attribute. Some instructions are only applicable for applications with graphical user interfaces. face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system). size (integer): The relative size of the font given the base size font is 3. align (string): Alignment of the label within its table cell (e.g., left, right, center). color (string): Color of the label text in hexadecimal (e.g., #000000 for black).
...Attribute.LabelMin	String	Instructions for the text to use for a text field that identifies the low end of a range attribute. Some instructions are only applicable for applications with graphical user interfaces. face (string): A comma-separated list of font faces to use, in order of preference (if available on the user's system). size (integer): The relative size of the font given the base size font is 3. align (string): Alignment of the label within its table cell (e.g., left, right, center). color (string): Color of the label text in hexadecimal (e.g., #000000 for black).

SortAttributes Elements

A sort attribute is a product aspect or feature that can be used as a sort key when you search for catalog products (i.e., when you execute GetProductSearchResultsCall). This does not necessarily match a searchable attribute. For example, you might be able to search on a product's title but sort the results by the release date or the manufacturer's suggested retail price (MSRP).

Table 23-13 describes the elements contained in the SortAttributes node in the Product Finder XML.

Table 23-13 SortAttributes Content

Element	Meaning/Notes
Attribute	Identifies a product aspect or feature that can be used as a key for sorting catalog search results. Multiple Attribute nodes can appear within a SortAttributes node. Applications should ensure that only one attribute is selected as a sort key from these results (before using GetProductSearchResultsCall). The default sort key is the one with the lowest DisplaySequence value. DisplaySequence (integer): Relative position of the sort key in a list that would be presented to a user. The attribute with the lowest display sequence is considered the default sort key for GetProductSearchResultsCall. Aside from that, usage of this display sequence information is optional. For example, in an application with a graphical user interface, an attribute with a display sequence of 2 could be presented before one with a display sequence of 3 in a drop-down list. If multiple sortable attributes are returned for a characteristic set, compare their display sequences to determine the lowest sequence value and the overall sequence. id (integer): Unique identifier for the attribute within the characteristic set.
Attribute.DateFormat	Only returned if the attribute is a Date data type. This specifies the date pattern that will be used. Possible values: Day/Month/Year Month/Year Year Only
Attribute.DisplayUOM	The unit of measure (e.g., Inch or Megabyte) that is associated with the attribute (if any). Not returned if not applicable.
Attribute.Label	The label to display when presenting the sort attribute to a user. Not necessarily the same as the attribute's label as defined in the characteristic set (i.e., the sort field's label could be overridden by the catalog). visible (boolean): If true (1), the value of Label is visible on the eBay site. If false (0), the label is not visible. Usage of this information is optional. You are not required to display labels in the same manner as eBay.
Attribute.SortOrder	Indicates the order in which the search engine will sort the results if you pass this attribute as the sort key when calling GetProductSearchResults. Applications cannot change the sort order of a sort attribute. Possible values: 0 = Unspecified* 1 = Ascending 2 = Descending * Returned in the order in which the results are stored (e.g., for international sites that use ideographic characters).