Parameters

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
• region
• species
• symbol
• external_db
• object_type
• callback

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	-