API Reference

RESTful API endpoints for geospatial data access

Base URL

https://app.nuraan.space/api/v1

All API endpoints are prefixed with the base URL. The API uses standard HTTP response codes and returns JSON for all responses.

Health Check

System Health Status

GET
Endpoint
/health
Description

Returns the current health status of the API service and its database connections. Use this endpoint for monitoring and alerting.

Response Example
{
  "status": "ok",
  "service": "api",
  "environment": "production",
  "postgres_ok": true,
  "clickhouse_ok": true
}
Status Codes
200 Service healthy
503 Service degraded
Response Time
Typically < 50ms

Geographic Data

Administrative Areas

GET
Endpoint
/layers/admin_areas
Description

Returns GeoJSON FeatureCollection of administrative boundaries with population data. Supports bounding box filtering, pagination, and geometry simplification for performance.

Query Parameters
bbox
string
Bounding box: minLon,minLat,maxLon,maxLat
limit
integer
Max results (1-10000, default: 2000)
offset
integer
Skip results (default: 0)
simplify_tolerance
float
Geometry simplification (0.0001 recommended)
Response Example
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[90.123, 23.456], ...]]
      },
      "properties": {
        "admin_area_id": "BD.13.29.0001",
        "name": "Dhanmondi",
        "level": "ADM3",
        "population_baseline": 45000
      }
    }
  ]
}
Usage Example
# Fetch areas within Dhaka center with simplified geometry
curl "https://app.nuraan.space/api/v1/layers/admin_areas?\
bbox=90.35,23.70,90.45,23.80&\
simplify_tolerance=0.0001&\
limit=100"

Authentication

Current Status: Concept Model

The current deployment uses session-based authentication for the web interface. API authentication tokens will be implemented in the POC phase.

For demo access, contact: charles@fixedpoint.io

Rate Limiting & Best Practices

Rate Limits

  • • 1000 requests per hour per IP
  • • 100 concurrent connections
  • • 10MB max response size

Best Practices

  • • Use bbox filtering to limit data transfer
  • • Enable geometry simplification for web maps
  • • Implement client-side caching

Need Help with Integration?

Python and JavaScript SDK examples are available in the GitHub repository.

View on GitHub