The keywords field is the basis for item searches. The search calls, such as findItemsByKeywords, search for item listings where the specified keywords are found in the title and, in some cases, the item subtitle or structured item data, returning those matching items in the result set. Queries aren't case-sensitive, so it doesn't matter whether you use uppercase or lowercase letters.
The following search features help you get the most relevant search results possible with your keyword queries.
Advanced Search Operators
The value specified in the keywords field can contain one or more keywords. The words "and" and "or" are treated like any other word. Only use "and," "or," or "the" if you are searching for listings containing these words. You can use AND or OR logic by including certain modifiers. Be careful when using spaces before or after modifiers, such as plus signs ("+") or minus signs ("-").
@1 baseball autograph card +star would be URL-encoded as %401+baseball+autograph+card+%2Bstar and "baseball card" would be URL-encoded as %22baseball+card%22. For more information, see the Name-value Syntax section in Making a Call.
The following table shows the operators and character punctuation that can be used in keyword queries, and the effects they have:
| Operator | Description | Example | Returns |
|---|---|---|---|
| Space between words | Applies AND logic to multiple keywords. | baseball card
|
Items with both the words "baseball" and "card". Note: Keyword queries consisting of keywords separated by spaces only are subject to automatic keyword expansions. |
| Comma (,) between words, with no parentheses or spaces | Requires an exact sequence of words. | baseball,card
|
Items with the exact phrase "baseball card" in the title. This is equivalent to specifying the keywords, separated by spaces, in order within quotation marks (e.g., "baseball card"). |
| Comma between words in parentheses and no spaces | Applies OR logic to multiple keywords. | (baseball,card)
|
Items with either the word "baseball" or the word "card" in the title. |
| Quoted (" ") words | Requires an exact sequence of words. | "baseball card"
|
Items with the exact phrase "baseball card" in the title. |
| Minus ("-") sign before a word | Applies NOT logic to a single word. Specified word cannot be present. | baseball -autograph
|
Items that have the word "baseball" but not "autograph". Note: A keyword query cannot consist of excluded words only. You must include one or more search terms in order to use the NOT operator ("-"). For example, "-autograph" is not a valid keywords value on its own, but "baseball -autograph" (i.e., |
| Minus ("-") sign before a group of words in parentheses | Applies NOT logic to a group of words. Specified words cannot be present. | baseball -(autograph,card,star)
|
Items with the word "baseball" but not "autograph," "card," or "star". |
| Asterisk ("*") | Substitutes for one or more characters. | baseball*
|
This operator is no longer supported. Items starting with the string "baseball". Use with a minimum of 2 characters. |
| At sign ("@") | Search must find two of three words from a list. | @1 baseball autograph card
|
Items with two of the three words "baseball," "autograph," and "card". For a "3 out of 4" search, use @2 and a list of four words. |
| Plus sign ("+") | Concatenates a query string using AND logic with another keyword. | @1 baseball autograph card +star
|
Items with any two of the three words "baseball," "autograph," or "card" in the title plus the word "star". |
With the exception of the advanced search operators, punctuation marks, such as hyphens (-), commas followed by spaces (, ), exclamation points (!), question marks (?), slashes (/), and forward slashes (\) are excluded from matching. For example, a search for "3/4 sleeve" (i.e., <keywords>"3/4 sleeve"</keywords>) will match "3-4 sleeve", "3\4 sleeve", "3/4-sleeve", etc.
Automatic Keyword Expansions
Keyword queries always search item titles for words or phrases that match exactly the keywords you specified. In some cases, eBay automatically expands keyword queries to increase the number of relevant results in the response. Keyword searches can be expanded by expanding the query and/or expanding the places in which to search for matching terms. This is why search results may contain items with titles that do not have all the keywords you specified in your query.
Using advanced search operators (e.g., " ", ( ), -, +, *, or @) in your keyword query disables automatic keyword expansions. For example, an exact phrase search, such as <keywords>"baseball card"</keywords> will limit the search results to items with the exact phrase in the title only.
| Expansion Type | Description |
|---|---|
| Keyword to keyword | Modifies your keyword query to search for either your original keywords, or a synonymous keyword from eBay's dictionary, such as a root word or a plural form. |
| Keyword to category | Modifies your query to search for items that have a specific keyword in the title or for items listed in a specific related category. |
| Keyword to structured item data | Modifies your query to search for items that have the keywords from the original query in the title or in the item's structured data, such as item specifics or parts compatibility information. |