Gov APIkys.udiseplus.gov.in ↗
Access Indian school data from UDISE Plus: states, districts, blocks, school categories, management types, and detailed school profiles via 8 endpoints.
What is the Gov API?
This API exposes 8 endpoints covering India's UDISE Plus Know Your School portal, giving programmatic access to the full geographic hierarchy of states, districts, and blocks, plus school search and detailed school profiles. The get_school_details endpoint returns a school's address, headmaster info, board affiliation, facility data (classrooms, toilets, internet), and enrollment and teacher counts in a single call, identified by UDISE school ID.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/cf9b943b-9961-4e2b-a62d-a207d488a140/get_academic_years' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace kys-udiseplus-gov-in-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: UDISE Plus Schools API — geographic hierarchy and school details."""
from parse_apis.udise_plus_schools_api import UDISEPlus, YearId, NotFoundError
udise = UDISEPlus()
# List available academic years
for year in udise.academicyears.list(limit=5):
print(year.year_id, year.year_desc)
# List all states for the latest academic year
for state in udise.states.list(year_id=YearId.REAL_TIME, limit=5):
print(state.state_name, state.udise_state_code)
# Navigate hierarchy: construct a State, list its districts
delhi = udise.state(state_id=107)
district = delhi.districts.list(year_id=YearId.YEAR_2024_25, limit=3).first()
if district:
print(district.district_name, district.udise_district_code)
# Drill into blocks for that district
constructed_district = udise.district(district_id=district.district_id)
for block in constructed_district.blocks.list(limit=3):
print(block.block_name, block.udise_block_code)
# Fetch full school details with typed error handling
try:
school = udise.schools.get(school_id=5420344)
print(school.report_card.school_name, school.report_card.management_desc)
print(school.statistics.total_count, school.statistics.total_teachers_regular)
print(school.facility.classrooms_instructional, school.facility.internet)
print(school.profile.address, school.profile.head_master_name)
except NotFoundError as exc:
print(f"School not found: {exc}")
# List school categories and management types
for cat in udise.categories.list(limit=5):
print(cat.cat_id, cat.cat_value)
for mgmt in udise.managements.list(limit=5):
print(mgmt.management_id, mgmt.management_name)
print("exercised: academicyears.list / states.list / districts.list / blocks.list / schools.get / categories.list / managements.list")
Fetch the list of academic years available in the system. Returns year IDs and descriptions used as parameters in other endpoints. The list is small (typically 5-6 entries) and does not paginate.
No input parameters required.
{
"type": "object",
"fields": {
"data": "array of academic year objects with yearId and yearDesc"
},
"sample": {
"data": {
"data": [
{
"yearId": 0,
"yearDesc": "Real Time"
},
{
"yearId": 11,
"yearDesc": "2024-25"
},
{
"yearId": 10,
"yearDesc": "2023-24"
}
]
},
"status": "success"
}
}About the Gov API
Geographic Hierarchy and Reference Data
Before querying schools, use the reference endpoints to resolve internal IDs. get_states returns each state's internal stateId and udiseStateCode — the stateId (e.g., 107 for Delhi, 136 for Telangana) is what get_districts and search_schools_by_region require, not the UDISE code. get_districts takes that state_id and returns districtId, districtName, and udiseDistrictCode. get_blocks then takes an internal district_id and returns block-level identifiers. All three hierarchy endpoints accept an optional year_id from get_academic_years; passing 0 (the default) retrieves the latest real-time data.
School Search
search_schools_by_region accepts a required state_id and district_id, with optional filters for block_id, cluster_id, village_id, category_id (from get_categories), and management_id (from get_managements). The response includes aggregate counts in allSchools, operationalSchools, and nonOperationalSchools objects, plus a content array listing matching schools. School categories cover levels like Primary, Upper Primary, and Secondary; management types distinguish Government, Private, Aided, and similar classifications.
School Details
get_school_details takes a single school_id (UDISE numeric ID, retrievable from search_schools_by_region) and returns four grouped objects. profile covers address, headmaster name, affiliated board, and medium of instruction. facility covers classroom count, toilet availability, electricity, library, playground, and internet access. statistics holds student and teacher counts. report_card consolidates location, category, management classification, and detailed teacher and student breakdowns in one place.
Academic Year Handling
get_academic_years lists all available year IDs and their descriptions (e.g., 2024-25, Real Time). A yearId of 0 consistently maps to the real-time or latest dataset across every endpoint that accepts year_id. To pull historical snapshots — for example, comparing enrollment counts from 2021-22 against 2023-24 — pass the specific year IDs returned by this endpoint.
The Gov API is a managed, monitored endpoint for kys.udiseplus.gov.in — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when kys.udiseplus.gov.in changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official kys.udiseplus.gov.in API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a school finder tool filtered by district, block, and management type using
search_schools_by_region. - Compile facility audits (classrooms, toilets, internet) across a district by iterating
get_school_detailsfor each school in acontentarray. - Track year-over-year enrollment changes by calling
get_school_detailswith differentyear_idvalues fromget_academic_years. - Generate state-level reports on government vs. private school distribution using
get_managementsandsearch_schools_by_region. - Map school density by block by aggregating
operationalSchoolscounts across all blocks in a district. - Filter schools by category (Primary, Secondary) and management type to support education policy research datasets.
- Cross-reference UDISE school codes with internal IDs to link external datasets to school profiles from
get_school_details.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does UDISE Plus have an official developer API?+
What does `get_school_details` actually return, and how do I get a school ID?+
get_school_details returns four objects: profile (address, headmaster, board, medium of instruction), facility (classrooms, toilets, electricity, library, playground, internet), statistics (student and teacher counts), and report_card (location, category, management, detailed breakdowns). The required school_id is the numeric UDISE school code, which you can obtain from the content array returned by search_schools_by_region.Why do I need to use internal IDs rather than UDISE codes for filtering?+
get_districts and search_schools_by_region endpoints require the internal stateId and districtId values, not the udiseStateCode or udiseDistrictCode strings. The UDISE codes are returned as reference fields but are not accepted as filter inputs. Always resolve IDs through get_states and get_districts first.Does the API return academic performance scores or exam results for schools?+
Does the API support pagination when searching schools in a large district?+
search_schools_by_region endpoint returns results in a content array, but the current endpoint definition does not expose pagination parameters such as page number or page size. For large districts, applying optional filters like block_id, category_id, or management_id can narrow result sets. You can fork this API on Parse and revise it to add pagination parameters if you need to handle very large result sets programmatically.