GeoFlux documentation

Overview

GeoFlux is Swarnandhra's self-hosted geospatial data service, built with agriculture in mind. It runs a full Overpass API instance over the OpenStreetMap (OSM) database for India, and exposes it securely over HTTPS to registered users with personal API keys.

Typical uses:

• Agriculture: farmland and orchard mapping, irrigation coverage, distance to mandis and input dealers, aquaculture and village-level fact sheets.
• Research and student projects: GIS analysis, urban planning, transport studies, environmental mapping.
• Applications: "nearest hospital / ATM / bus stop" features, location-aware apps, campus and city dashboards.
• Data science: build datasets of facilities, road networks or land use for machine-learning and statistics.
• Teaching: hands-on lessons in spatial queries without depending on rate-limited public servers.

What data you get

GeoFlux returns raw OpenStreetMap data. OSM describes the world with three element types:

Every element carries tags (key=value pairs) that describe it, e.g. amenity=hospital, name=Apollo Hospital, name:te=…, opening_hours=Mo-Su 00:00-24:00. Querying GeoFlux is mostly about filtering by tags and location.

Main categories

Coverage and freshness

The database covers India. It is a snapshot of OpenStreetMap; the exact date is returned in every JSON response as osm3s.timestamp_osm_base, and by GET /api/me. Data outside the coverage area returns empty results.

Quick start

1. Get an API key from the GeoFlux administrator (see API keys). It looks like gf_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.

2. Store it in an environment variable rather than in your code:

# Linux / macOS
export GEOFLUX_KEY="gf_your_key_here"

# Windows PowerShell
$env:GEOFLUX_KEY = "gf_your_key_here"

3. Check the key works:

curl -H "X-API-Key: $GEOFLUX_KEY" https://api.geoflux.swarnandhra.ac.in/api/me

4. Run your first query, all cafés within 1 km of a point in Hyderabad:

curl -X POST https://api.geoflux.swarnandhra.ac.in/api/interpreter \
  -H "X-API-Key: $GEOFLUX_KEY" \
  --data-urlencode 'data=[out:json][timeout:25];
node["amenity"="cafe"](around:1000,17.3850,78.4867);
out;'

The response is JSON with an elements array:

{
  "version": 0.6,
  "generator": "Overpass API 0.7.62",
  "osm3s": { "timestamp_osm_base": "2026-03-25T00:53:14Z", "copyright": "… ODbL." },
  "elements": [
    { "type": "node", "id": 2261567007, "lat": 17.3871359, "lon": 78.4776933,
      "tags": { "amenity": "cafe", "name": "…" } }
  ]
}

API keys

GeoFlux is not open to the public. Every request needs a valid API key, which is issued by the administrator for a specific person or project.

Requesting a key

Send a request to the GeoFlux administrator with:

• Your name, department or organisation, and email
• The purpose of the project and the expected volume (queries per day)
• How long you need access (e.g. one semester)
• Optionally, the fixed server IP addresses that will call the API (for extra protection)

What a key includes

Authentication

All API calls must use HTTPS. Plain HTTP requests are rejected. Send the key in one of these ways, in order of preference:

Endpoints

Base URL: https://api.geoflux.swarnandhra.ac.in

POSTGET /api/interpreter

Runs an Overpass query. This is the same interface as the standard Overpass API.

• POST, form-encoded (recommended): body data=<url-encoded query>, content type application/x-www-form-urlencoded.
• POST, raw: the query text as the request body.
• GET: /api/interpreter?data=<url-encoded query>. Fine for short queries.

Maximum query size: 1 MB. The response format depends on the query's [out:…] setting (JSON, XML or CSV) and is streamed as it is produced.

GET /api/me

Returns details about your key: validity dates, days left, limits, how many requests you have used today, and the data snapshot date. Calls to /api/me do not count against your quota.

{
  "key": { "name": "GIS lab project", "prefix": "gf_a1B2c3D", "valid_until": "2027-03-31T23:59:59.000Z", "days_left": 167 },
  "limits": { "daily_quota": 1000, "used_today": 42, "remaining_today": 958,
              "rate_per_minute": 30, "max_concurrent": 2, "max_timeout_seconds": 180 },
  "data": { "coverage": "India", "osm_snapshot": "2026-03-25T00:53:14Z" }
}

GET /health

Public, no key needed. Returns 200 {"status":"ok"} when the backend is answering, 503 otherwise.

Response headers

Limits & quotas

• Daily quota: counted per UTC day and resets at 00:00 UTC (05:30 IST).
• Rate limit: a rolling one-minute window.
• Concurrency: extra simultaneous queries are rejected, not queued. Wait for one to finish.
• Timeout: if your query has no [timeout:N], the server default (180 s, or your key's maximum if lower) applies. A larger timeout than your key allows is rejected with timeout_too_high.
• Memory: Overpass's own [maxsize:…] limit applies (512 MB by default). Very large extracts should be split into smaller areas.

The exact values for your key are in /api/me. If you need more, ask the administrator.

Overpass QL primer

Overpass QL is the query language of the Overpass API. The full reference is on the OSM wiki; this section covers what you need for most work.

Query structure

[out:json][timeout:60];        // settings: output format, time limit
(                               // union: collect results of several statements
  node["amenity"="hospital"](around:5000,16.4337,81.6966);
  way["amenity"="hospital"](around:5000,16.4337,81.6966);
);
out center tags;                // print results

Settings go first, in square brackets, ended by ;. Each statement ends with ;. Use nwr as a shortcut for "node, way and relation".

Filters

Areas & boundaries

To search inside a district, city or state, first find its boundary as an area, then filter by it:

[out:json][timeout:90];
area["boundary"="administrative"]["name"="West Godavari"]["admin_level"="5"]->.district;
nwr["amenity"="hospital"](area.district);
out center tags;

Tips: check the exact name and admin_level of a boundary first, since names can differ in spelling. Area queries are heavier than bounding-box or radius queries.

Output modes

Formats: [out:json], [out:xml] (default), or CSV with chosen columns: [out:csv(name, ::lat, ::lon, "addr:city"; true; ",")].

Agriculture recipes

Ready-to-run queries for common agricultural questions. Replace the coordinates (latitude, longitude) or bounding box (south, west, north, east) with your own area. Mapping density varies by region, so if a query returns little data, try a nearby area or a broader tag.

Farmland parcels around a village

[out:json][timeout:90];
way["landuse"="farmland"](around:5000,16.4337,81.6966);
out geom;

Crop-specific fields (paddy, sugarcane, cotton…)

[out:json][timeout:90];
nwr["landuse"="farmland"]["crop"~"rice|sugarcane|cotton"](16.2,81.4,16.7,82.0);
out center tags;

Orchards, plantations and vineyards

[out:json][timeout:90];
nwr["landuse"~"orchard|vineyard|plantation"](around:20000,19.9975,73.7898);
out center tags;

Irrigation canals, drains and ditches

[out:json][timeout:120];
way["waterway"~"canal|ditch|drain"](16.2,81.4,16.7,82.0);
out geom;

Tanks, ponds and reservoirs (with names) as CSV

[out:csv(::id, name, water, ::lat, ::lon; true; ",")][timeout:90];
nwr["natural"="water"]["water"~"pond|reservoir|tank|lake"](16.2,81.4,16.7,82.0);
out center;

Wells and water pumps

[out:json][timeout:60];
node["man_made"~"water_well|water_works|pumping_station"](around:10000,16.4337,81.6966);
out;

Aquaculture ponds (fish / prawn farming)

[out:json][timeout:90];
nwr["landuse"="aquaculture"](16.2,81.4,16.7,82.0);
out center tags;

Seed, fertiliser and pesticide shops

[out:json][timeout:60];
nwr["shop"~"agrarian|farm|garden_centre"](around:20000,16.3067,80.4365);
out center tags;

Market yards, mandis and weekly markets

[out:json][timeout:60];
nwr["amenity"="marketplace"](around:25000,16.4337,81.6966);
out center tags;

Warehouses, silos and cold storage

[out:json][timeout:90];
(
  nwr["man_made"="silo"](16.2,81.4,16.7,82.0);
  nwr["building"="warehouse"](16.2,81.4,16.7,82.0);
  nwr["industrial"~"warehouse|cold_storage"](16.2,81.4,16.7,82.0);
);
out center tags;

Veterinary clinics and dairies

[out:json][timeout:60];
(
  nwr["amenity"="veterinary"](around:25000,22.5645,72.928);
  nwr["craft"="dairy"](around:25000,22.5645,72.928);
  nwr["shop"="dairy"](around:25000,22.5645,72.928);
);
out center tags;

Farm tracks and village roads

[out:json][timeout:90];
way["highway"~"track|unclassified|tertiary"](around:5000,16.4337,81.6966);
out geom;

All villages in a district (for a village table)

[out:csv(::id, name, "name:te", ::lat, ::lon; true; ",")][timeout:180];
area["boundary"="administrative"]["name"="West Godavari"]["admin_level"="5"]->.d;
node["place"~"village|hamlet"](area.d);
out;

Village fact sheet: what is within 3 km?

[out:json][timeout:90];
(
  nwr["amenity"~"school|clinic|hospital|marketplace|veterinary|bank"](around:3000,16.4337,81.6966);
  nwr["shop"~"agrarian|farm"](around:3000,16.4337,81.6966);
  nwr["natural"="water"](around:3000,16.4337,81.6966);
);
out center tags;

General recipes

Hospitals and clinics within 5 km (with centre points)

[out:json][timeout:60];
nwr["amenity"~"hospital|clinic"](around:5000,16.4337,81.6966);
out center tags;

ATMs and banks in a bounding box

[out:json][timeout:25];
(
  node["amenity"="atm"](17.35,78.44,17.42,78.52);
  nwr["amenity"="bank"](17.35,78.44,17.42,78.52);
);
out center;

All schools in a district

[out:json][timeout:120];
area["boundary"="administrative"]["name"="West Godavari"]["admin_level"="5"]->.d;
nwr["amenity"="school"](area.d);
out center tags;

Road network with geometry

[out:json][timeout:90];
way["highway"~"motorway|trunk|primary|secondary"](16.35,81.60,16.50,81.80);
out geom;

Building footprints near a point

[out:json][timeout:60];
way["building"](around:500,16.4337,81.6966);
out geom;

Count restaurants in a city

[out:json][timeout:60];
nwr["amenity"="restaurant"](17.30,78.35,17.50,78.60);
out count;

Places with a Telugu name (CSV export)

[out:csv(::id, name, "name:te", ::lat, ::lon; true; ",")][timeout:60];
node["place"~"town|village"]["name:te"](16.2,81.4,16.7,82.0);
out;

Petrol pumps open 24 hours

[out:json][timeout:60];
nwr["amenity"="fuel"]["opening_hours"="24/7"](17.20,78.20,17.60,78.70);
out center tags;

State boundary outline

[out:json][timeout:180];
relation["boundary"="administrative"]["admin_level"="4"]["name"="Andhra Pradesh"];
out geom;

Bus stops along a route (relation members)

[out:json][timeout:60];
relation["route"="bus"](17.30,78.40,17.45,78.55);
node(r)["highway"="bus_stop"];
out;

Name search (case-insensitive)

[out:json][timeout:60];
nwr["name"~"swarnandhra",i];
out center tags;

Client code

curl (query in a file)

# save your query to query.overpassql, then:
curl -X POST https://api.geoflux.swarnandhra.ac.in/api/interpreter \
  -H "X-API-Key: $GEOFLUX_KEY" \
  --data-urlencode data@query.overpassql \
  -o result.json

Python (requests)

import os
import requests

GEOFLUX = "https://api.geoflux.swarnandhra.ac.in/api/interpreter"
KEY = os.environ["GEOFLUX_KEY"]

def overpass(query: str) -> dict:
    r = requests.post(GEOFLUX, headers={"X-API-Key": KEY}, data={"data": query}, timeout=300)
    if r.status_code == 429:
        raise RuntimeError(f"Limit reached, retry after {r.headers.get('Retry-After')} s")
    r.raise_for_status()
    return r.json()

data = overpass("""
[out:json][timeout:60];
nwr["amenity"="hospital"](around:5000,16.4337,81.6966);
out center tags;
""")
for el in data["elements"]:
    lat = el.get("lat") or el["center"]["lat"]
    lon = el.get("lon") or el["center"]["lon"]
    print(el["tags"].get("name", "(unnamed)"), lat, lon)

Python (pandas, from CSV output)

import io, os, requests, pandas as pd

q = '[out:csv(name, ::lat, ::lon; true; ",")][timeout:60];node["amenity"="school"](16.3,81.5,16.6,81.9);out;'
r = requests.post("https://api.geoflux.swarnandhra.ac.in/api/interpreter",
                  headers={"X-API-Key": os.environ["GEOFLUX_KEY"]}, data={"data": q})
df = pd.read_csv(io.StringIO(r.text))
print(df.head())

JavaScript (Node.js 18+ or server-side)

const res = await fetch("https://api.geoflux.swarnandhra.ac.in/api/interpreter", {
  method: "POST",
  headers: { "X-API-Key": process.env.GEOFLUX_KEY },
  body: new URLSearchParams({
    data: '[out:json][timeout:25];node["amenity"="pharmacy"](around:2000,17.385,78.4867);out;',
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const { elements } = await res.json();

R (httr2)

library(httr2)
resp <- request("https://api.geoflux.swarnandhra.ac.in/api/interpreter") |>
  req_headers(`X-API-Key` = Sys.getenv("GEOFLUX_KEY")) |>
  req_body_form(data = '[out:json];node["amenity"="college"](16.3,81.5,16.6,81.9);out;') |>
  req_perform()
elements <- resp_body_json(resp)$elements

Postman / Insomnia

Method POST, URL https://api.geoflux.swarnandhra.ac.in/api/interpreter, header X-API-Key, body type x-www-form-urlencoded with one field data containing your query.

GeoJSON & GIS

Overpass JSON is not GeoJSON, but converting is easy:

# Node.js
npm install -g osmtogeojson
curl -s -X POST https://api.geoflux.swarnandhra.ac.in/api/interpreter -H "X-API-Key: $GEOFLUX_KEY" \
  --data-urlencode 'data=[out:json];way["leisure"="park"](17.35,78.44,17.42,78.52);out geom;' \
  | osmtogeojson > parks.geojson

# Python
pip install osm2geojson
import osm2geojson
geojson = osm2geojson.json2geojson(data)   # data = Overpass JSON from the example above

The resulting .geojson files open directly in QGIS, ArcGIS, Leaflet, Mapbox, kepler.gl and geopandas (geopandas.read_file("parks.geojson")).

Tools that cannot send custom headers (some GIS plugins) can use the URL form https://api.geoflux.swarnandhra.ac.in/api/interpreter?key=YOUR_KEY, but only on trusted machines.

Errors

Gateway errors are JSON: {"error": {"code": "…", "message": "…"}}. Errors in the query itself come from Overpass, usually as HTTP 400 with an HTML/text explanation of the syntax problem.

Good practice

• Start small. Test on a small bounding box, then expand.
• Always set [timeout:N] to what your query really needs.
• Prefer around or a bounding box over named areas for speed.
• Request only what you need: out center or out tags instead of out geom when you only need locations.
• Cache results in your application; OSM data in GeoFlux changes only when the snapshot is updated.
• Back off on 429/502/504: wait for Retry-After and retry with exponential delay, never in a tight loop.
• Split large jobs (e.g. a whole state) into tiles or districts.

Licence & attribution

Data returned by GeoFlux comes from OpenStreetMap and is licensed under the Open Database License (ODbL) 1.0. You may use it for any purpose, including commercial, provided that you:

• Attribute: show "© OpenStreetMap contributors" wherever you display the data (maps, reports, apps, papers), with a link to openstreetmap.org/copyright.
• Share-alike: if you publish a modified database derived from the data, release it under the ODbL too.

Access to GeoFlux itself is governed by your institution's acceptable-use rules: keys are personal, must be used for the stated purpose, and may be revoked for misuse.

FAQ

Need help or a bigger quota? Contact the GeoFlux administrator.