Search entities
Last updated
Last updated
search parameterThe search query parameter finds results that match a given text search. Example:
Get works with search term "dna" in the title, abstract, or fulltext:
When you , the API looks for matches in titles, abstracts, and . When you , we look in each concept's display_name and description fields. When you , we look at the display_name, alternate_titles, and abbreviated_title fields. When you , we look at the display_name and display_name_alternatives fields. When you , we look at the display_name, display_name_alternatives, and display_name_acronyms fields.
For most text search we remove and use (specifically, the ) to improve results. So words like "the" and "an" are transparently removed, and a search for "possums" will also return records using the word "possum." With the exception of raw affiliation strings, we do not search within words but rather try to match whole words. So a search with "lun" will not match the word "lunar".
To disable stemming and the removal of stop words for searches on titles and abstracts, you can add .no_stem to the search filter. So, for example, if you want to search for "surgery" and not get "surgeries" too:
Including any of the words AND, OR, or NOT in any of your searches will enable boolean search. Those words must be UPPERCASE. You can use this in all searches, including using the search parameter, and using .
This allows you to craft complex queries using those boolean operators along with parentheses and quotation marks. Surrounding a phrase with quotation marks will search for an exact match of that phrase, after stemming and stop-word removal (be sure to use double quotation marks — "). Using parentheses will specify order of operations for the boolean operators. Words that are not separated by one of the boolean operators will be interpreted as AND.
Behind the scenes, the boolean search is using Elasticsearch's on the searchable fields (such as title, abstract, and fulltext for works; see each individual entity page for specifics about that entity). Wildcard and fuzzy searches using *, ? or ~ are not allowed; these characters will be removed from any searches. These searches, even when using quotation marks, will go through the same cleaning as desscribed above, including stemming and removal of stop words.
When you use search, each returned entity in the results lists gets an extra property called relevance_score, and the list is by default sorted in descending order of relevance_score. The relevance_score is based on text similarity to your search term. It also includes a weighting term for citation counts: more highly-cited entities score higher, all else being equal.
If you search for a multiple-word phrase, the algorithm will treat each word separately, and rank results higher when the words appear close together. If you want to return only results where the exact phrase is used, just enclose your phrase within quotes. Example:
Search for works that mention "elmo" and "sesame street," but not the words "cookie" or "monster":
Get works with the exact phrase "fierce creatures" in the title or abstract (returns just a few results):
Get works with the words "fierce" and "creatures" in the title or abstract, with works that have the two words close together ranked higher by relevance_score (returns way more results):
You can also use search as a , allowing you to fine-tune the fields you're searching over. To do this, you append .search to the end of the property you are filtering for:
Get authors who have "Einstein" as part of their name:
Get works with "cubist" in the title:
Additionally, the filter default.search is available on all entities; this works the same as the .
You might be tempted to use the search filter to power an autocomplete or typeahead. Instead, we recommend you use the , which is much faster. 👎
👍