ESearch Entrez Utility

ESearch
Last updated: December 17, 2008

ESearch: Searches and retrieves primary IDs (for use in EFetch, ELink and ESummary) and term translations, and optionally retains results for future use in the user's environment.

URL Parameters

Database
History Web Environment Query_key Tool E-mailAddress

User System Requirements
Entrez DTDs
Demonstration Program
Announcement Mailing List
Help Desk

Base URL: http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?

URL parameters: (Note: utility parameters may be case sensitive. Use lower case characters in all parameters except for WebEnv.

Database:

db=database name

Entrez database values available from EInfo PubMed is the default db.

History: Requests utility to maintain results in user's environment. Used in conjunction with WebEnv.

usehistory=y

Web Environment: Value previously returned in XML results from ESearch or EPost. This value may change with each utility call. If WebEnv is used, History search numbers can be included in an ESummary URL, e.g., term=cancer+AND+%23X (where %23 replaces # and X is the History search number).

WebEnv=WgHmIcDG]B etc.

Query_key: The value used for a history search number or previously returned in XML results from ESearch or EPost.

query_key=6

Note: WebEnv is similar to the cookie that is set on a user's computers when accessing PubMed on the web. If the parameter usehistory=y is included in an ESearch URL both a WebEnv (cookie string) and query_key (history number) values will be returned in the results. Rather then using the retrieved PMIDs in an ESummary or EFetch URL you may simply use the WebEnv and query_key values to retrieve the records. WebEnv will change for each ESearch query, but a sample URL would be as follows:

http://www.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed
&WebEnv=%3D%5DzU%5D%3FIJIj%3CC%5E%5DA%3CT%5DEACgdn%3DF%5E%3Eh
GFA%5D%3CIFKGCbQkA%5E_hDFiFd%5C%3D
&query_key=6&retmode=html&rettype=medline&retmax=15

Tool: A string with no internal spaces that identifies the resource which is using Entrez links (e.g., tool=flybase). This argument is used to help NCBI provide better service to third parties generating Entrez queries from programs. As with any query system, it is sometimes possible to ask the same question different ways, with different effects on performance. NCBI requests that developers sending batch requests include a constant 'tool' argument for all requests using the utilities.

tool=

E-mail Address: If you choose to provide an email address, we will use it to contact you if there are problems with your queries or if we are changing software interfaces that might specifically affect your requests. If you choose not to include an email address we cannot provide specific help to you, but you can still sign up for utilities-announce to receive general announcements.

email=

PubMed:

Search terms: This command uses search terms or phrases with or without Boolean operators. See the PubMed or Entrez help for information about search field descriptions and tags. Search fields and tags are database specific.

term=search strategy

For example:

term=asthma[mh]+OR+hay+fever[mh]

You may also tag search terms using field=tag.

Search Field: Use this command to specify a specific search field.

field=

PubMed fields: affl, auth, ecno, jour, iss, mesh, majr, mhda, page, pdat, ptyp, si, subs, subh, tiab, word, titl, lang, uid, fltr, vol

Relative Dates: Limit items a number of days immediately preceding today's date.

reldate=

For example:

Date Ranges: Limit results bounded by two specific dates. Both mindate and maxdate are required if date range limits are applied using these variables.

mindate=
maxdate=

For example:

Date Type: Limit dates to a specific date field based on database.

datetype=

For example:

datetype=edat

Display Numbers:

retstart=x (x= sequential number of the first record retrieved - default=0 which will retrieve the first record)
retmax=y (y= number of items retrieved)

Retrieval Mode:

retmode=xml

Use your web browser's View Page Source function to display results. Results are only available in XML; use in conjunction with Web Environment and EFetch to display data in text format.

Retrieval Type: