Skip Navigation Bar
NLM logo

EDirect Documentation

Please note: following the release of the new version of PubMed, the results returned by E-utilities queries of PubMed may differ slightly from those returned in the web version of PubMed. A new PubMed API is currently under development: more information will be announced when available.

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.

The EDirect package includes several commands which use the E-utilities API to help you find and retrieve PubMed data. In addition, EDirect includes a handful of commands which can help you extract, process, and work with the data you have retrieved.

Six EDirect commands use the E-utilities API:

  • esearch: Uses the ESearch utility to search an NCBI database.
  • efetch: Uses the EFetch utility to download records from an NCBI database in a specified format.
  • epost: Uses the EPost utility to post a list of unique identifiers (UIDs; i.e. PMIDs) to the History server, so they can be used by a later command.
  • einfo: Uses the EInfo utility to display a list of NCBI databases which can be accessed by E-utilities, or summary information about a specific database.
  • efilter: Uses the History server to filter or restrict the results of a previous query.
  • elink: Uses the ELink utility to look up similar, related, or otherwise connected records in the same database, or linked records in a different database.

Three EDirect commands do not use the E-utilities API:

  • xtract: Extracts specific data from XML and creates tabular output, based on your custom specifications. Note: The xtract command is very flexible and customizable, and has many options, so we have broken the documentation into several pages:
    • Overview: An introduction to the xtract command.
      • Arguments discussed: -pattern and -element; plus attributes and Parent/Child construction.
    • Creating rows and columns: Creating the rows and columns of a basic table.
      • Arguments discussed: -pattern and -element.
    • Formatting arguments: Adjust the separators between columns and data elements, and define placeholders for blank values.
      • Arguments discussed: -tab, -sep, and -def.
    • Exploration arguments: Explore subsections of your XML document and link multiple child elements of the same parent together.
      • Arguments discussed: -block and others.
    • Filtering output with Conditional arguments: Include or exclude data from your output, based on certain conditions.
      • Arguments discussed: -if, -unless, -equals, -contains, -position and others.
    • Storing and retrieving information with variables: Pass information from one part of an xtract command to another, using custom variables.
      • Arguments discussed: creating custom arguments to assign data to variables.
  • sort-uniq-count-rank: Displays each unique line of text from the input, along with the number of times each unique line occurred in the input, sorted from most to least frequently occurring.
  • word-at-a-time: Parses passages of text into individual lines, with each word appearing on its own line.

One EDirect command sometimes uses the E-utilities API:

  • nquire: Creates a URL to query a server based on your specifications.

When working with EDirect in Unix, you may also want to use some Unix tools which are not part of EDirect, to help you work with and process data.

Some helpful Unix commands and operators:

  • cat: Opens files into your terminal, and concatenates multiple files together.
  • cut: Trims portions of each line of text.
  • head/tail: Restricts output to only the first or last portion.
  • sort: Sorts output.
  • >: Redirects the output of a command to a file.
  • $: Accesses the value of a variable or command.

If you need more EDirect documentation, please visit NCBI’s EDirect documentation page, “Entrez Direct: E-utilities on the UNIX Command Line”.

As of EDirect version 8.00, EDirect now includes tools and methods to help you download the entirety of PubMed onto a local drive and organize the data to make it easy to retrieve and work with using EDirect. Creating a local copy of PubMed requires some technical expertise and has certain minimum hardware requirements, but may be very useful for experienced EDirect users who need to work with extremely large amounts of PubMed data (i.e. tens or hundreds of thousands of records).

For more information and documentation on these tools and methods, please see “Using EDirect to create a local copy of PubMed”.

Last Reviewed: August 6, 2021