Quick Start & API Guide

Get started with the Bishkek 3D Urban Analytics web platform, spatial REST APIs, and the Python FastAPI crawler microservice.

1. Interactive 3D Map Workspace

Open the 3D Map to explore Bishkek across all four administrative rayons:

• Thematic Shader Modes: Switch between Architectural Dark (Obsidian), Price per m² Choropleth, Building Typology & Series, Construction Stage, and School Deficit Isochrones.
• 60 FPS Floor Slicing: Drag the Cutoff Elevation slider (0m – 75m) to slice high-rise towers horizontally and inspect interior floor levels.
• Camera Presets: Jump directly to Downtown (Golden Square), Asanbay, Dzhal, Vostok-5, or Overview.

2. Geospatial REST & Vector Tile APIs

All spatial endpoints are backed by PostgreSQL + PostGIS (extensions.ST_DWithin, extensions.ST_AsMVT):

GET /api/buildings

Returns a GeoJSON FeatureCollection of surveyed 3D buildings in Bishkek with extruded heights, levels, construction stage, developer metadata, and active listing averages.

curl "https://house-data-web.vercel.app/api/buildings?rayon=Oktyabrsky&min_levels=9"

GET /api/buildings/{id}

Returns full building specifications, floor plate breakdowns, active listings from verified real estate portals, and nearest schools, kindergartens, and retail POIs within a 1.2km geodesic buffer.

GET /api/analytics

Returns city-wide KPIs, average price per m² by rayon, room-count inventory distributions, developer market share leaderboards, and school/kindergarten capacity deficit ratios.

GET /api/tiles/{z}/{x}/{y}

Serves binary Mapbox Vector Tiles (application/vnd.mapbox-vector-tile) generated directly in PostGIS via ST_AsMVT.

3. AI Spatial Co-Pilot (POST /api/copilot)

Send natural language queries in English, Russian, or Kyrgyz to execute parameterized spatial tools (query_spatial_database, orchestrate_viewport, generate_comparison_analysis):

curl -X POST "https://house-data-web.vercel.app/api/copilot" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What is the average price per sqm in Asanbay?"}]}'

4. Python FastAPI Crawler (services/crawler)

The crawler microservice ingests property listings and performs multi-tier Cyrillic/Latin address entity resolution against PostGIS buildings:

• POST /api/crawl — Trigger a live or dry-run scrape job.
• POST /api/resolve/address — Resolve a raw listing address (e.g., "мкр. Асанбай, д. 28") to a PostGIS building_id and coordinates.
• GET /api/stats — View crawler pipeline throughput and entity resolution confidence scores.