GeneBe API: Annotating Genetic Variants Made Easy
This page briefly describes the GeneBe API, which can be utilized for various purposes:- If you need to annotate a VCF or JSON file using the API, we recommend using the Python client available at https://pygenebe.readthedocs.io/en/latest/ .
- If you intend to annotate variants in a Python script, such as with Pandas, we suggest using the Python library also accessible at https://pygenebe.readthedocs.io/en/latest/ .
- For other specific requirements, you may opt to generate a client yourself by referring to the Open API documentation at https://api.genebe.net/cloud/gb-api-doc/swagger-ui/index.html .
We encourage you to review the brief description below, which outlines the main endpoints.
Introduction
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. Client can be used as a library for variant annotation as well as a standalone commandline program for VCF and JSON files annotation. Find out documentation on https://pygenebe.readthedocs.io/en/latest/ and check usage examples here https://github.com/pstawinski/pygenebe/tree/main/examples.Install it with ease by running:
pip install genebeAnd then, in your Python script, run the following to obtain annotated variants in a Pandas DataFrame::
import genebe as gnb
input_variants = ['7-69599651-A-G']
df = gnb.annotate_variants_list_to_dataframe(input_variants, flatten_consequences=True)Find out more in the documentation at https://pygenebe.readthedocs.io/en/latest/ .
API Limits and Registration
GeneBe enforces daily query limits per IP address. To access more queries, it's recommended to:- Register an account on GeneBe.
- Create an API key on your profile page.
- 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.184Other 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.