GI-DB API
Programmatic access to Genome India variant frequency data. Query by gene symbol or genomic location and receive JSON responses with main population frequency data.
Rate Limits & Constraints
- 100 requests per day per IP address (resets at midnight UTC)
- Gene query: Maximum 5 genes per request
- Location query: Maximum 20 locations per request (batch), each region max 100 kb
- Returns main frequency data only (no sub-population breakdown)
- Maximum 5,000 variants returned per query
Base URL
1. Query by Gene
Retrieve all variants for one or more gene symbols.
| Parameter | Type | Description |
|---|---|---|
type required |
string | Must be gene |
genes required |
string or array | Gene symbol(s). Comma-separated string or JSON array. Max 5. |
Examples
Single gene query:
import requests # Single gene query response = requests.post("https://ibdc.dbt.gov.in/gidb/api/query.php", json={ "type": "gene", "genes": "BRCA1" }) data = response.json() print(f"Found {data['results']['BRCA1']['count']} variants") # Access variant details for variant in data["results"]["BRCA1"]["variants"][:5]: print(f"{variant['GIDB_ID']} - freq: {variant['freq']}")
// Single gene query const response = await fetch("https://ibdc.dbt.gov.in/gidb/api/query.php", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "gene", genes: "BRCA1" }) }); const data = await response.json(); console.log(`Found ${data.results.BRCA1.count} variants`); // Access variant details data.results.BRCA1.variants.slice(0, 5).forEach(v => { console.log(`${v.GIDB_ID} - freq: ${v.freq}`); });
# Single gene query curl -s -X POST "https://ibdc.dbt.gov.in/gidb/api/query.php" \ -H "Content-Type: application/json" \ -d '{"type":"gene","genes":"BRCA1"}' | python3 -m json.tool
Multiple genes (batch):
import requests # Batch gene query (max 5 genes) response = requests.post("https://ibdc.dbt.gov.in/gidb/api/query.php", json={ "type": "gene", "genes": ["BRCA1", "BRCA2", "TP53"] }) data = response.json() for gene, info in data["results"].items(): print(f"{gene}: {info['count']} variants")
// Batch gene query (max 5 genes) const response = await fetch("https://ibdc.dbt.gov.in/gidb/api/query.php", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "gene", genes: ["BRCA1", "BRCA2", "TP53"] }) }); const data = await response.json(); Object.entries(data.results).forEach(([gene, info]) => { console.log(`${gene}: ${info.count} variants`); });
2. Query by Genomic Location
Retrieve all variants within a genomic region. Supports single or batch queries (max 20 locations, each region max 100 kb). Autosomes (chr1–chr22) and sex chromosomes (chrX, chrY) are fully supported — chrX/Y variants include HAP_A1/HAP_A2 haploid call counts.
| Parameter | Type | Description |
|---|---|---|
type required |
string | Must be location |
locations required |
string or array | Genomic region(s) in chrN:start-end format. Comma-separated or JSON array. Max 20. Each region max 100 kb. |
Examples
Single location:
import requests # Query a genomic region (max 100kb per region) response = requests.post("https://ibdc.dbt.gov.in/gidb/api/query.php", json={ "type": "location", "locations": "chr17:43044295-43064295" }) data = response.json() region = data["results"]["chr17:43044295-43064295"] print(f"Found {region['count']} variants in region") # Filter for clinically significant variants for v in region["variants"]: if v.get("ClinVar_CLNSIG") and "Pathogenic" in str(v["ClinVar_CLNSIG"]): print(f" {v['GIDB_ID']} - {v['ClinVar_CLNSIG']} - freq: {v['freq']}")
// Query a genomic region (max 100kb per region) const response = await fetch("https://ibdc.dbt.gov.in/gidb/api/query.php", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "location", locations: "chr17:43044295-43064295" }) }); const data = await response.json(); const region = data.results["chr17:43044295-43064295"]; console.log(`Found ${region.count} variants`);
# Single location query (max 100kb per region) curl -s -X POST "https://ibdc.dbt.gov.in/gidb/api/query.php" \ -H "Content-Type: application/json" \ -d '{"type":"location","locations":"chr17:43044295-43064295"}' | python3 -m json.tool
Batch location query:
import requests # Batch location query (max 20 locations, each max 100kb) regions = [ "chr17:43044295-43094295", # BRCA1 "chr13:32315086-32365086", # BRCA2 "chr7:117480025-117530025", # CFTR ] response = requests.post("https://ibdc.dbt.gov.in/gidb/api/query.php", json={ "type": "location", "locations": regions }) data = response.json() for loc, info in data["results"].items(): print(f"{loc}: {info['count']} variants")
// Batch location query (max 20 locations, each max 100kb) const response = await fetch("https://ibdc.dbt.gov.in/gidb/api/query.php", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "location", locations: [ "chr17:43044295-43094295", "chr13:32315086-32365086", "chr7:117480025-117530025" ] }) }); const data = await response.json(); Object.entries(data.results).forEach(([loc, info]) => { console.log(`${loc}: ${info.count} variants`); });
3. Response Format
All responses are JSON. Each variant object contains:
| Field | Description |
|---|---|
GIDB_ID | Unique variant identifier (e.g., chr7_117504290_C_T) |
CHROM | Chromosome |
POS | Genomic position (GRCh38) |
REF | Reference allele |
ALT | Alternate allele |
SYMBOL | Gene symbol |
freq | Minor allele frequency in GenomeIndia cohort |
AN | Allele number |
NS | Total number of samples |
NS_GT | Samples with called genotype |
AC | Alternate allele count |
HOM_A1 | Homozygous minor allele count |
HOM_A2 | Homozygous major allele count |
HET | Heterozygous count |
HAP_A1 | Haploid minor allele count (chrX/chrY only) |
HAP_A2 | Haploid major allele count (chrX/chrY only) |
Consequence | Functional consequence |
IMPACT | Impact level (HIGH, MODERATE, LOW, MODIFIER) |
HGVSp | Protein change (HGVS notation) |
HGVSc | Coding sequence change |
Existing_variation | Known variant IDs (rsID) |
ClinVar | ClinVar ID |
ClinVar_CLNSIG | Clinical significance |
ClinVar_CLNDN | Clinical disease name |
4. Error Handling
Errors return appropriate HTTP status codes with a JSON error message:
| Status | Meaning |
|---|---|
400 | Bad request (missing/invalid parameters) |
429 | Daily limit exceeded (100 requests/day; resets at midnight UTC) |
500 | Server error |
// Example error response { "error": "Maximum 5 genes per request. You provided 8.", "limit": 5 } // Location region too large { "error": "Region too large: chr1:1-200000 spans 200,000 bp. Maximum allowed is 100,000 bp (100 kb).", "limit": "100kb" }
5. Best Practices
- Use POST with JSON body for batch queries (cleaner than long GET URLs)
- Implement retry logic with exponential backoff for
429responses - Cache results locally to avoid redundant queries
- For large-scale analyses, split into batches of 20 locations or 5 genes
- This API returns main population frequency only. For sub-population data (bio-geographic, linguistic), use the web interface
Python helper function for batch processing
import requests import time def query_gidb_locations(locations, base_url="https://ibdc.dbt.gov.in/gidb/api/query.php"): """Query GI-DB in batches of 20 locations (each max 100kb).""" all_results = {} batch_size = 20 for i in range(0, len(locations), batch_size): batch = locations[i:i + batch_size] response = requests.post(base_url, json={ "type": "location", "locations": batch }) if response.status_code == 429: print("Rate limited, waiting 60s...") time.sleep(60) response = requests.post(base_url, json={ "type": "location", "locations": batch }) data = response.json() all_results.update(data.get("results", {})) time.sleep(2) # Be polite between batches return all_results # Usage my_regions = ["chr1:100000-150000", "chr2:300000-350000", ...] # any number, each max 100kb results = query_gidb_locations(my_regions)