General URL, sections in braces are the parameters, so they are variables:

domain/api/{version}/{species}/{category}/{subcategory}/ id /{resource|action}?{filters|extra-options}

All sections in URL must be in lower case!


Public and privates version must exist. Versions are numbered as v1, v2, v3, ... In private versions a user and password will be needed to be passed as an extra-option.


For the beginning human, mouse and rat must be available: hsa, mu, rat, ... Short 3 letter code and common name must be accepted, i.e.:

domain/api/v1/ hsa /genomic/region/3:1000-200000/gene

must give the same result than:

domain/api/v1/ human /genomic/region/3:1000-200000/gene

Category and subcategory

There are 5 main categories:

  • genomic: region, cytoband, position, ... more
  • feature: gene, snp, transcript, protein, ... more
  • funcgen: pathwat and annotation more
  • regulatory: tfbs, mirna, ... more
  • xref: id more
  • DEPRECATED: annotation: go, interpro, ...
  • DEPRECATED: pathway: reactome, kegg, ... more
  • DEPRECATED: variation: snp, mutation, ... moved to feature

Subcategories should specify the type of the id field. Subcategories can be different for each category.

Id field

It's the query parameter, it's the feature about we want to retrieve the information (resource or action). Its type must be specified by the subcategory

NOTE: in order to improve performance, id lists can be passed together in only one connection separated by commas. Only 200 ids are allowed, i.e.:


Resources and actions

Each Category and Subcategory can have different resources and actions, i.e.:

domain/api/v1/hsa/core/gene/brca2/ exon
domain/api/v1/hsa/genomic/region/3:1000-200000/ gene
domain/api/v1/hsa/genomic/region/3:1000-200000/ snp

Resources and action must always be in singular

Filters and extra-options

General options, all of them are optionals:

  • output: text, json, zip. By default: text
  • separator: the character to separate column sin results. By default: tab
  • user: in case of private version
  • password: in case of private version

Specific options:

Every resource or action may have different filters or option, i.e.:

domain/api/v1/hsa/genomic/region/3:1000-200000/gene? biotype=protein_coding,mirna_gene
domain/api/v1/hsa/genomic/region/3:1000-200000/snp? consequence_type=non_synonymous_coding,splice_site

Some exceptions

URL pattern can have other pattern for those cases in which we want to retrieve general information no resource specific, i.e.:

domain/api/v1/hsa/genomic/region/ list

In this case we will get the list of chromosomes for that species.

Tech. specifications