Pranay Aryal

Pranay Aryal / 19th May 2023

Pubmed Api

What is pubmed?

Pubmed is a website clinicians and researchers visit to look for research articles. I recently visited the API website, but it appeared outdated and lacked a modern and polished look.

I have selected and highlighted the favorable aspects mentioned there, although there might be a few omissions. For a comprehensive description, please refer to the provided link above.

The base URI for the API is https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

See the demo here

Table of contents:

1. API Key

2. Basic Searching

3. Storing Search Results

4. Getting Summaries

5. Getting Full Data

6. Spelling Suggestions

7. Related Articles

8. Database Statistics annd Search Terms

1

API Key

API keys can be obtained from http://www.ncbi.nlm.nih.gov/account/after you create an account
Once the key has been generated, users are required to incorporate it into every E-utility request by assigning it to the api_key parameter.
Example request including an API key:

esummary.fcgi?db=pubmed&id=123456&api_key=ABCDE12345

Example error message if rates are exceeded:

{
  "error": "API rate limit exceeded",
  "count": 11
}
2

Basic Searching

Endpoint:

esearch.fcgi?db=<database>&term=<query>
By utilizing this API endpoint, you can initiate a search for a specific term, and in response, you will receive a collection of UIDs, which serve as unique identifiers for articles.

Functions:

Provides a list of UIDs matching a text query.

UID:

Unique Identifier

BaseUrl: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed

Output:

List of UIDs matching a query

Example:

Get the PubMed IDs (PMIDs) for articles about breast cancer published in Science in 2008

Uri:

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=science[journal]+AND+breast+cancer+AND+2008[pdat]&retmode=json
You can remove the &retmode=json to default it to xml.
3

Storing Search Results

Can be used to save your query results in the pubmed server.
Later on, when combining the results as I will explain, it will be necessary for you to utilize this information.
esearch.fcgi?db=<database>&term=<query>&usehistory=y

Input:

Any query; Entrez database (&db); &usehistory=y

Output:

Web environment (&WebEnv) and query key (&query_key).

Example:

Get the PubMed IDs (PMIDs) for articles about breast cancer published in Science in 2008.
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=science[journal]+AND+breast+cancer+AND+2008[pdat]&usehistory=y
Use &retmode=json to get the json output
This will return a WebEnvId in the repsonse.
Use WebEnvId in a subsequent request like this:
esearch.fcgi?db=<database>&term=<query2>&usehistory=y&WebEnv=$web1
Use the "epost" endpoint to save a set of UIDs in the database
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/epost.fcgi?db=gene&id=7173,22018,54314,403521,525013
This will also return a WebEnvId which you can use in a subsequent request.
{
  "header": {
    "type": "esearch"
  },
  "esearchresult": {
    "querykey": "1",
    "webenv": "MCID_63a5a3e077047a",
    "idlist": [
      "19008416",
      "18927361",
      "18937361",
      "28937361"
    ],
    "translationset": "..."
  }
}
4

Getting Summary

It provides summaries of studies for a given list of pubmed IDs separate by commas.
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=16899775,33164953&version=2.0
Add a &retmode=json if you want the above in json format
You can also get the summary if you have used the usehistory=y as described above in Store Search Results
5

Getting Full Data

It downloads full data

Endpoint:

efetch.fcgi?db=<database>&id=<uid_list>&rettype=<retrieval_type>&retmode=<retrieval_mode>

Input:

List of UIDs (&id); Entrez database (&db); Retrieval type (&rettype); Retrieval mode (&retmode)`
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=nuccore&id=34577062,24475906&rettype=json&retmode=text
6

Spelling Suggestions

Endpoint:

espell.fcgi?term=<query>&db=<database>

Input:

Entrez text query (&term); Entrez database (&db)

Output:

XML or json containing the original query and spelling suggestions.

Example:

Find spelling suggestions for the PubMed Central query ‘fiberblast cell grwth’.
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/espell.fcgi?term=rhuinitis&db=pubmed
Responds to a list of UIDs in a given database with either a list of related UIDs (and relevancy scores) in the same database or a list of linked UIDs in another Entrez database
Batch mode – finds only one set of linked UIDs
elink.fcgi?dbfrom=<source_db>&db=<destination_db>&id=<uid_list></uid_list>

Input:

List of UIDs (&id); Source Entrez database (&dbfrom); Destination Entrez database (&db)

Output:

XML containing linked UIDs from source and destination databases

Example:

Find one set of Gene IDs linked to nuccore GIs 34577062 and 24475906
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=pubmed&db=pubmed&id=34525277
7

Optional Parameters

1.

retmode:

Set this to json to return in a json format

2.

retstart:

Index of first UID to be shown

3.

retmax:

Total number of UIDs to be shown

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=science[journal]+AND+breast+cancer+AND+2008[pdat]&retmode=json&sort=pub_date
5.

field:

Search field. If used, the entire search term will be limited to the specified Entrez field. The following two URLs are equivalent:

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=science[journal]+AND+breast+cancer+AND+2008[pdat]&retmode=json&sort=pub_date
3.

datetype:

3.

mindate, maxdate:

8

Database Statistics And Search Fields

Endpoint:

einfo.fcgi?db=<database>

Output:

XML containing database statistics
Note: If no database parameter is supplied, einfo will return a list of all valid Entrez databases

Example:

Find database statistics for Entrez Pubmed
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi?db=pubmed
Use &retmode=json to get the json output
Have questions on above, shoot me a chat in the box below.