API Reference · v1

UniversityDB API

A REST API over 72,973 Indian universities, colleges and standalone institutions, compiled from research by the UniversityDB team. Endpoints return JSON, and support CORS so you can call them from a browser.

Base URL

https://bharat-campus-compass.lovable.app/api/public

Quick start

Create a free account and confirm your email.
Open your dashboard and create an API key. Copy it — it’s shown only once.
Make your first request:

curl "https://bharat-campus-compass.lovable.app/api/public/v1/institutions?q=iit%20bombay&limit=5" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY"

Authentication

Every request needs an API key. Keys start with udb_. Send it in the Authorization header (preferred), the X-API-Key header, or as an api_key query parameter. Keep keys secret — if one leaks, revoke it from your dashboard and create a new one. You can have up to 5 active keys.

Authorization: Bearer udb_3f9c…
# or
X-API-Key: udb_3f9c…

Rate limits

Free

50 requests per day, per account

Pro

Unlimited. Apply from your dashboard.

Limits are shared across all of your keys and reset at midnight India time (IST). Every response carries these headers:

X-Plan	free or pro
X-RateLimit-Limit	Daily limit, or unlimited
X-RateLimit-Used	Requests counted today
X-RateLimit-Remaining	Requests left today

Custom lists Pro

Create a list of only the colleges you care about from your dashboard. Every endpoint stays exactly the same — search, resolve, autocomplete, states, cities and stats simply return results from your list. Either add list=<list-id> to any request, or create an API key tied to the list so every call is scoped automatically. Scoped responses carry an X-List header.

GET /v1/autocomplete?q=iit&list=6f1c2a7e-…

Errors

Errors use standard HTTP codes and a consistent body:

{ "error": { "code": "rate_limited", "message": "Free plan allows 50 requests per day…" } }

Status	Code	Meaning
400	invalid_params	A parameter is missing or out of range.
401	missing_api_key	No key was sent.
401	invalid_api_key	The key is wrong or has been revoked.
403	account_disabled	The account was disabled by an administrator.
403	pro_required	This feature (custom lists, ID verification) needs the Pro plan.
404	not_found	No institution with that code.
404	list_not_found	The list ID does not belong to your account.
422	unreadable	The ID card photos could not be read.
429	rate_limited	Free plan daily limit reached. Resets at midnight IST.
502	upstream_error	Temporary problem on our side. Retry.

The institution object

code	Unique UniversityDB code. U- universities, C- colleges, S- standalone.
name	Official name.
shortName	Short form / acronym.
category	university \| college \| standalone
type	e.g. State Public University, Institute of National Importance
city	City / district.
state	State or union territory.
university	Affiliating university (colleges only).
management	Government, private aided, private unaided…
yearEstablished	Year founded, if known.
website	Official website.
location	Urban or Rural.
relevance	Ranking score, present only when searching with q.

Search & list institutions

GET/v1/institutions

The main endpoint. With q, results are ranked from most to least relevant, matching full names, acronyms (iitb, iimb) and website names. Without q, lists institutions alphabetically. Combine with filters and paginate.

Parameter	Type	Description
q	string	Free-text search, up to 200 chars.
category	enum	university, college or standalone.
state	string	Exact state name, case-insensitive.
city	string	Exact city name, case-insensitive.
type	string	Institution type.
code	string	UniversityDB code.
page	integer	Page number, default 1.
limit	integer	Results per page, 1-1000, default 50.

curl "https://bharat-campus-compass.lovable.app/api/public/v1/institutions?q=iitb&limit=3" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY"

Response

{
  "total": 62,
  "page": 1,
  "limit": 3,
  "pages": 21,
  "data": [
    {
      "code": "U-0306",
      "name": "Indian Institute of Technology, Bombay",
      "shortName": "IIT",
      "category": "university",
      "type": "Institute of National Importance",
      "city": "Mumbai",
      "state": "Maharashtra",
      "university": null,
      "management": null,
      "yearEstablished": 1958,
      "website": "www.iitb.ac.in",
      "location": "Urban",
      "relevance": 247.3
    }
  ]
}

Get one institution

GET/v1/institutions/{code}

Fetch a single institution by its UniversityDB code. Returns 404 if no record exists.

Parameter	Type	Description
code*	path	e.g. U-0306

curl "https://bharat-campus-compass.lovable.app/api/public/v1/institutions/U-0306" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY"

Response

{
  "data": {
  "code": "U-0306",
  "name": "Indian Institute of Technology, Bombay",
  "shortName": "IIT",
  "category": "university",
  "type": "Institute of National Importance",
  "city": "Mumbai",
  "state": "Maharashtra",
  "university": null,
  "management": null,
  "yearEstablished": 1958,
  "website": "www.iitb.ac.in",
  "location": "Urban"
}
}

Resolve a messy name

GET/v1/resolve

Turn free-text input from a form or resume ("iitb", "Indian Inst Tech Bombay") into one canonical record, with a confidence of high, medium, low or none, plus up to 3 alternatives.

Parameter	Type	Description
name*	string	Text to resolve, 2-200 chars.
state	string	Optional state to narrow the match.

curl "https://bharat-campus-compass.lovable.app/api/public/v1/resolve?name=iit%20bombay" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY"

Response

{
  "input": "iit bombay",
  "confidence": "high",
  "match": { "code": "U-0306", "name": "Indian Institute of Technology, Bombay", "…": "…" },
  "alternatives": [ … ]
}

Autocomplete

GET/v1/autocomplete

Lightweight suggestions for search-as-you-type college pickers. Returns only the fields a dropdown needs.

Parameter	Type	Description
q*	string	Partial text, 1-100 chars.
limit	integer	1-20, default 8.
category	enum	Optional category filter.
state	string	Optional state filter.

curl "https://bharat-campus-compass.lovable.app/api/public/v1/autocomplete?q=iit%20bom&limit=5" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY"

Response

{
  "query": "iit bom",
  "suggestions": [
    { "code": "U-0306", "label": "Indian Institute of Technology, Bombay", "shortName": "IIT", "city": "Mumbai", "state": "Maharashtra", "category": "university" }
  ]
}

List states

GET/v1/states

All 36 states and union territories (28 states, 8 UTs) with kind, counts of institutions by category and number of cities.

curl "https://bharat-campus-compass.lovable.app/api/public/v1/states" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY"

Response

{
  "data": [
    { "state": "Karnataka", "kind": "state", "institutions": 7251, "universities": 97, "colleges": 5140, "standalone": 2014, "cities": 31 }
  ]
}

List cities in a state

GET/v1/cities

All cities in a state with the number of institutions in each. Use the names as the city filter on search.

Parameter	Type	Description
state*	string	State name.

curl "https://bharat-campus-compass.lovable.app/api/public/v1/cities?state=Kerala" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY"

Response

{
  "state": "Kerala",
  "data": [ { "city": "Ernakulam", "institutions": 292 } ]
}

Dataset statistics

GET/v1/stats

Totals for the whole dataset.

curl "https://bharat-campus-compass.lovable.app/api/public/v1/stats" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY"

Response

{
  "data": {
    "total": 72973,
    "byCategory": { "university": 1438, "college": 54458, "standalone": 17077 },
    "states": 36,
    "cities": 762
  },
  "source": "Research by the UniversityDB team"
}

Verify a student ID card

POST/v1/verify-idPro

AI reads the front and back of a student ID card and checks that the printed name and college match what the student told you, and that the card has not expired. Send multipart form-data with image files, or JSON with https URLs or base64 data URLs (max 6 MB each). Images are not stored.

Parameter	Type	Description
name*	string	Student's full name.
college*	string	College or university name.
front*	file \| string	Front of the ID card.
back*	file \| string	Back of the ID card.

curl -X POST "https://bharat-campus-compass.lovable.app/api/public/v1/verify-id" \
  -H "Authorization: Bearer $UNIVERSITYDB_KEY" \
  -F name="Ananya Rao" \
  -F college="IIT Bombay" \
  -F front=@id-front.jpg \
  -F back=@id-back.jpg

Response

{
  "verified": true,
  "status": "verified",
  "confidence": "high",
  "checks": { "isStudentIdCard": true, "nameMatches": true, "collegeMatches": true, "notExpired": true },
  "extracted": { "name": "Ananya Rao", "college": "Indian Institute of Technology Bombay", "expiryDate": "2027-06-30" },
  "reason": "Name and college match and the card is valid until June 2027.",
  "checkedOn": "2026-11-04"
}

Try it

Requests count against your daily limit. Get a key.