AUTOMATED SPATIAL INTELLIGENCE SYSTEM API – ALKF+

Modular geospatial intelligence platform for automated urban feasibility assessment. Converts raw geographic lot data into structured analytical maps and PDF reports via a cloud-deployed API.

Quick Start

Prerequisites

Python 3.11+
pip
Git

Installation

# Clone the repository
git clone https://github.com/your-org/automated-site-analysis-api.git
cd automated-site-analysis-api

# Install dependencies
pip install -r requirements.txt

# Start the development server
uvicorn app:app --host 0.0.0.0 --port 10000 --reload

The API will be available at http://localhost:10000.

Environment Variables

Variable	Description	Required	Default
`PORT`	Server port	No	`10000`
`LOG_LEVEL`	Logging verbosity (`debug`, `info`, `warning`)	No	`info`
`CACHE_ENABLED`	Enable in-memory result caching	No	`true`
`DPI`	Output image resolution	No	`200`

Your First Request

curl -X POST http://localhost:10000/walking \
  -H "Content-Type: application/json" \
  -d '{"lot_id": "IL 1657"}' \
  --output walking_analysis.png

System Architecture

End-to-End Processing Flow

flowchart TD

A[User Request - LOT ID] --> B[FastAPI Endpoint]
B --> C[Government GIS Resolver API]
C --> D[Coordinate Transformation EPSG 2326 → 4326 → 3857]

D --> E[Data Layer]

E --> E1[Zoning Dataset]
E --> E2[Building Height Dataset]
E --> E3[OpenStreetMap Extraction]

E --> F[Spatial Analysis Engine]

F --> F1[Walking Analysis]
F --> F2[Driving Analysis]
F --> F3[Transport Network]
F --> F4[Context Mapping]
F --> F5[View Sector Scoring]
F --> F6[Noise Modelling]

F --> G[Visualization Engine]

G --> H[PNG Output]
G --> I[PDF Report Generator]

H --> J[Streaming Response]
I --> J

Cloud Execution Flow

flowchart LR

Client --> Render
Render --> Uvicorn
Uvicorn --> FastAPI
FastAPI --> LoggingLayer
FastAPI --> CacheLayer
FastAPI --> Modules
Modules --> GeoPandas
Modules --> OSMnx
Modules --> StaticDatasets
FastAPI --> Output

Request Lifecycle

sequenceDiagram
    participant Client
    participant FastAPI
    participant Cache
    participant GIS Resolver
    participant Analysis Engine
    participant Visualizer

    Client->>FastAPI: POST /walking { lot_id }
    FastAPI->>Cache: Check lot_id cache
    alt Cache Hit
        Cache-->>FastAPI: Cached PNG
        FastAPI-->>Client: 200 PNG (< 1s)
    else Cache Miss
        FastAPI->>GIS Resolver: Resolve lot_id → coordinates
        GIS Resolver-->>FastAPI: EPSG:2326 coordinates
        FastAPI->>Analysis Engine: Run spatial analysis
        Analysis Engine-->>FastAPI: GeoDataFrames + metrics
        FastAPI->>Visualizer: Render map
        Visualizer-->>FastAPI: PNG buffer
        FastAPI->>Cache: Store result
        FastAPI-->>Client: 200 PNG (5–10s)
    end

Repository Structure

Automated-Site-Analysis-API/
│
├── app.py                    # FastAPI entrypoint, route definitions, cache + logging init
├── render.yaml               # Render cloud deployment config
├── requirements.txt
├── runtime.txt
│
├── data/
│   ├── BUILDINGS_FINAL.gpkg  # Optimized building footprint dataset (42k rows, EPSG:3857)
│   └── ZONE_REDUCED.gpkg     # Zoning dataset (reduced attributes, EPSG:3857)
│
├── images/
│   └── alkf-logo.png
│
├── static/
│   └── HK_MTR_logo.png
│
└── modules/
    ├── context.py            # Land-use and amenity mapping
    ├── driving.py            # Vehicular isochrone analysis
    ├── noise.py              # Road traffic noise propagation
    ├── resolver.py           # LOT ID → coordinate resolution
    ├── transport.py          # Public transit accessibility
    ├── view.py               # 360° view sector classification
    └── walking.py            # Pedestrian network analysis

Module Breakdown

`resolver.py` — Multi-Type Input Resolver

Translates a human-readable lot identifier (e.g. IL 1657) into usable spatial coordinates via the government GIS API.

Transformation pipeline:

POST lot ID to Government GIS Resolver API
Receive raw EPSG:2326 (Hong Kong Grid) coordinates
Reproject → EPSG:4326 (WGS84) for OSM queries
Reproject → EPSG:3857 (Web Mercator) for internal spatial analysis

Error handling: Returns 422 Unprocessable Entity if the lot ID cannot be resolved (invalid format, unknown lot).

`walking.py` — Pedestrian Accessibility Analysis

Evaluates walkability and proximity to amenities from the site centroid.

Method:

Extract walk graph from OSMnx within a configurable radius (default: 1,200 m)
Snap lot centroid to nearest node
Run Dijkstra shortest-path routing to all reachable amenity nodes
Classify amenities by type (food, health, education, retail, recreation)
Generate 5-minute and 10-minute isochrone buffers
Render choropleth map with amenity cluster overlays

Key parameters:

Parameter	Default	Description
Walk speed	1.39 m/s	Standard pedestrian speed (5 km/h)
Graph radius	1,200 m	OSMnx extraction radius
Time thresholds	5 min, 10 min	Isochrone bands

`driving.py` — Vehicular Connectivity Analysis

Assesses road network reach and efficiency from the site.

Method:

Extract drive-mode graph from OSMnx
Assign travel-time weights to edges based on posted speed limits
Compute isochrones at 5, 10, and 20-minute thresholds
Calculate betweenness centrality to identify key road corridors

Output: Isochrone polygon map overlaid on a contextual basemap with centrality heatmap.

`transport.py` — Public Transit Accessibility

Scores the site's proximity to and density of public transit infrastructure.

Method:

Query OSM for bus stops and MTR/rail stations within 800 m
Compute transit node density per unit area
Score route diversity (number of distinct routes within walking distance)
Render node markers scaled by route count

Scoring:

Transit Score = 0.5 × (node_density_norm) + 0.5 × (route_diversity_norm)

`context.py` — Land-Use & Zoning Mapping

Provides a spatial overview of the surrounding land-use environment.

Layers rendered:

Zoning overlay (from ZONE_REDUCED.gpkg)
Amenity point distribution (OSM)
Green space polygons (parks, recreational areas)
Building footprint density heatmap
Road network classification (motorway → footway)

`view.py` — 360° View Classification Engine

Classifies the visual environment from the site across all directions.

Methodology:

Divide 360° into N equal sectors (default: 36 × 10° sectors)
For each sector, extract:
- Green ratio — proportion of OSM green space within sightlines
- Water ratio — proportion of water bodies within sightlines
- Building density — count of building footprints
- Average building height — from HEIGHT_M field in BUILDINGS_FINAL.gpkg
Normalize all features to [0, 1]
Apply composite scoring model (see below)
Merge adjacent sectors sharing the same dominant view type

Scoring Model:

Green Score  = green_ratio
Water Score  = water_ratio
City Score   = height_norm × density_norm
Open Score   = (1 - density_norm) × (1 - height_norm)

Each sector is labelled with the highest-scoring view type:

Label	Condition
`GREEN VIEW`	Dominant green_ratio
`WATER VIEW`	Dominant water_ratio
`CITY VIEW`	High density + high height
`OPEN VIEW`	Low density + low height

Output: Polar sector diagram with colour-coded view classifications.

`noise.py` — Road Traffic Noise Propagation Model

Simulates noise levels across the surrounding area based on road type and traffic volume.

Base propagation model:

L = L₀ − 20 log₁₀(r)

Where:

L₀ — Source emission level (dB), assigned per road class
r — Distance from source (m)

Source emission levels by road class:

Road Class	L₀ (dB)
Motorway	78
Primary	72
Secondary	68
Tertiary	64
Residential	58

Extended correction factors:

Heavy vehicle correction — +3 dB for motorway/primary roads
Barrier attenuation — building mass reduces propagation across facades
Ground absorption — soft ground surfaces reduce propagation by up to 3 dB
Reflection adjustment — hard surfaces (streets, plazas) add +1–2 dB

Output: 50 m × 50 m grid-based noise heatmap (dB scale) with road network overlay.

API Reference

Base URL

https://automated-site-analysis-api.onrender.com

Authentication

No authentication required (current version). See Future Enhancements for planned auth layer.

Request Format

All endpoints accept POST with Content-Type: application/json.

{
  "lot_id": "IL 1657"
}

Lot ID formats accepted:

Format	Example
Inland Lot	`IL 1657`
New Kowloon Inland Lot	`NKIL 6304`
New Territories Lot	`DD 123 LOT 456`

Endpoints

`POST /walking`

Returns a pedestrian accessibility map.

Request:

{ "lot_id": "IL 1657" }

Response: 200 OK — PNG image stream (Content-Type: image/png)

Errors:

Code	Reason
`422`	Invalid or unresolvable lot ID
`500`	OSMnx graph extraction failed (network timeout or empty graph)
`503`	Government GIS API unavailable