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.

Base URL

1. Query by Gene

Retrieve all variants for one or more gene symbols.

Examples

Single gene query:

Copyimport requests

# Single gene query
response = requests.post("https://gidb.igib.res.in/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']}")

Copy// Single gene query
const response = await fetch("https://gidb.igib.res.in/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}`);
});

Copy# Single gene query
curl -s -X POST "https://gidb.igib.res.in/api/query.php" \
  -H "Content-Type: application/json" \
  -d '{"type":"gene","genes":"BRCA1"}' | python3 -m json.tool

Multiple genes (batch):

Copyimport requests

# Batch gene query (max 5 genes)
response = requests.post("https://gidb.igib.res.in/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")

Copy// Batch gene query (max 5 genes)
const response = await fetch("https://gidb.igib.res.in/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).

Examples

Single location:

Copyimport requests

# Query a genomic region (max 100kb per region)
response = requests.post("https://gidb.igib.res.in/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']}")

Copy// Query a genomic region (max 100kb per region)
const response = await fetch("https://gidb.igib.res.in/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`);

Copy# Single location query (max 100kb per region)
curl -s -X POST "https://gidb.igib.res.in/api/query.php" \
  -H "Content-Type: application/json" \
  -d '{"type":"location","locations":"chr17:43044295-43064295"}' | python3 -m json.tool

Batch location query:

Copyimport 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://gidb.igib.res.in/api/query.php", json={
    "type": "location",
    "locations": regions
})

data = response.json()
for loc, info in data["results"].items():
    print(f"{loc}: {info['count']} variants")

Copy// Batch location query (max 20 locations, each max 100kb)
const response = await fetch("https://gidb.igib.res.in/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:

4. Error Handling

Errors return appropriate HTTP status codes with a JSON error message:

Copy// 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 429 responses
• 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

Copyimport requests
import time

def query_gidb_locations(locations, base_url="https://gidb.igib.res.in/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)