How does E-utilities work?
As new Insider's Guide classes are no longer being offered, this site is not currently being updated. Please refer to NCBI's E-utilities documentation for more up-to-date information.
E-utilities uses structured URLs to search and retrieve the requested data. The URL asks the NCBI server for information and returns it in a specific format. The information that you get, and the format that it’s in, depends on how you construct the URL.
The three parts of an E-utilities URL
Each URL consists of three parts:
- The base URL: This is the address of the E-utilities server. Every URL begins with https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
A utility name: This is the name of the specific tool that you are using. There are nine E-utilities and each one performs a specific function:
- ESearch: Search a text query in a single database and retrieve the list of matching unique identifiers (UIDs). In PubMed, ESearch retrieves a list of PMIDs.
- ESummary: Retrieve document summaries for each UID.
- EFetch: Retrieve full records for each UID.
- EPost: Upload a list of UIDs for later use.
- ELink: Retrieve UIDs for related or linked records, or LinkOut URLs.
- EInfo: Retrieve information and statistics about a single database.
- ESpell: Retrieve spelling suggestions for a text query.
- ECitMatch: Search PubMed for a series of citation strings.
- EGQuery: Search a text query in all databases and return the number of results for the query in each database.
Each of the nine E-utilities ends with the file extension “.fcgi?” (which stands for Fast Common Gateway Interface). The utilities are described in more detail here: The 9 E-utilities and Associated Parameters.
- The parameters: These are the details of your query. Common parameters include the name of the database, your search terms, the number of results you’d like to get, and the format. The parameters that are available will change depending on the utility.
Putting the three parts together
Searching PubMed with ESearch
When you put these three parts together, you will have a URL that looks something like this:
If you click on this link or copy and paste the URL into your browser, you will see that it retrieves the unique identifiers (UIDs; in this case, PMIDs) for all citations in PubMed from the journal “Nature” with the term “3D printing”.
The base URL provides the address of the E-utilities server: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
The utility in this case is ESearch (esearch.fcgi?), which will allow us to search a database.
This URL has two parameters, “db” and “term”. The “db” parameter specifies the PubMed database. The “term” parameter specifies the text that we are looking for, in this case, “nature” in the journal field and “3D printing” in all fields: db=pubmed&term=nature[journal]+AND+3D+printing
By default, the information is retrieved in XML format. If you scroll through the XML you’ll see the number of records retrieved along with a list of PMIDs for those records. Scroll further and you will see the search translation - just like you would see in PubMed’s “Search details” window. In fact, you’ll notice that ESearch has the same translation and details that you would get if you typed “nature[journal] AND 3D printing” into the search box. The search results are the same.
Retrieving records with EFetch
Our ESearch URL retrieves a list of PMIDs - not full records. To get the full records you would use EFetch, and the URL would look something like this:
Clicking on this link or copying and pasting the URL into your browser will retrieve the citations for these four PMIDs and display the text abstract. You can see that the base URL has stayed the same: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
The utility in this case is EFetch (efetch.fcgi?), which will retrieve the full records.
The “db” parameter is still “pubmed”. But our other parameters have changed. We include the PMIDs of the records with the “id” parameter, and then use the “retmode” (return mode) of “abstract” and “rettype” (return type) of “text”, which determine the format our records will be returned in: id=27558065,27466125,27127816,26842040&retmode=abstract&rettype=text
These examples show the basic structure of the E-utilities URLs and are meant to show the types of queries that you can build with E-utilities.
Next steps…
The Insider’s Guide classes are designed to introduce E-utilities and build on that foundation. Classes include an online instructional session (available live or asynchronous), and are supported by documentation, sample code, and other educational materials which you can find throughout this website.
If you are new to APIs and E-utilities, we suggest you start with our introductory class, “Welcome to E-utilities for PubMed”. We hope that once you see how useful E-utilities is, you will continue to explore how you can put these tools to work for you!