Skip to content
Snippets Groups Projects

Parameters

Last edited by Andrew Yates

Parameters are ways for you the user to specify what is required from the REST API and influence the type of data returned from endpoints. They are split into two types: required parameters which should form the URL and optional parameters which should be passed in using HTTP key value parameters for GET requests or in a POST body.

A number of parameters are consistent in their definition and usage across multiple endpoints.

Common Parameters

id

Type Can be Required Description Example Example Endpoint
String Yes Indicates the use of a stable identifier within the scope of Ensembl (Ensembl assigned IDs, externally assigned IDs e.g. dbSNP rsIDs) in order to find information. Sometimes you will be required to combine ID with the species and db_type parameter when it is not possible to uniquely identify the source species from just an identifier ENSG00000157764, ENSGT00390000003602 sequence/id/:id

region

Type Can be Required Description Example Example Endpoint
String location Yes Locations are coordinates normally held on a genomic region of DNA e.g. chromosome or supercontig. By default they should specify the name of the region of DNA, a start, an end and an optional direction (expressed as 1/-1 to flag positive or negative strand). The strand, end and start can be omitted and are assumed to be positive, length of the region and 1 respectively. Endpoints which take in regions will have a maximum length they support. Check your endpoint's documentation X:1..10000 sequence/region/:species/:region

species

Type Can be Required Description Example Example Endpoint
String Yes Allows the specification of a species to retrieve information from. This can be the scientific name of the species or one of the common aliases for it. To check the available synonyms you should check the http://rest.ensembl.org/info/species.json endpoint. Each species entry lists a number of them under the aliases key. You can see the example output below. human, homo_sapiens, homo sequence/region/:species/:region 
[
    {
      "division":"Ensembl",
      "taxon_id":"9606",
      "name":"homo_sapiens",
      "release":75,
      "display_name":"Human",
      "accession":"GCA_000001405.14",
      "common_name":"human",
      "aliases":[
        "homo",
        "homo sapiens",
        "h_sapiens",
        "enshs",
        "human",
        "hsap",
        "9606",
        "homsap",
        "hsapiens"
      ],
      "groups":[
        "core",
        "cdna",
        "vega",
        "otherfeatures",
        "rnaseq",
        "variation",
        "funcgen"
      ],
      "assembly":"GRCh37"
    }
]

symbol

Type Can be Required Description Example Example Endpoint
String Yes A linked symbol can be one of 3 items. Firstly they are the names given to Ensembl entities such as a Gene. Secondly they can be synonyms of those names. Thirdly it can be any external reference linked to an entity. BRAF xrefs/symbol/:species/:symbol

external_db

Type Can be Required Description Example Example Endpoint
String Yes The same symbol can appear from multiple external resources. Specifying this parameter allows you to restrict the search to a single subset of databases. SQL style wildcards are supported HGNC, Uniprot% xrefs/symbol/:species/:symbol

object_type

Type Can be Required Description Example Example Endpoint
String Yes When specifying an ambiguous term such as a symbol it can be advantages to limit the search to a single object type. Gene lookup/symbol/:species/:symbol

callback

Type Can be Required Description Example Example Endpoint
String No Should be specified when using any endpoint and the requested output is in JSON-P. Please see our section on JSON-P for more information randomname -