GeneBe API: Annotating Genetic Variants Made Easy

GeneBe provides a user-friendly API for genetic variant annotation. You can use one of two key endpoints: a GET query for single variant annotation and a POST query for batch annotation. We'll explore the details of this API, its advantages, and how to use it effectively.

Endpoints for Genetic Variant Annotation

GET Endpoint for Single Variant (/api-public/v1/variant)

Ideal for individual variant annotation.
Example Usage without Logging In:

curl -X 'GET' \
'https://api.genebe.net/cloud/api-public/v1/variant?chr=6&pos=160585140&ref=T&alt=G&genome=hg38' \
-H 'Accept: application/json'

You can easily see the results in browser: https://api.genebe.net/cloud/api-public/v1/variant?chr=6&pos=160585140&ref=T&alt=G&genome=hg38
Example Usage with an API key:

curl -X 'GET' -u YOUR_EMAIL:YOUR_API_KEY \
'https://api.genebe.net/cloud/api-public/v1/variant?chr=6&pos=160585140&ref=T&alt=G&genome=hg38' \
-H 'Accept: application/json'

POST Endpoint for Batch Annotation (/api-public/v1/variants)

If you need to annotate multiple variants it is recommended to use POST endpoint. It works with multiple variants in batches (up to 1000).
Example Usage Without Logging In:

curl -X 'POST' \
'https://api.genebe.net/cloud/api-public/v1/variants?genome=hg38' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '[{"chr":"22", "pos":28695868, "ref":"AG", "alt":"A"}]'

Example Usage with an API key:

curl -X 'POST' -u YOUR_EMAIL:YOUR_API_KEY \
'https://api.genebe.net/cloud/api-public/v1/variants?genome=hg38' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '[{"chr":"22", "pos":28695868, "ref":"AG", "alt":"A"}]'

GeneBe python client

There is an experimental python API client, available on PyPI. Install it with ease by running:

pip install genebe

And then, in your Python script, run the following to obtain annotated variants in a Pandas DataFrame::

import genebe as gb
input_variants = ['7-69599651-A-G']
df = gb.annotate_variants_list_to_dataframe(input_variants, flatten_consequences=True)

API Limits and Registration

GeneBe enforces daily query limits per IP address. To access more queries, it's recommended to:

1. Register an account on GeneBe.
2. Create an API key on your profile page.
3. Use Basic Authorization with your email as the username and the API key as the password in your API requests.

You can always see the number of requests you've made by checking header Gb-Requests in API response. For example

Requests 3 for ip#148.211.51.184

means that you are unlogged (not using an API key, so requests counts per IP, not per user), and you've made 3 requests already.
Other way to check your Account plan and number of requests you have made is to check the whoami endpoint:

curl -X 'GET' \
  'https://api.genebe.net/cloud/api-public/v1/whoami' \
  -H 'accept: */*'

Or just visit https://api.genebe.net/cloud/api-public/v1/whoami.
If you require annotation for hundreds of thousands of variants daily, please contact us.

Detailed documentation

For more comprehensive information, you can refer to the automatically generated GeneBe Rest API documentation .