Skip to content

First Manual API Run

This page turns one concrete question into one traceable CoRE Stack run:

How much of my tehsil or block is built-up?

Use it as the bridge between "the backend is running" and "I can follow one real computation through the stack."

What You Will Do

  1. choose a place
  2. trigger one LULC run
  3. trace the route and handler
  4. inspect the next computation file
  5. calculate the built-up share from the output

Before You Start

  • Complete Installer first.
  • Keep one valid gee_account_id ready if your local setup requires it.
  • Start with the normal tehsil or block route if you already know the place names.

If exact spellings are difficult, use the fallback at the end of this page to start from latitude and longitude instead.

Step 1: Pick A Place

The typical path uses:

  • state
  • district
  • block or tehsil

Example:

  • state: karnataka
  • district: raichur
  • block: devadurga

If you are not sure about the spellings, first use GeoAdmin (NoAuth) APIs to confirm the exact location names you should send into the computation route.

Reveal a quick location-finding route Start with your state: 
curl https://geoserver.core-stack.org/api/v1/get_states/
Once you find your state (eg: 29), start with: 
curl https://geoserver.core-stack.org/api/v1/get_districts/29/
Using the district code in your state, follow with: 
curl https://geoserver.core-stack.org/api/v1/get_blocks/566/
That lets you copy the exact district and block names before you try the computation route locally.

Step 2: Trigger one LULC Run

Start with the tehsil-level LULC route because it keeps the scope easy to inspect.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "state": "karnataka",
    "district": "raichur",
    "block": "devadurga",
    "start_year": 2022,
    "end_year": 2023,
    "gee_account_id": 1
  }' \
  http://127.0.0.1:8000/api/v1/lulc_for_tehsil/

Why this route?

  • it is a real computation endpoint already listed in Computing API Endpoints
  • built-up is one class inside the resulting LULC output
  • it gives you a clean path from request to handler to computation module
Reveal what success should look like The route should acknowledge the request quickly, because the heavy work usually moves into a task or computation boundary after the handler parses the payload. If nothing happens, stop here and check: - the backend server is running - your request keys are spelled exactly as expected - your local environment has the required Earth Engine configuration

Step 3: Find The Route In Code

Open the route file first:

Look for a line shaped like this:

Route shape to look for in computing/urls.py
1
2
3
urlpatterns = [
    path("lulc_for_tehsil/", ...),
]

You are not trying to memorize the whole file. You are only verifying one thing:

the incoming POST /api/v1/lulc_for_tehsil/ request really has a named route in the computing surface.

Reveal the next clue Once you find the route entry, the next useful question is: which handler in `computing/api.py` owns this request?

Step 4: Inspect The Handler

Now open:

The handler will usually have this overall shape:

Typical computing handler shape
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
@api_view(["POST"])
@schema(None)
def lulc_for_tehsil(request):
    state = request.data.get("state").lower()
    district = request.data.get("district").lower()
    block = request.data.get("block").lower()
    gee_account_id = request.data.get("gee_account_id")
    run_lulc_task.apply_async(
        args=[state, district, block, gee_account_id],
        queue="nrm",
    )
    return Response({"Success": "Successfully initiated"})

Focus on the highlighted parts:

  • request fields are normalized early
  • the handler stays thin
  • the real work is handed off to a task or computation boundary
Reveal what to inspect next Do not stop at the handler. Search for the task or function it calls, then follow that into the LULC workflow module under `computing/`. That is the point where the route stops being an API concern and becomes a geospatial computation concern.

Step 5: Follow The Computation Path

At this point, your next useful references are:

Use this rule while tracing:

  1. computing/urls.py tells you the route name
  2. computing/api.py tells you the handler and task handoff
  3. the LULC module tells you how the result is actually produced

If you lose the trail, search for:

rg "lulc_for_tehsil|lulc_v3|lulc_v4" computing

That usually gets you back onto the main road quickly.

Step 6: Calculate The Built-up Share

Once the computation finishes, extract or summarize the class areas and compute the built-up percentage.

Turn class areas into a built-up share
1
2
3
4
5
6
7
8
class_areas = {
    "cropland": 1264.2,
    "built_up": 182.4,
    "water": 37.8,
    "other": 615.6,
}
built_up_share = 100 * class_areas["built_up"] / sum(class_areas.values())
print(f"Built-up share: {built_up_share:.2f}%")

What matters here is the shape of the final reasoning:

  • identify the built-up class
  • identify the total area under consideration
  • divide built-up area by total area
  • report the answer as a percentage

If your output is a table instead of a dictionary, the same rule still applies.

Optional Fallback: Start From Latitude And Longitude

Use this only when place names are hard to resolve or you want a quick local dry run around a point before running the full tehsil workflow.

This is a local exploration shortcut, not the canonical published tehsil route.

Optional 1 km point-based sanity check
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import ee

ee.Initialize()
lat, lon = 15.91, 76.53
roi = ee.Geometry.Point([lon, lat]).buffer(1000)

# Replace this with the local LULC helper you are tracing in your checkout.
class_areas = run_lulc_sample(roi=roi, start_year=2022, end_year=2023)
built_up_share = 100 * class_areas["built_up"] / sum(class_areas.values())
print(f"Built-up share inside 1 km radius: {built_up_share:.2f}%")

Use this fallback to answer a smaller question first:

"Around this point, in a 1 km radius, what share is built-up?"

Then return to the tehsil route once you are ready to run the full administrative unit.

Outcome

By the end of this page, you should have:

  • sent one real LULC request
  • located the route and handler in code
  • followed the handoff into the computation layer
  • calculated one built-up-share result for a place or a 1 km local ROI

If you want the next step after this, continue into Local Pipeline First or How They Work Programmatically.