The COVID-19 Beacon API enables the search query across the COVID-19 genome sequences from India. The notion behind creating the Beacon API is to make the genomic data discoverable for the research and clinical purpose in the public domain that will help in understanding the spread and control of the new coronavirus.
The COVID-19 Beacon API allows the user to search queries related to the presence or absence of specific variants and lineages in a given dataset. The Beacon API has one endpoint: /beacon; query interface is provided by the beacon endpoint. The beacon API specification is written in OpenAPI. It uses JSON in requests and responses and standard HTTPS for information transfer.
This document also describes the Beacon API in detail and provides information on the specific endpoints, request formats, and response.
Version : 1.0.0
| Parameter (* mandatory, one of these is mandatory) | Description | Type | Example |
|---|---|---|---|
| startDate | Minimum Date(ISO 8601 format). | string | 2020-04-01 |
| endDate | Maximum Date(ISO 8601 format). | string | 2021-07-01 |
| lineage | Pangolin Lineage | string | B.1 |
| state | Because state names represent specific places, they are always capitalized | string | Maharashtra |
| mutation | Gene:Mutation | string | ORF1a:F924F |
Content-type:application/json
Payload: Beacon Response object
| Properties | Description | Type | Example |
|---|---|---|---|
| beaconId | Identifier of the beacon, as defined in Beacon | string | |
| apiVersion | Version of the API. | string | 1.0.0 |
| exists | Indicator of whether the given query was observed in the dataset queried. This should be non-null, unless there was an error, in which case error has to be non-null. | string | TRUE |
| updatedDate | The time the dataset was updated in (ISO 8601 format). | string | "2021-07-20" |
| requestParameter | The request that is sent to the Beacon. | object | BeaconRequest Object |
| datasetResponses | The response that the user receives from the Beacon | object | BeaconDatasetResponse Object |
| error | The error message and the appropriate HTTP status code | object | null |
| Properties | Description | Type | Example |
|---|---|---|---|
| exists | Indicator of whether the given query was observed in the dataset. This should be non-null, unless there was an error, in which case error has to be non-null. | boolean | TRUE |
| error | The error message and the appropriate HTTP status code | object | null |
| Lineage Count | Indicates the count of per Lineage | object | "B.1": 257 |
| States Count | Indicates the count of per Lineage | object | "Maharashtra": 257 |
A GET request like this:
{
"beaconId": "covid19-genome-surveillance-beacon",
"apiVersion": "1.0.0",
"exists": true,
"error": null,
"updatedDate": "2021-07-30",
"requestParameters": {
"startDate": "2020-04-01",
"endDate": "2021-07-01",
"lineage": "B.1",
"state": "Maharashtra",
"mutation": "ORF1a:F924F",
"includeDatasetResponses": "ALL"
},
"datasetResponses": {
"exists": true,
"lineageCount": {
"B.1": 257
},
"statesCount": {
"Maharashtra": 257
},
"error": null
}
}
{
...,
"datasetResponses": null
}