# Kys Udiseplus — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for schools across India by geographic region and management type, then access detailed information about any school including academic performance, facilities, and enrollment data. Navigate through states, districts, and blocks to find schools that match your criteria and compare their profiles.

**Category:** Education | **Website:** [kys.udiseplus.gov.in/](https://kys.udiseplus.gov.in/) | **Docs:** [parse.bot/marketplace/75b66f72-2971-432f-8966-ed1cc64092fa/kys-udiseplus-gov-in-api](https://parse.bot/marketplace/75b66f72-2971-432f-8966-ed1cc64092fa/kys-udiseplus-gov-in-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_academic_years

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.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/get_academic_years \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_blocks

Fetch the list of blocks for a given district. Use the internal districtId from get_districts, NOT the UDISE district code. Returns block IDs and names for finer-grained geographic filtering.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `district_id` | integer | Yes | Internal district ID from get_districts endpoint (e.g. 1601 for East Delhi). |
| `year_id` | integer | No | Year ID from get_academic_years. Defaults to 0 (latest/Real Time). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/get_blocks \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"district_id":"<integer>","year_id":"<integer>"}'
```

### get_categories

Fetch school categories (e.g. Primary, Upper Primary, Secondary, Higher Secondary). Returns category IDs and descriptions. The list is fixed (~10 entries) and does not paginate.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_districts

Fetch the list of districts for a given state. Use the internal stateId from get_states, NOT the UDISE state code. Returns district IDs and names needed for get_blocks and school lookups.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `state_id` | integer | Yes | Internal state ID from get_states endpoint (e.g. 107 for Delhi, 136 for Telangana). |
| `year_id` | integer | No | Year ID from get_academic_years. Defaults to 0 (latest/Real Time). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/get_districts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state_id":"<integer>","year_id":"<integer>"}'
```

### get_managements

Fetch school management types (e.g. Department of Education, Government Aided, Private Unaided). Returns management IDs and names. The list is fixed (~17 entries) and does not paginate.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/get_managements \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_school_details

Get comprehensive details for a specific school including profile, facility, statistics, and report card information. Aggregates data from four sub-endpoints into a single response. The school_id is the UDISE school code (numeric). Some sub-sections may be absent if the school has not reported that data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `school_id` | integer | Yes | UDISE school ID (numeric code identifying the school, e.g. 5420344). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/get_school_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"school_id":"<integer>"}'
```

### get_states

Fetch the list of all states and union territories. Returns internal stateId values needed for get_districts and other regional endpoints. Includes special entities like Kendriya Vidyalaya Sanghathan and Navodaya Vidyalaya Samiti.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year_id` | integer | No | Year ID from get_academic_years. Defaults to 0 (latest/Real Time). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/get_states \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year_id":"<integer>"}'
```

### search_schools_by_region

Search for schools based on regional filters. Requires state_id and district_id (internal IDs from get_states/get_districts). Returns school statistics and a list of schools in the 'content' field.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `block_id` | string | No | Block ID from get_blocks |
| `category_id` | string | No | Category ID from get_categories |
| `cluster_id` | string | No | Cluster ID |
| `district_id` | integer | Yes | Internal district ID from get_districts (e.g., 1601 for East Delhi) |
| `management_id` | string | No | Management ID from get_managements |
| `state_id` | integer | Yes | Internal state ID from get_states (e.g., 107 for Delhi) |
| `village_id` | string | No | Village ID |
| `year_id` | integer | No | Year ID. Defaults to 0 (latest). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kys-udiseplus-gov-in-api-75b66f72/search_schools_by_region \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"block_id":"<string>","category_id":"<string>","cluster_id":"<string>","district_id":"<integer>","management_id":"<string>","state_id":"<integer>","village_id":"<string>","year_id":"<integer>"}'
```