Unpaywall Title Search Endpoint


The Unpaywall title search endpoint gives you the full DOI API response for articles with titles matching your query. 50 results are returned at a time. The page argument can be used to get results after the first 50. The main use cases are:


  • Collecting metadata (titles, years, DOIs, fulltext availability status, etc.) for articles on a certain topic.

  • Using the is_oa filter to find fulltext articles about topics you’re interested in.


An example query and its response looks like this:


https://api.unpaywall.org/v2/search/?query=hungry%20hippos&is_oa=true&email=YOUR_EMAIL


{

  "results": [

    {

      "response": a DOI object as returned by /v2/:doi

      "score": 0.055811062,

      "snippet": "<b>Hippo</b>: <b>Hungry</b>, <b>Hungry</b> for Melanoma Invasion"

    },

   … more results

  ]

  "elapsed_seconds": 0.047,

}


This endpoint is in its early stages, and is pretty basic for now. We may add other features based on demand, like different sorting, more results, and more filters. If there’s a feature you want to see, get in touch with us and lay out your use case.


A simple frontend for the search API is here: http://unpaywall.org/articles 


Usage Notes and Limitations


  • It only searches article titles. Not authors, affiliations, journal names, abstracts, or anything else. You can search for repositories and journal titles (eg. “BioRxiv” or “New England Journal of Medicine”)  at https://unpaywall.org/sources. If you already have a list of DOIs, the Simple Query Tool is for you: https://unpaywall.org/products/simple-query-tool.

  • All 120M+ articles in our database are searched - not just OA ones. We are searching every title that has a Crossref DOI, including just-published ones (with a lag of up to 24 hours). Use the is_oa parameter to limit results to OA articles if desired.

  • Results are ranked by relevance using a form of cover density ranking. No other ranking is supported for now. In order of decreasing importance, relevance is determined by:

    • How many words in the query are in the title. 

      • For the query tree frogs, All About Tree Frogs is a better match than All About Frogs

    • How close together the matched terms are:

      • For the query peanut butter, I Love Peanut Butter is a better match than Peanuts Are Great And So Is Butter

    • How long the title is:

      • The more of the title your search terms make up, the better. For the query turtles, I Like Turtles is a better match than These Are A Few Of My Favorite Turtles.



  • Search terms are separated by whitespace and are AND-ed together by default. The title must contain all search terms to be matched. This can be modified by:

    • "quoted text": words inside quotation marks must appear as a phrase to match

      • "hungry hippos" matches Hungry Hippos Ate All My Marbles, but not Those Hippos Sure Look Hungry

    • OR: replaces the default AND between words, making a match on either word

      • rock OR roll matches 1001 Facts about Rocks and How To Bake Rolls and Rock and/or Roll

    • -: negation, only titles not containing this term will match

      • hungry -hippos matches Hungry Rhinoceri but not Hungry Hippos


  • is_oa is the only available attribute filter


  • Use the page argument to get results after first 50. page=3 will return the 101st through 150th best matches.


Example Queries



  • query: wave or particle

    • Get the most relevant results with “wave” OR “particle” in their titles, regardless of OA status.



  • query: wave -ocean

    • Get the most relevant articles with titles containing “wave” but NOT “ocean”, regardless of OA status.