Ac APIingres.iith.ac.in ↗
Access India's national groundwater assessment data via 7 endpoints. Retrieve recharge, extraction, and resource availability at state, district, and block level.
What is the Ac API?
The INGRES API exposes India's National Groundwater Resource Estimation data across 7 endpoints, covering national summaries down to block-level breakdowns. Using get_state_data you can retrieve district-level recharge and extraction figures for any state by name or UUID; get_district_data goes further, returning block-level water data within a chosen district. Assessment years, report listings, and a location search endpoint round out the coverage.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/193cf43e-4028-48b5-ad4b-45df7e18386f/get_assessment_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 ingres-iith-ac-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.
"""
India Groundwater Resources API - Usage Example
Get your API key from: https://parse.bot/settings
"""
from parse_apis.india_groundwater_resources_api import Ingres, AssessmentYear, Query, StateNotFound
ingres = Ingres()
# Get available assessment years
year_list = ingres.assessmentyearlists.get()
print("Available years:", year_list.years)
# Get national-level summary for latest year
summary = ingres.countrysummaries.get(year=AssessmentYear.Y_2024_2025)
print(summary.state_count, summary.stage_of_extraction, summary.total_gw_extraction)
# List states and take the first one
state = ingres.states.list(year=AssessmentYear.Y_2024_2025, limit=3).first()
if state:
print(state.location_name, state.location_uuid)
# Search for a state and drill into districts
for location in ingres.states.search(query=Query.RAJASTHAN, limit=3):
print(location.name, location.uuid)
# Construct a state and list its districts
rajasthan = ingres.state(location_uuid="785cc6f0-e9d0-4961-9578-08ed2f24377a")
first_district = rajasthan.districts.list(limit=3).first()
if first_district:
print(first_district.location_name, first_district.stage_of_extraction)
# Drill into blocks for that district
for block in first_district.blocks.list(state_uuid="785cc6f0-e9d0-4961-9578-08ed2f24377a", limit=3):
print(block.location_name, block.total_gw_availability)
# Typed error handling
try:
ingres.states.search(query=Query.TAMIL, limit=1).first()
except StateNotFound as exc:
print(f"State not found: {exc.state_name}")
print("exercised: assessmentyearlists.get / countrysummaries.get / states.list / states.search / districts.list / blocks.list")
Returns the list of assessment year periods available in the INGRES system. Each year is a string in YYYY-YYYY format representing the assessment cycle. Use these values as the year parameter in other endpoints.
No input parameters required.
{
"type": "object",
"fields": {
"years": "array of assessment year strings in format YYYY-YYYY"
},
"sample": {
"data": [
"2012-2013",
"2016-2017",
"2019-2020",
"2021-2022",
"2022-2023",
"2023-2024",
"2024-2025"
],
"status": "success"
}
}About the Ac API
What the API Covers
The API surfaces data from India's INGRES portal, which publishes periodic groundwater assessments across multiple geographic tiers. Every response relates to a specific assessment year — expressed as a YYYY-YYYY string such as 2022-2023 or 2024-2025 — and you can call get_assessment_years (no inputs required) to retrieve the full list of available periods before making other requests.
Navigating Geographic Levels
get_country_summary returns aggregated national statistics: totals for extractable resources, current extraction, recharge, and natural discharges computed across all states for the chosen year. get_state_list returns an array of state objects each carrying groundwater metrics and a locationUUID you can pass to downstream calls. get_state_data accepts either state_uuid or state_name and returns district-level breakdowns; get_district_data drills one level further to blocks, requiring both a state identifier and a district identifier (again accepting either names or UUIDs). Block-level objects include water level information alongside the standard recharge and extraction fields.
Supporting Endpoints
get_report_list returns a structured object mapping year strings to arrays of report objects, each with filename, file path, and timestamp — useful for linking users directly to the underlying PDF reports that accompany each assessment cycle. search_location accepts a free-text query string and performs a case-insensitive substring match against state names, returning matching objects with their UUIDs. This is the quickest way to resolve a partial state name to its UUID without iterating the full state list.
Identifier Lookup Behavior
Endpoints that accept both _name and _uuid parameters perform automatic UUID resolution when only a name is supplied. This means you can call get_district_data with just state_name and district_name without separately fetching UUIDs first, though passing UUIDs directly avoids the internal lookup step and is preferable in high-volume workflows.
The Ac API is a managed, monitored endpoint for ingres.iith.ac.in — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ingres.iith.ac.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 ingres.iith.ac.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?+
- Tracking annual changes in groundwater extraction for a specific state across multiple assessment years using
get_state_data - Building a national groundwater depletion map by aggregating block-level data from
get_district_dataacross all districts - Comparing district-level recharge versus extraction ratios to identify over-exploited zones
- Retrieving downloadable PDF assessment reports via
get_report_listfor a given assessment year - Resolving partial or misspelled state names to valid UUIDs using
search_locationbefore querying detailed data - Computing national totals for a given assessment year using
get_country_summaryto feed dashboard KPIs - Monitoring block-level water level information alongside extraction figures for groundwater sustainability research
| 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 INGRES have an official public developer API?+
What does `get_district_data` return that `get_state_data` does not?+
get_state_data returns an array of district objects for the chosen state. get_district_data goes one level deeper, returning an array of block objects within a single district, and each block object includes water level information in addition to the recharge and extraction fields present at the district level.Does the API expose taluk- or village-level groundwater data below the block level?+
get_district_data. You can fork this API on Parse and revise it to add a sub-block endpoint if the INGRES portal publishes that data in the future.Are assessment years updated automatically, and how far back does coverage go?+
get_assessment_years, which reflects the assessment periods published on the INGRES portal. Historical depth depends on what the portal has indexed; call that endpoint first to confirm which YYYY-YYYY strings are valid before querying other endpoints.