omnilab/ncbi API reference

Omnilab\Ncbi

NcbiSource class

final class NcbiSource extends HttpSource NcbiSource.php:33

NCBI Gene and NCBI Taxonomy: a gene by its GeneID - its symbol, name, organism, place on the genome, summary, its UniProt and Ensembl ids - and a taxon by its id or a name - its scientific name, rank, lineage, common name and GBIF key; a search of either.

The records come from NCBI Datasets v2 (api.ncbi.nlm.nih.gov/datasets/v2), whose reports carry what E-utilities' summaries do not (a gene's UniProt and Ensembl ids, a taxon's ranked lineage and its links to GBIF); the search from E-utilities' esearch (eutils.ncbi.nlm.nih.gov), Entrez's text search, which Datasets has not. An API key raises NCBI's limit from three calls a second (E-utilities; five for Datasets) to ten: the source leaves 0.34 s between two without one, 0.1 s with one.

const BASE_URI = 'https://api.ncbi.nlm.nih.gov/datasets/v2/'

const EUTILS_URI = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/'

const MAX_PER_PAGE = 100

The most records one search page is asked for.

NcbiSource::__construct()

public function __construct(HttpClientInterface $http, readonly ?string $apiKey = null, readonly ?string $email = null, readonly string $tool = 'omnilab', readonly bool $links = true, readonly int $synonyms = 20, string $baseUri = self::BASE_URI, readonly string $eutilsUri = self::EUTILS_URI, array $headers = [], ?float $throttle = null)

$apiKey

an NCBI API key (account settings at ncbi.nlm.nih.gov): ten calls a second instead of three

$email

sent to E-utilities with the tool's name, as NCBI asks: whom it writes to before it blocks a caller

$links

whether a taxon's external links are read (one call more): its GBIF key

NcbiSource::getName()

public function getName(): string

NcbiSource::capabilities()

public function capabilities(): array

NcbiSource::entity()

public function entity(Identifier|string $id): ?Entity

A gene by its GeneID (an Identifier of ncbi.gene, "gene:3043", "ncbigene:3043", its page, or a bare number), a taxon by its id (an Identifier of ncbi.taxon, "txid9689", "taxonomy:9689", its page) or by a name, scientific or common ("Panthera leo", "lion").

NcbiSource::search()

public function search(Query $query): Page

Entrez's search (esearch) of NCBI Gene, or of NCBI Taxonomy for the taxonomy domain, the text in Entrez's syntax ("HBB AND human[orgn]", "Panthera[subtree]"), in Entrez's order; then the page's records from Datasets, in one call.

NcbiSourceFactory class

final class NcbiSourceFactory extends SourceFactory NcbiSourceFactory.php:24

NCBI Gene and NCBI Taxonomy, through NCBI Datasets v2 and E-utilities - no key needed, an API key for ten calls a second instead of three.

options: mailto: 'support@glitchr.io' # E-utilities' "email" and the User-Agent: whom NCBI writes to before it blocks a caller api_key: '...' # an NCBI API key (ncbi.nlm.nih.gov, account settings) tool: 'omnilab' # E-utilities' "tool": the name NCBI knows the application by links: true # read a taxon's external links (one call more): its GBIF key synonyms: 20 # how many of a gene's other names to keep (0: none) throttle: auto # seconds between two calls; auto: 0.34 without a key, 0.1 with one base_uri: 'https://api.ncbi.nlm.nih.gov/datasets/v2/' eutils_uri: 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/'

Options