Skip to content
Docs

beacon_operations.get_search

GET
/g_variants

Search for variants

Parameters

Query Parameters

skip
  • In the request: number of pages to skip * In the response: number of pages that has been skipped
integer
0
limit

Size of the page. Use 0 to return all the results or the maximum allowed by the Beacon, if there is any.

integer
default: 10 
10
includeResultsetResponses

Indicator of whether responses from every Resultset should be included in the response to this request or just the ones with positive, negative results or no details at all. If null (not specified), the default value of ‘HIT’ is assumed. This parameter allows for returning boolean/counting results although the Beacon instance is capable to return record level details.

string
default: HIT
Allowed values: ALL HIT MISS NONE
start
integer
end
integer
assemblyId
string
referenceName
string
referenceBases
string
alternateBases
string
variantMinLength
integer format: int64
variantMaxLength
integer format: int64
allele
string
Example
NM_004006.2:c.4375C>T
geneId
string
Example
BRAF
filters
Array<string>

Responses

200

Successful operation.

One of:

Complete definition for a minimal response that provides only a Boolean exists true|false answer.

object
beaconHandovers

Set of handovers to be added in one section the response.

Array<object>

A handover is a typed link for attaching actionable links to results, non purely informational, requests. The goal of the handovers is to list the different actions available, e.g.:

  • a link to a request access page * linking to a file for download, e.g. a VCF file Another common scenario is to provide a fast summary response (e.g. BeconCountResponse) and to provide access to different endpoints for the entities matched by the query using temporary access tokens in the handover URLs.
object
handoverType
required

In our context, only htsget urls should be returned

object
id
string
Allowed values: CUSTOM
label
string
Allowed values: HTSGET
note

An optional text including considerations on the handover link provided.

string
This handover link provides access to a summarized VCF.
url
required

URL endpoint to where the handover process could progress, in RFC3986 format

string format: uri 
https://api.mygenomeservice.org/Handover/9dcc48d7-fc88-11e8-9110-b0c592dbf8c0/
info

Placeholder to allow the Beacon to return any additional information that is necessary or could be of interest in relation to the query or the entry returned. It is recommended to encapsulate additional informations in this attribute instead of directly adding attributes at the same level than the others in order to avoid collision in the names of attributes in future versions of the specification.

object
meta
required

Information about the response that could be relevant for the Beacon client in order to interpret the results.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
beaconId
required

The Id of a Beacon. Usually a reversed domain string, but any URI is acceptable. The purpose of this attribute is, in the context of a Beacon network, to disambiguate responses coming from different Beacons.

string
receivedRequestSummary
required

Section of the response that summarize the request received as it has been interpreted by the Beacon server. This summary can help to identify differences between the incoming request and its interpretation or processing, e.g. in the response granularity or pagination. The required properties include those that should be part of every request.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
requestedSchemas
required

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string
filters

Ontology based filters. A CURIE syntax is encouraged to be used.

Array<string>
[
  "BTO:0000199",
  "PATO:0000383"
]
requestParameters
object
alternateBases

Alternate bases for this variant (starting from start). * Accepted values: [ACGTN]* * N is a wildcard, that denotes the position of any base, and can be used as a standalone base of any type or within a partially known sequence. As example, a query of ANNT the Ns can take take any form of [ACGT] and will match ANNT, ACNT, ACCT, ACGT … and so forth.

  • an empty value is used in the case of deletions with the maximally trimmed, deleted sequence being indicated in ReferenceBases
  • Categorical variant queries, e.g. such not being represented through sequence & position, make use of the variantType parameter.
  • either alternateBases or variantType is required.
string
/^([ACGTUNRYSWKMBDHV\-\.]*)$/
aminoacidChange

Aminoacid alteration of interest. Format 1 letter, e.g. “V600E”

string
assemblyId

Genomic assembly accession and version as RefSqeq assembly accession (e.g. “GCF_000001405.39”) or a versioned assembly name or synonym such as UCSC Genome Browser assembly (e.g. “hg38”) or Genome Reference Consortium Human (e.g. “GRCh38.p13”) names.

string
default: hg38 
[
  "GCF_000001405.39",
  "hg38",
  "GRCh38.p13"
]
end

Precise or bracketing the end of the variants of interest: * (0-based, exclusive) - see start * for bracket queries, provide 2 values (e.g. [111,222]).”

Array<integer>
<= 2 items
geneId
string
genomicAlleleShortForm

HGVSId descriptor, e.g. NC_000017.11:g.43057063G>A

string
referenceBases

Reference bases for this variant (starting from start). * Accepted values: [ACGTN]* * N is a wildcard, that denotes the position of any base, and can be used as a standalone base of any type or within a partially known sequence. As example, a query of ANNT the Ns can take take any form of [ACGT] and will match ANNT, ACNT, ACCT, ACGT … and so forth.

  • an empty value is used in the case of insertions with the maximally trimmed, inserted sequence being indicated in AlternateBases
string
/^([ACGTUNRYSWKMBDHV\-\.]*)$/
referenceName

Reference sequence id for genomic reference sequence in which variant coordinates are given, e.g. “refseq:NC_000009.12” for human chromosome 9 in the GRCh38 assembly. The use of the assembly specific RefSeqId is recommended although alternatively names, synonymous or aliases e.g. “chr9” could be used in conjunction with an Assembly parameter.

string
[
  "refseq:NC_000009.12",
  "chr9",
  "NC_012920.1"
]
start

Precise or fuzzy start coordinate position(s), allele locus (0-based, inclusive). * start only:

  • for single positions, e.g. the start of a specified sequence alteration where the size is given through the specified alternateBases
  • typical use are queries for SNV and small InDels
  • the use of start without an end parameter requires the use of alternateBases
  • start and end:
    • for searching any variant falling fully or partially within the range between start and end (a.k.a. “range query”)
    • additional use of variantType OR alternateBases can limit the scope of the query
    • by convention, partial overlaps of variants with the indicated genomic range are accepted; for specific overlap requirements the 4-parameter “Bracket Queries” should be employed
  • 2 values in both start and end for constructing a “Bracket Query”:
    • can be used to match any contiguous genomic interval, e.g. for querying imprecise positions
    • identifies all structural variants starting between start[0] and start[1], and ending between end[0] <-> end[1]
    • single or double sided precise matches can be achieved by setting start[1]=start[0]+1 and end[1]=end[0]+1
Array<integer>
>= 1 items <= 2 items
variantMaxLength
  • Maximum length in bases of a genomic variant. * This is an optional parameter without prescribed use. While a length is commonly available for structural variants such as copy number variations, it is recommended that length based queries should also be supported for variants with indicated referenceBases and alternateBases, to enable length-specific wildcard queries.
integer format: int64
>= 1
variantMinLength
  • Minimum length in bases of a genomic variant * This is an optional parameter without prescribed use. While a length is commonly available for structural variants such as copy number variations, it is recommended that length based queries should also be supported for variants with indicated referenceBases and alternateBases, to enable length-specific wildcard queries.
integer format: int64
variantType

The variantType is used to query variants which are not defined through a sequence of one or more bases using the alternateBases parameter. Examples here are e.g. structural variants: * DUP

  • increased allelic count of material from the genomic region between start and end positions
  • no assumption about the placement of the additional sequences is being made (i.e. no in situ requirement as tandem duplications)
  • DEL: deletion of sequence following start The Beacon model is not prescriptive with regard to the values allowed for variantType with use of extended types (such as from EFO:0030063) being possible. However, a support for the basic CNV types above - where represented in the data - is recommended. Either alternateBases or variantType is required, with the exception of range queries (single start and end parameters).
string
includeResultsetResponses

Indicator of whether responses from every Resultset should be included in the response to this request or just the ones with positive, negative results or no details at all. If null (not specified), the default value of ‘HIT’ is assumed. This parameter allows for returning boolean/counting results although the Beacon instance is capable to return record level details.

string
default: HIT
Allowed values: ALL HIT MISS NONE
pagination
required

Pagination to apply or that has been applied on the results.

object
currentPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
limit

Size of the page. Use 0 to return all the results or the maximum allowed by the Beacon, if there is any.

integer
default: 10 
10
nextPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
previousPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
skip
  • In the request: number of pages to skip * In the response: number of pages that has been skipped
integer
0
requestedGranularity
required

Level of detail of the response:

  • boolean: returns true/false’ responses * count: adds the total number of positive results found * aggregated: returns summary, aggregated or distribution like responses * record: returns details for every row. In cases where a Beacon prefers to return records with fewer than allattributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count aggregated record
testMode

Used for indicating that a request or response is done in a test context e.g. for compliance testing i.e. to evaluate the acceptance/understanding of a request and the structure of the returned response by the Beacon instance. A TRUE testMode parameter DOES NOT require that the Beacon instance is a test instance, but that this specific request-response cycle is a testing one. When true the Beacon instance MUST respond the request but it SHOULD use virtual or non-sensitive data. Here, what is being evaluated is the acceptance/understanding of a request and the structure of the returned response by the Beacon instance.

boolean
returnedGranularity
required

Level of detail of the response:

  • boolean: returns true/false’ responses * count: adds the total number of positive results found * aggregated: returns summary, aggregated or distribution like responses * record: returns details for every row. In cases where a Beacon prefers to return records with fewer than allattributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count aggregated record
returnedSchemas
required

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string
testMode

Used for indicating that a request or response is done in a test context e.g. for compliance testing i.e. to evaluate the acceptance/understanding of a request and the structure of the returned response by the Beacon instance. A TRUE testMode parameter DOES NOT require that the Beacon instance is a test instance, but that this specific request-response cycle is a testing one. When true the Beacon instance MUST respond the request but it SHOULD use virtual or non-sensitive data. Here, what is being evaluated is the acceptance/understanding of a request and the structure of the returned response by the Beacon instance.

boolean
responseSummary
required

Boolean (true/false) response section.

object
exists
required

Indicator of whether any record was observed in any of the collections queried. This should be non-null.

boolean

default

An unsuccessful operation.

object
error
required

Beacon-specific error.

object
errorCode
required

Entry not found

integer format: int32
errorMessage
string
meta
required

Information about the response that could be relevant for the Beacon client in order to interpret the results.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
beaconId
required

The Id of a Beacon. Usually a reversed domain string, but any URI is acceptable. The purpose of this attribute is, in the context of a Beacon network, to disambiguate responses coming from different Beacons.

string
receivedRequestSummary
required

Section of the response that summarize the request received as it has been interpreted by the Beacon server. This summary can help to identify differences between the incoming request and its interpretation or processing, e.g. in the response granularity or pagination. The required properties include those that should be part of every request.

object
apiVersion
required

Version of API, e.g. in request or response. Beacon uses a Github-style, “v”-prefixed semantic versioning format.

string
requestedSchemas
required

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string
filters

Ontology based filters. A CURIE syntax is encouraged to be used.

Array<string>
[
  "BTO:0000199",
  "PATO:0000383"
]
requestParameters
object
alternateBases

Alternate bases for this variant (starting from start). * Accepted values: [ACGTN]* * N is a wildcard, that denotes the position of any base, and can be used as a standalone base of any type or within a partially known sequence. As example, a query of ANNT the Ns can take take any form of [ACGT] and will match ANNT, ACNT, ACCT, ACGT … and so forth.

  • an empty value is used in the case of deletions with the maximally trimmed, deleted sequence being indicated in ReferenceBases
  • Categorical variant queries, e.g. such not being represented through sequence & position, make use of the variantType parameter.
  • either alternateBases or variantType is required.
string
/^([ACGTUNRYSWKMBDHV\-\.]*)$/
aminoacidChange

Aminoacid alteration of interest. Format 1 letter, e.g. “V600E”

string
assemblyId

Genomic assembly accession and version as RefSqeq assembly accession (e.g. “GCF_000001405.39”) or a versioned assembly name or synonym such as UCSC Genome Browser assembly (e.g. “hg38”) or Genome Reference Consortium Human (e.g. “GRCh38.p13”) names.

string
default: hg38 
[
  "GCF_000001405.39",
  "hg38",
  "GRCh38.p13"
]
end

Precise or bracketing the end of the variants of interest: * (0-based, exclusive) - see start * for bracket queries, provide 2 values (e.g. [111,222]).”

Array<integer>
<= 2 items
geneId
string
genomicAlleleShortForm

HGVSId descriptor, e.g. NC_000017.11:g.43057063G>A

string
referenceBases

Reference bases for this variant (starting from start). * Accepted values: [ACGTN]* * N is a wildcard, that denotes the position of any base, and can be used as a standalone base of any type or within a partially known sequence. As example, a query of ANNT the Ns can take take any form of [ACGT] and will match ANNT, ACNT, ACCT, ACGT … and so forth.

  • an empty value is used in the case of insertions with the maximally trimmed, inserted sequence being indicated in AlternateBases
string
/^([ACGTUNRYSWKMBDHV\-\.]*)$/
referenceName

Reference sequence id for genomic reference sequence in which variant coordinates are given, e.g. “refseq:NC_000009.12” for human chromosome 9 in the GRCh38 assembly. The use of the assembly specific RefSeqId is recommended although alternatively names, synonymous or aliases e.g. “chr9” could be used in conjunction with an Assembly parameter.

string
[
  "refseq:NC_000009.12",
  "chr9",
  "NC_012920.1"
]
start

Precise or fuzzy start coordinate position(s), allele locus (0-based, inclusive). * start only:

  • for single positions, e.g. the start of a specified sequence alteration where the size is given through the specified alternateBases
  • typical use are queries for SNV and small InDels
  • the use of start without an end parameter requires the use of alternateBases
  • start and end:
    • for searching any variant falling fully or partially within the range between start and end (a.k.a. “range query”)
    • additional use of variantType OR alternateBases can limit the scope of the query
    • by convention, partial overlaps of variants with the indicated genomic range are accepted; for specific overlap requirements the 4-parameter “Bracket Queries” should be employed
  • 2 values in both start and end for constructing a “Bracket Query”:
    • can be used to match any contiguous genomic interval, e.g. for querying imprecise positions
    • identifies all structural variants starting between start[0] and start[1], and ending between end[0] <-> end[1]
    • single or double sided precise matches can be achieved by setting start[1]=start[0]+1 and end[1]=end[0]+1
Array<integer>
>= 1 items <= 2 items
variantMaxLength
  • Maximum length in bases of a genomic variant. * This is an optional parameter without prescribed use. While a length is commonly available for structural variants such as copy number variations, it is recommended that length based queries should also be supported for variants with indicated referenceBases and alternateBases, to enable length-specific wildcard queries.
integer format: int64
>= 1
variantMinLength
  • Minimum length in bases of a genomic variant * This is an optional parameter without prescribed use. While a length is commonly available for structural variants such as copy number variations, it is recommended that length based queries should also be supported for variants with indicated referenceBases and alternateBases, to enable length-specific wildcard queries.
integer format: int64
variantType

The variantType is used to query variants which are not defined through a sequence of one or more bases using the alternateBases parameter. Examples here are e.g. structural variants: * DUP

  • increased allelic count of material from the genomic region between start and end positions
  • no assumption about the placement of the additional sequences is being made (i.e. no in situ requirement as tandem duplications)
  • DEL: deletion of sequence following start The Beacon model is not prescriptive with regard to the values allowed for variantType with use of extended types (such as from EFO:0030063) being possible. However, a support for the basic CNV types above - where represented in the data - is recommended. Either alternateBases or variantType is required, with the exception of range queries (single start and end parameters).
string
includeResultsetResponses

Indicator of whether responses from every Resultset should be included in the response to this request or just the ones with positive, negative results or no details at all. If null (not specified), the default value of ‘HIT’ is assumed. This parameter allows for returning boolean/counting results although the Beacon instance is capable to return record level details.

string
default: HIT
Allowed values: ALL HIT MISS NONE
pagination
required

Pagination to apply or that has been applied on the results.

object
currentPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
limit

Size of the page. Use 0 to return all the results or the maximum allowed by the Beacon, if there is any.

integer
default: 10 
10
nextPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
previousPage

A hash or similar that allows the server to retrieve a “page”, e.g. (a subset of) a query response.

string
ab0sc&fe1dd
skip
  • In the request: number of pages to skip * In the response: number of pages that has been skipped
integer
0
requestedGranularity
required

Level of detail of the response:

  • boolean: returns true/false’ responses * count: adds the total number of positive results found * aggregated: returns summary, aggregated or distribution like responses * record: returns details for every row. In cases where a Beacon prefers to return records with fewer than allattributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count aggregated record
testMode

Used for indicating that a request or response is done in a test context e.g. for compliance testing i.e. to evaluate the acceptance/understanding of a request and the structure of the returned response by the Beacon instance. A TRUE testMode parameter DOES NOT require that the Beacon instance is a test instance, but that this specific request-response cycle is a testing one. When true the Beacon instance MUST respond the request but it SHOULD use virtual or non-sensitive data. Here, what is being evaluated is the acceptance/understanding of a request and the structure of the returned response by the Beacon instance.

boolean
returnedGranularity
required

Level of detail of the response:

  • boolean: returns true/false’ responses * count: adds the total number of positive results found * aggregated: returns summary, aggregated or distribution like responses * record: returns details for every row. In cases where a Beacon prefers to return records with fewer than allattributes, different strategies have to be considered w/o adding them to the current design, e.g.:
    • keeping non-mandatory attributes empty
    • Beacon to provide a minimal record definition
string
default: boolean
Allowed values: boolean count aggregated record
returnedSchemas
required

Set of schemas to be used in the response to a request.

Array<object>

Schema to be used for the requested entry type in the response.

object
entityType
string
Individual
schema
string
testMode

Used for indicating that a request or response is done in a test context e.g. for compliance testing i.e. to evaluate the acceptance/understanding of a request and the structure of the returned response by the Beacon instance. A TRUE testMode parameter DOES NOT require that the Beacon instance is a test instance, but that this specific request-response cycle is a testing one. When true the Beacon instance MUST respond the request but it SHOULD use virtual or non-sensitive data. Here, what is being evaluated is the acceptance/understanding of a request and the structure of the returned response by the Beacon instance.

boolean