The search query parameter finds results that match a given text search. Example:
- Get works with search term "dna" in the title, abstract, or fulltext:
https://api.openalex.org/works?search=dna
When you search works, the API looks for matches in titles, abstracts, and fulltext. When you search concepts, we look in each concept's display_name and description fields. When you search sources, we look at the display_name, alternate_titles, and abbreviated_title fields. When you search authors, we look at the display_name and display_name_alternatives fields. When you search institutions, we look at the display_name, display_name_alternatives, and display_name_acronyms fields.
For most text search we remove stop words and use stemming (specifically, the Kstem token filter) 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:
https://api.openalex.org/works?filter=display_name.search.no_stem:surgeryhttps://api.openalex.org/works?filter=title.search.no_stem:surgeryhttps://api.openalex.org/works?filter=abstract.search.no_stem:surgeryhttps://api.openalex.org/works?filter=title_and_abstract.search.no_stem:surgery
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 search filters.
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 query string query 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.
- Search for works that mention "elmo" and "sesame street," but not the words "cookie" or "monster":
https://api.openalex.org/works?search=(elmo AND "sesame street") NOT (cookie OR monster)
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:
- Get works with the exact phrase "fierce creatures" in the title or abstract (returns just a few results):
https://api.openalex.org/works?search="fierce%20creatures" - 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):
https://api.openalex.org/works?search=fierce%20creatures
You can also use search as a filter, 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:
https://api.openalex.org/authors?filter=display_name.search:einstein - Get works with "cubist" in the title:
https://api.openalex.org/works?filter=title.search:cubist
Additionally, the filter default.search is available on all entities; this works the same as the search parameter.
{% hint style="info" %}
You might be tempted to use the search filter to power an autocomplete or typeahead. Instead, we recommend you use the autocomplete endpoint, which is much faster.
👎 https://api.openalex.org/institutions?filter=display_name.search:florida
👍 https://api.openalex.org/autocomplete/institutions?q=Florida
{% endhint %}