API Documentation
Complete reference for the BodhDisha API
Getting Started
The BodhDisha API provides programmatic access to India's most comprehensive education data repository. This REST API allows you to access structured information about exams, colleges, universities, courses, scholarships, and coaching centres.
Quick Start in 3 Steps
Get Your API Key
Sign up at bodhdisha.com/api/register to get your API key.
Make Your First Request
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://bodhdisha.com/api/v1/health"
Start Building
Explore the endpoints below to find the data you need.
https://bodhdisha.com/api/v1
Authentication
Every protected API request requires a valid API key. You can obtain your API key from the developer dashboard after signing up.
Authentication Methods
Send your API key using one of these methods:
Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY
Base URL
All API endpoints are relative to the following base URL:
https://bodhdisha.com/api/v1
Example full endpoint:
https://bodhdisha.com/api/v1/colleges
Rate Limiting
Each API key has a request limit per hour. The limit varies based on your subscription tier.
When exceeded, the API returns a 429 status with a Retry-After header.
429 responses. Repeated immediate retries will delay your access further.
API Endpoints
All endpoints support GET requests only and return JSON responses.
Exams
Access information about educational exams in India.
| Method | Endpoint | Description |
|---|---|---|
| GET | /exams |
List all active exams |
| GET | /exams/{slug} |
Get detailed exam information by slug |
Search fields: name, short_name,
category, education_level, state
GET /exams?search=JEE&page=1&per_page=20
View Example Response
{
"success": true,
"data": [
{
"id": 1,
"name": "Joint Entrance Examination Main",
"slug": "jee-main",
"short_name": "JEE Main",
"category": "engineering",
"education_level": "undergraduate",
"state": "national",
"description": "Joint Entrance Examination Main is a national-level entrance exam...",
"eligibility_summary": "10+2 with Physics, Chemistry, and Mathematics",
"last_verified_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-06-20T14:22:10Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 125,
"last_page": 7
}
}
Colleges
Access information about colleges across India.
| Method | Endpoint | Description |
|---|---|---|
| GET | /colleges |
List all active colleges |
| GET | /colleges/{slug} |
Get detailed college information by slug |
Search fields: name, state,
city, accreditation
GET /colleges?search=delhi&page=1&per_page=20
View Example Response
{
"success": true,
"data": [
{
"id": 1,
"name": "Indian Institute of Technology Delhi",
"slug": "iit-delhi",
"state": "Delhi",
"city": "New Delhi",
"accreditation": "AICTE",
"is_verified": true,
"trust_score": 4.9,
"description": "IIT Delhi is one of the premier engineering institutes...",
"official_website": "https://iitd.ac.in",
"last_verified_at": "2024-01-15T10:30:00Z"
}
]
}
Universities
Access information about universities across India.
| Method | Endpoint | Description |
|---|---|---|
| GET | /universities |
List all active universities |
| GET | /universities/{slug} |
Get detailed university information by slug |
Search fields: name, state,
city, accreditation
Courses
Access information about courses offered by various institutions.
| Method | Endpoint | Description |
|---|---|---|
| GET | /courses |
List all active courses |
| GET | /courses/{slug} |
Get detailed course information by slug |
Search fields: name, provider,
level, duration
Scholarships
Access information about scholarships available for students.
| Method | Endpoint | Description |
|---|---|---|
| GET | /scholarships |
List all active scholarships |
| GET | /scholarships/{slug} |
Get detailed scholarship information by slug |
Search fields: name, provider,
education_level, state
Coaching Centres
Access information about coaching centres across India.
| Method | Endpoint | Description |
|---|---|---|
| GET | /coaching |
List all active coaching centres |
| GET | /coaching/{slug} |
Get detailed coaching centre information by slug |
Search fields: name, city,
area_hub, state, fee_range
Pagination
All collection endpoints support pagination to help you manage large datasets.
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
Integer | 1 |
Page number (starts at 1) |
per_page |
Integer | 20 |
Records per page (max: 100) |
Example
GET /colleges?page=2&per_page=50
Response
{
"success": true,
"data": [ ... ],
"pagination": {
"page": 2,
"per_page": 50,
"total": 125,
"last_page": 3
}
}
Search
Use the search parameter to search across specific fields in each endpoint.
| Endpoint | Searchable Fields |
|---|---|
/exams |
name, short_name, category, education_level, state |
/colleges |
name, state, city, accreditation |
/universities |
name, state, city, accreditation |
/courses |
name, provider, level, duration |
/scholarships |
name, provider, education_level, state |
/coaching |
name, city, area_hub, state, fee_range |
Example
GET /exams?search=JEE&page=1&per_page=20
Response Format
Single Record Response
{
"success": true,
"data": {
"id": 1,
"name": "Indian Institute of Technology Guwahati",
"slug": "iit-guwahati",
"location": "Guwahati, Assam",
"accreditation": "AICTE",
"website": "https://www.iitg.ac.in",
"trust_score": 4.8,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-06-20T14:22:10Z"
}
}
Collection Response
{
"success": true,
"data": [
{ ... },
{ ... }
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 125,
"last_page": 7
}
}
Error Response
{
"success": false,
"error": {
"code": "not_found",
"message": "College not found"
}
}
HTTP Status Codes
| Code | Meaning | Description |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Invalid parameters or malformed request |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | API key does not have permission |
| 404 | Not Found | Resource does not exist |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Server Error | Unexpected server error |
Error Response Format
{
"success": false,
"error": {
"code": "not_found",
"message": "The requested resource was not found"
}
}
Code Examples
cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://bodhdisha.com/api/v1/colleges/iit-guwahati"
JavaScript (Fetch)
const response = await fetch(
'https://bodhdisha.com/api/v1/colleges?search=guwahati',
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Accept': 'application/json'
}
}
);
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
const result = await response.json();
console.log(result.data);
JavaScript (Axios)
import axios from 'axios';
const response = await axios.get(
'https://bodhdisha.com/api/v1/colleges',
{
params: {
search: 'guwahati',
per_page: 20
},
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
console.log(response.data.data);
Python
import requests
response = requests.get(
'https://bodhdisha.com/api/v1/colleges',
params={
'search': 'guwahati',
'per_page': 20
},
headers={
'Authorization': 'Bearer YOUR_API_KEY'
}
)
response.raise_for_status()
data = response.json()
print(data['data'])
PHP
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://bodhdisha.com/api/v1/colleges?search=guwahati',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_KEY',
'Accept: application/json'
]
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
$data = json_decode($response, true);
print_r($data['data']);
} else {
echo "Error: HTTP $httpCode\n";
}
Ruby
require 'net/http'
require 'uri'
require 'json'
uri = URI('https://bodhdisha.com/api/v1/colleges')
params = { search: 'guwahati', per_page: 20 }
uri.query = URI.encode_www_form(params)
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer YOUR_API_KEY'
req['Accept'] = 'application/json'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
http.request(req)
end
if res.is_a?(Net::HTTPSuccess)
data = JSON.parse(res.body)
puts data['data']
else
puts "Error: #{res.code} - #{res.message}"
end
Go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
baseURL, _ := url.Parse("https://bodhdisha.com/api/v1/colleges")
params := url.Values{}
params.Add("search", "guwahati")
params.Add("per_page", "20")
baseURL.RawQuery = params.Encode()
req, _ := http.NewRequest("GET", baseURL.String(), nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Accept", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
if resp.StatusCode == 200 {
var result map[string]interface{}
json.Unmarshal(body, &result)
fmt.Printf("%v\n", result["data"])
} else {
fmt.Printf("Error: %d\n", resp.StatusCode)
}
}
Security Best Practices
- Keep API keys confidential — treat them like passwords
- Use HTTPS — always encrypt data in transit
- Store keys in environment variables or a secure secrets manager
- Never commit API keys to version control (Git, SVN, etc.)
- Do not expose API keys in client-side JavaScript
- Request only the data you need — use search filters effectively
- Respect rate limits — implement graceful error handling
- Rotate keys periodically and revoke compromised keys immediately
Frequently Asked Questions
How do I get an API key?
Sign up at bodhdisha.com/api/register using Google or GitHub. Your API key will be displayed in the dashboard.
What happens if I exceed my rate limit?
You'll receive a 429 Too Many Requests response. The limit resets every hour.
Can I use the API for commercial purposes?
Yes, the API is available for commercial use with appropriate subscription plans.
How fresh is the data?
Data is updated regularly. Cache duration varies by endpoint (5-15 minutes for lists, 30 minutes for details).
Is there a sandbox environment?
The production API can be used for testing with the Free tier (50 requests/hour).
How do I report an issue?
Contact us at [email protected] or through the contact form.