Skip to main content
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

The Insider's Guide to Accessing NLM Data

The 9 E-utilities and Associated Parameters

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.

While all E-utilities URLs begin with the same base URL (https://eutils.ncbi.nlm.nih.gov/entrez/eutils/ ), the E-utilities API actually includes nine different utilities, each of which allows you to formulate a different type of query. Which utility you choose to use will depend on the type of question you are asking. Additionally, each utility allows or requires a different set of parameters. Which parameters you use will define the details of your query. To learn more about combining the base URL, utility name, and parameters to create an E-utilites URL, please see the “How does E-utilities work?” page of our Insider’s Guide Overview.

This page provides information about each of the nine utilities, and provides explanations of many of the parameters E-utilities users should be aware of, especially those working primarily with PubMed data.

The 9 E-utilities

  • Introductory Notes
  • ESearch: Search a text query in a single Entrez database.
  • 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 Entrez databases and return the number of results for the query in each database.

Introductory Notes

Usage Guidelines

To avoid overloading the E-utilities servers, NCBI asks that you follow a few guidelines when using E-utilities. Details of these guidelines can be found in NCBI’s “A General Introduction to E-utilities” in the Usage Guidelines and Requirements section. Most of these guidelines apply to using E-utilities programmatically, as part of an application or script. However, even ad hoc users should be aware of them. In short, these guidelines cover four general areas:

  • Frequency: Please do not post more than three URL requests per second.
  • Timing: Please try to limit large jobs to either weekends or between 9:00 PM and 5:00 AM Eastern time during weekdays.
  • Identification: Especially for larger jobs or applications, we suggest that you use the tool and email parameters (see below) so NCBI can contact you should your application cause unintended issues.
  • Quantity: For some utilities (like ESearch, EFetch, and ESummary), there are limits to how many records can be retrieved with a single URL. For example, each ESearch URL can only retrieve up to 100,000 UIDs. If you wish to exceed these limits, you can use the retstart/retmax parameters, or the NCBI History server.

To enable NCBI to contact you in the event of problems with your use of E-utilties, the tool and email parameters are allowed (and encouraged) on any E-utilities URL:

  • tool: Name of the application making the E-utility call (no spaces allowed).
  • email: Your E-mail address. NCBI will use this to contact you if your application is causing unintended issues to the server.

Parameters and the History server

The E-utilities API is at its most powerful when you combine multiple E-utilities queries together in sequence. One way to accomplish this is by storing the results of an E-utilities query on NCBI’s History server. It is then possible to retrieve these stored results and incorporate them in a later E-utilities query.

For the sake of simplicity, we have left these parameters off this page, but you can find out much more about the History server and the relevant parameters on our “E-utilities and the History server” page.

ESearch

ESearch (esearch.fcgi) searches a database and returns a list of unique identifiers (UIDs) for records in that database which meet the search criteria. You can specify the search query, sort results, filter results by date, or combine multiple searches with Boolean AND/OR/NOT by adjusting the parameters. Remember, ESearch only returns UIDs, not full records. To retrieve the full records for each of the UIDs in your result set, consider using the EFetch utility.

ESearch Parameters

ESearch Required Parameters

  • db (required): Which database you wish to search. You can see NCBI’s table of Entrez Unique Identifiers (UIDs) for a complete list of allowable database names, but some example values include:

    • pubmed: PubMed
    • pmc: PubMed Central
    • nlmcatalog: NLM Catalog

  • term (required): The text query you wish to search for, similar to the search string you would put into an Entrez database’s web interface. All special characters must be URL encoded (a.k.a “percent encoded”); for more information on URL encoding, see W3Schools’ URL Encoding Reference page. Spaces may be replaced by ‘+’ signs. See the PubMed Help for information about search field descriptions and tags in PubMed.

ESearch Formatting Parameters

  • retstart (optional): Setting this parameter helps limit which of the unique identifiers (UIDs) in the results set will be shown in the output, as it determines whether the output begins at the first retrieved UID, or with a UID that is later in the results set. For example, if retstart is set to 10, the first ten UIDs in the results set will be skipped, and the output will begin with the eleventh UID. The default of this parameter is 0, corresponding to the first record in the entire set. This parameter can be used in conjunction with retmax to download an arbitrary subset of UIDs retrieved from a search.
  • retmax (optional): Total number of unique identifiers (UIDs) from the retrieved set to be shown in the output (default=20). Increasing retmax allows more of the retrieved UIDs to be included in the output, up to a maximum of 100,000 UIDs. If you need to retrieve more than 100,000 UIDs, you can submit multiple ESearch requests, and increase the retstart parameter each time. For example:
  • rettype (optional): Retrieval type. There are two supported values:
    • uilist (default): Displays the standard XML output, including a list of unique identifiers (UIDs), the total number of results, and the query translation for the search.
    • count: Displays only the total number of results, without the list of UIDs or query translation.
  • retmode (optional): Determines the format of the returned output. The default value is xml, but json is also supported.

ESearch Date Filter Parameters

  • datetype (optional): If you are limiting your search by date, this parameter determines which date field you wish to limit by. Available date types vary by database. For PubMed, valid datetype values include:

    • crdt: Create Date (For records added after December 18, 2008, this is the date the citation was first added to PubMed. For more details, see the entry for “Create Date” in MEDLINE/PubMed Data Element (Field) Descriptions.)
    • edat: Entrez Date (For records added after October 9, 2008, this is the date the citation was added to PubMed, except for records added more than twelve months after the date of publication. For more details, see the entry for “Entrez Date” in MEDLINE/PubMed Data Element (Field) Descriptions.)
    • pdat: Publication Date (The article’s publication date.)
    • mhda: MeSH Date (The date the citation was indexed with MeSH. If the citation has not yet been indexed, this will be the same as the Entrez Date.)

    For more information on date types, see Searching by date in the PubMed Help.

  • reldate (optional): Limit your search to only those items with a date within the last n days. This parameter uses the date field you specified in the datetype parameter.
  • mindate,maxdate (optional): Limit your search to a specific range of dates. You must include both a mindate and a maxdate to specify a date range. Dates can be formatted in the following options:
    • YYYY/MM/DD
    • YYYY/MM
    • YYYY

ESearch Other Parameters

  • sort (optional): Specifies the sort order for the resulting list of unique identifiers (UIDs). The default sort order varies by database (for PubMed, it is most+recent), as do the options for sort order. For PubMed, valid sort values include:

    • journal: Records are sorted alphabetically by journal title, and then by publication date.
    • pub+date: Records are sorted chronologically by publication date (with most recent first), and then alphabetically by journal title.
    • most+recent: Records are sorted chronologically by date added to PubMed (with the most recent additions first).
    • relevance: Records are sorted based on relevance to your search. For more information about PubMed’s relevance ranking, see the PubMed Help section on Computation of Weighted Relevance Order in PubMed.
    • title: Records are sorted alphabetically by article title.
    • author: Records are sorted alphabetically by author name, and then by publication date.

  • field (optional): Limit your search to a specific field. If used, your entire term search query will be searched only within the specified field. This can also be accomplished by including the tag in your term parameter, as if you were tagging a search in the PubMed web interface. For a list of search PubMed search fields, see Search Field Descriptions and Tags in the PubMed Help.

ESearch Examples

ESummary

ESummary (esummary.fcgi) returns document summaries for a list of unique identifiers (UIDs). The list of input UIDs is either provided in the parameters, or is retrieved from the History server.

ESummary Parameters

ESummary Required Parameters

  • db (required): Database containing the unique identifiers (UIDs) for which you wish to retrieve document summaries. You can see NCBI’s table of Entrez Unique Identifiers (UIDs) for a complete list of allowable database names, but some example values include:
    • pubmed: PubMed
    • pmc: PubMed Central
    • nlmcatalog: NLM Catalog
  • id (required): Either a single unique identifier (UID) or a comma-delimited list of UIDs. All of the UIDs must be from the database specified by the db parameter.

ESummary Optional Parameters

  • retstart (optional): Setting this parameter helps limit which document summaries will be shown in the output, as it determines whether the document summary for the first input unique identifier (UID) is retrieved, or whether to skip to a later UID in the input list. For example, if retstart is set to 10, the output will begin with the document summary for the tenth UID. The default of this parameter is 1, corresponding to the first UID in the input list. This parameter can be used in conjunction with retmax to download an arbitrary subset of document summaries.
  • retmax (optional): Total number of document summaries from the retrieved set to be shown in the output, up to a maximum of 10,000. If the set of document summaries you are trying to retrieve is larger than 10,000, you can submit multiple ESummary requests, and increase the retstart parameter each time.
  • retmode (optional): Determines the format of the returned output. The default value is xml, but json is also supported.
  • version (optional): If your summaries are being returned in XML (see retmode), this parameter determines which XML schema to use. If this parameter is not used, the generic DocSum (document summary) schema will be used, which applies to all Entrez databases. However, if you set this parameter to 2.0, the 2.0 DocSum XML schema will be used. This schema uses different fields for each Entrez database, and often provides more (and more specific) information than the default schema.

ESummary Examples

EFetch

EFetch (efetch.fcgi) returns full data records for a list of unique identifiers (UIDs) in a format specified in the parameters. The list of UIDs is either provided in the parameters, or is retrieved from the History server.

EFetch Parameters

EFetch Required Parameters

  • db (required): Database containing the unique identifiers (UIDs) for which you wish to retrieve records. You can see NCBI’s table of Entrez Unique Identifiers (UIDs) for a complete list of allowable database names, but some example values include:
    • pubmed: PubMed
    • pmc: PubMed Central
    • nlmcatalog: NLM Catalog
  • id (required): Either a single unique identifier (UID) or a comma-delimited list of UIDs. All of the UIDs must be from the database specified by the db parameter.

EFetch Optional Parameters

  • retstart (optional): Setting this parameter helps limit which records will be shown in the output, as it determines whether the record for the first input unique identifier (UID) is retrieved, or whether to skip to a later UID in the input list. For example, if retstart is set to 10, the output will begin with the record for the eleventh UID. The default of this parameter is 0, corresponding to the first UID in the input list. This parameter can be used in conjunction with retmax to download an arbitrary subset of records.
  • retmax (optional): Total number of records to be shown in the output, up to a maximum of 10,000. If the set of records you are trying to retrieve is larger than 10,000, you can submit multiple EFetch requests, and increase the retstart parameter each time.

  • retmode/rettype: These two parameters determine how your results will be displayed. retmode determines the data format your records will be returned in (e.g. XML, plain text, etc.). rettype determines the specific view your records will be returned in (e.g. MEDLINE, Abstract, list of PMIDs, etc.). Different databases have different allowable data formats and record views, and not all retmode data formats are compatible with all rettype record views, and vice versa.

    The table below shows the allowable combinations of retmode and rettype for some of the databases. Bold retmode values are the default data format for the specified database. Bold rettype parameters are the default record view for the specified data format and database.

    Databases Record Type retmode rettype
    All Document Summary xml docsum
    All List of UIDs in XML xml uilist
    All List of UIDs in plain text text uilist
    MeSH Full record in plain text text full
    NLM Catalog Full record in plain text text
    NLM Catalog XML xml
    PubMed ASN.1 (text) asn.1
    PubMed PubMed XML xml
    PubMed MEDLINE (text) text medline
    PubMed PMID list (text) text uilist
    PubMed Abstract (text) text abstract
    PubMed Summary (text) text docsum

    Other Entrez databases allow other combinations of retmode and rettype. For details, see NCBI’s “Table of valid values of &retmode and &rettype for EFetch.”

EFetch Examples

EPost

EPost (epost.fcgi) uploads a list of unique identifiers (UIDs) to the History server. There is more information about using the History server to combine multiple searches on our “E-utilities and the History server” page.

EPost Parameters

  • db (required): Database containing the unique identifiers (UIDs) you wish to upload. You can see NCBI’s table of Entrez Unique Identifiers (UIDs) for a complete list of allowable database names, but some example values include:
    • pubmed: PubMed
    • pmc: PubMed Central
    • nlmcatalog: NLM Catalog
  • id (required): Either a single unique identifier (UID) or a comma-delimited list of UIDs. All of the UIDs must be from the database specified by the db parameter.
  • WebEnv: If provided this parameter specifies the Web Environment that you wish to upload the UIDs to. You can think of a Web Environment as your current “session”; if you wish to use multiple posted or saved UID lists together, they must all be in the same Web Environment. If WebEnv is omitted, EPost will create a new Web Environment, and will post your list of UIDs with the query_key value “1”. For more information on Web Environments and query keys, see E-utilities and the History server

EPost Examples

ELink

ELink (elink.fcgi) is a very flexible and powerful utility that takes a list of unique identifiers (UIDs) from one database and returns, for each of the listed UIDs:

  • a list of UIDs for similar, related or otherwise connected records in the same database,
  • a list of UIDs for linked records in a different Entrez database, or
  • a list of LinkOut URLs and attributes for related non-Entrez resources.

Because this utility is so powerful and flexible, and because it involves links between databases (and between databases and external resources), it can be challenging to use some of its more advanced features. New users are advised to have patience.

ELink Parameters

ELink Required Parameters

  • dbfrom: The database containing your input unique identifiers (UIDs). This is the origin database of your link.
  • db: The database from which you wish to retrieve linked unique identifiers (UIDs). This is the destination database of your link. If db and dbfrom are the same database, then ELink will return computational neighbors (i.e. similar or related records) within that database. Note: the db parameter may be omitted if you are using ELink to find LinkOut information instead of similar, related or linked records in an Entrez database.
  • id: Either a single unique identifier (UID) or a comma-delimited list of UIDs. All of the UIDs must be from the database specified by the dbfrom parameter.
  • cmd: This specifies the “command mode” to use with ELink, and determines what type of links or information will be output. Some command modes help identify similar or related records in the same database, others identify linked records in a different Entrez database, and still others identify LinkOut information. The default value for cmd is neighbor, but the other options include:
    • neighbor: Returns a set of UIDs in the db database linked to the input UIDs in the dbfrom database.
    • neighbor_score: Returns a set of UIDs in a database that are similar or related to the input UIDs, along with the the computed similarity scores. Note that neighbor_score returns UIDs from the same database as the input UIDs, and assumes that the db and dbfrom databases are the same.
    • neighbor_history: Functions similarly to neighbor, but stores the results to the NCBI History server and returns a Web environment string and query keys for each set of resulting UIDs, so you can use them in future queries. For more information about using the History server to store and combine query results sets, see our “E-utilities and the History server” page.
    • acheck: Returns a list of all of the available links for the input UIDs. If you specify a db parameter, only links to that database will be shown. Otherwise, links to all databases will be shown.
    • ncheck: Checks for the existence of links between your input UIDs and other UIDs in the same database.
    • lcheck: Checks for the existence of external links (LinkOuts) for your set of input UIDs.
    • llinks: Checks for the existence of external links (LinkOuts) for your set of input UIDs, and returns LinkOut URLs and provider attributes for all non-library providers.
    • llinkslib: Checks for the existence of external links (LinkOuts) for your set of input UIDs, and returns LinkOut URLs and provider attributes for all providers (including library providers).
    • prlinks: Returns the primary LinkOut provider for each input UID. If you input a single UID and use set the retmode parameter to ref, an ELink URL using the prlinks command mode will also redirect to the primary LinkOut provider’s website (using the LinkOut URL).

ELink Limiting Parameters

  • linkname: Records can be linked or related to other records (in either the same or a different database) in a number of ways. Each different type of link can be identified by specifying 1) the database you are linking from, 2) the database you are linking to, and 3) the name of the specific type of link you wish to use, following the naming convention dbfrom_db_subset. (Note that some link names do not include a subset identifier.) The value of the linkname parameter specifies which specific type of link you would like to use.

    The table below shows a selection of different Entrez links for some of the Entrez databases. For a complete list of links for all Entrez databases, see the Entrez Link Descriptions.

    Link Name Link From DB Link To DB Description
    pmc_pubmed PubMed Central PubMed Finds PubMed citations for specified PMC articles
    pubmed_pmc PubMed PubMed Central Finds free full-text versions in PMC of specified articles cited in PubMed
    pubmed_pmc_refs PubMed PubMed Central Finds free full-text articles in PMC that cite the specified PubMed articles
    pubmed_pubmed PubMed PubMed Finds Similar Articles in PubMed to the specified PubMed articles
    pubmed_pubmed_alsoviewed PubMed PubMed Finds PubMed articles frequently viewed together with the specified PubMed articles
    pubmed_pubmed_pmh_cited PubMed PubMed Finds PubMed Health systematic reviews that cite specified PubMed articles

  • term: Text query used to limit the set of unique identifiers (UIDs) returned, similar to the search string you would put into an Entrez database’s web interface. The linked UIDs will be checked against the results of this search, and only the UIDs for records which match the query will be returned. In essence, the set of UIDs that results from the link will be combined with the term query with a Boolean AND. This is especially useful for filtering the results of a link by a given criteria (e.g. date, publication type, etc.). All special characters must be URL encoded (a.k.a “percent encoded”); for more information on URL encoding, see W3Schools’ URL Encoding Reference page. Spaces may be replaced by ‘+’ signs. See the PubMed Help for information about search field descriptions and tags in PubMed.

  • holding: Name of a LinkOut provider. Only URLs for the LinkOut provider specified will be returned. The value you use for holding should be the LinkOut provider’s name abbreviation, found in the <NameAbbr> tag of the ELink XML output. Note that the holding parameter is only permitted when using command mode llinks or llinkslib.

ELink Date Filter Parameters

  • datetype (optional): If you wish to limit your retrieved links by date, this parameter determines which date field you wish to limit by. Available date types vary by output database (i.e. by which database you have specified in your db parameter). For PubMed, valid datetype values include:
    • crdt: Create Date (For records added after December 18, 2008, this is the date the citation was first added to PubMed. For more details, see the entry for “Create Date” in MEDLINE/PubMed Data Element (Field) Descriptions.)
    • edat: Entrez Date (For records added after October 9, 2008, this is the date the citation was added to PubMed, except for records added more than twelve months after the date of publication. For more details, see the entry for “Entrez Date” in MEDLINE/PubMed Data Element (Field) Descriptions.)
    • pdat: Publication Date (The article’s publication date.)
    • mhda: MeSH Date (The date the citation was indexed with MeSH. If the citation has not yet been indexed, this will be the same as the Entrez Date.)
      For more information on date types, see the Searching by date in the PubMed Help.
  • reldate (optional): Limit your retrieved links to only those items with a date within the last n days. This parameter uses the date field you specified in the datetype parameter.
  • mindate,maxdate (optional): Limit your retrieved links to a specific range of dates. You must include both a mindate and a maxdate to specify a date range. Dates can be formatted in the following options:
    • YYYY/MM/DD
    • YYYY/MM
    • YYYY

ELink Examples

EInfo

EInfo (einfo.fcgi) provides statistics for a single database including lists of indexing fields and available link names. EInfo can also provide a list of all Entrez databases.

EInfo Parameters

  • db: Which database you wish to retrieve statistics for. If the db parameter is omitted, EInfo will return a list of all of the Entrez databases. You can see NCBI’s table of Entrez Unique Identifiers (UIDs) for a complete list of allowable database names, but some example values include:
    • pubmed: PubMed
    • pmc: PubMed Central
    • nlmcatalog: NLM Catalog
  • version: EInfo returns statistics in two different XML schemas. If you omit the version parameter, the default schema is used. If you include the version parameter, the only supported value is 2.0. The 2.0 EInfo XML includes two extra fields:
    • <IsTruncatable>: Fields that are truncatable allow the wildcard character ‘*’ in terms. The wildcard character will expand to match any set of characters up to a limit of 600 unique expansions.
    • <IsRangeable>: Fields that are rangeable allow the range operator ‘:’ to be placed between a lower and upper limit for the desired range (e.g. 2008:2010[pdat]).
  • retmode: Determines the format of the returned output. The default value is xml, but json is also supported.

EInfo Examples

ESpell

ESpell (espell.fcgi) provides spelling suggestions for terms within a single text query in a given database.

ESpell Parameters

  • db (required): Which database your search is intended for. Each database provides different spelling suggestions, so you should use the database which you plan to search. You can see NCBI’s table of Entrez Unique Identifiers (UIDs) for a complete list of allowable database names, but some example values include:
    • pubmed: PubMed
    • pmc: PubMed Central
    • nlmcatalog: NLM Catalog
  • term (required): The text query you wish to spellcheck, similar to the search string you would put into an Entrez database’s web interface. All special characters must be URL encoded (a.k.a “percent encoded”); for more information on URL encoding, see W3Schools’ URL Encoding Reference page. Spaces may be replaced by ‘+’ signs. See the PubMed Help for information about search field descriptions and tags in PubMed.

ESpell Examples

ECitMatch

ECitMatch (ecitmatch.cgi) retrieves PubMed IDs (PMIDs) that correspond to a set of input citation strings. This is E-utilities version of the PubMed Batch Citation Matcher, and uses the same input format.

ECitMatch Parameters

  • db (required): Which database you wish to search. The only supported value is ‘pubmed’.

  • bdata (required): The citation strings for which you are attempting to retrieve PMIDs. Each citation you are trying to match must be listed in the following format:

    journal_title|year|volume|first_page|author_name|your_key|

    Multiple citation strings should be separated by a carriage return character (%0D). The your_key value is an arbitrary label that you can use to keep track of which citation is which, and will be included in the output. Be aware that all spaces must be replaced by ‘+’ symbols and that citation strings should end with a final vertical bar ‘|’.

    For more information on how to format these input strings, see the Batch Citation Matcher Help.

  • email: This parameter is recommended for all E-utilities URLs, but is especially useful with ECitMatch. If you specify an email but omit the retmode parameter, your results will be sent to the specified e-mail address, rather than displayed on the screen.

ECitMatch Examples

EGQuery

EGQuery (egquery.fcgi) allows you to search all Entrez databases for a single text query, and return the number of results that match that query in each database. Note: EGQuery does not return the matching UIDs from each database, only the number of results that match.

EGQuery Parameters

  • term (required): The text query you wish to search for, similar to the search string you would put into an Entrez database’s web interface. All special characters must be URL encoded (a.k.a “percent encoded”); for more information on URL encoding, see W3Schools’ URL Encoding Reference page. Spaces may be replaced by ‘+’ signs.

EGQuery Examples

Last Reviewed: July 30, 2021