entrezpy.esearch.esearcher.Esearcher implements the E-Utility ESearch [0]. Esearcher queries return UIDs for data in the requested Entrez database or WebEnv/QueryKey references from the Entrez History server.


import entrezpy.esearch.esearcher
import entrezpy.log.logger

e = entrezpy.esearch.esearcher.Esearcher("entrezpy",
analyzer = e.inquire({'db' : 'pubmed',
                      'term' : 'viruses[orgn]',
                      'retmax' : '20',
                      'rettype' : 'uilist'})
print(analyzer.result.count, analyzer.result.uids)

This creates an Esearcher instance with the following parameters:



param str tool:String with no internal spaces uniquely identifying the software producing the request, i.e. your tool/pipeline.
param str email:
 A complete and valid e-mail address of the software developer and not that of a third-party end user. entrezpy is a library, not a tool.
param str apikey:
param str apikey_var:
 Environment variable storing an NCBI API key
param int threads:
 Number of threads (not processors)
param str qid:Unique Esearch query id. Will be generated if not given.

Supported E-Utility parameter

Parameters are passed as dictionary to entrezpy.esearch.esearcher.Esearcher.inquire() and are expected to be the same as those for the E-Utility [0]. For example:

{'db' : 'nucleotide', 'term' : 'viruses[orgn]', 'reqsize' : 100, 'retmax' : 99, 'idtype' : 'acc'}

Esearcher introduces one additional parameter reqsize. It sets the size of a request. Numbers grater than the maximum allowed by NCBI will be set to the maximum.

Parameter   Type
db str
WebEnv str
query_key int
uilist bool
retmax int
retstart int
usehistory bool
term str
sort str
field str
reldate int
datetype str (YYYY/MM/DD, YYYY/MM, YYYY)
mindate str (YYYY/MM/DD, YYYY/MM, YYYY)
maxdate str (YYYY/MM/DD, YYYY/MM, YYYY)
idtype bool
retmode `json, enforced by Esearcher
Esearcher reqsize int


Instance of entrezpy.esearch.esearch_result.EsearchResult.

If retmax = 0 or retmode = count no UIDs are returned. If usehistory is True (default), WebEnv and query_key for the request is returned.

  • count : number of found UIDs for request
  • retmax : number of UIDs to retrieve
  • retstart : number of first UID to retrieve
  • uids : list of fetched UIDs


  1. Parameters are checked and the request size is configured
  2. Initial search is requested
  3. If more search requests are required, Parameter is adjusted and the remaining requests are done
  4. If no errors were encountered, returns the analyzer with the result for all requests