GeoPop API

Overview

The geopop-api is a high-performance Rust service that provides geospatial intelligence for the TerraGuard platform. It handles reverse geocoding, population density analysis, disaster exposure assessments, land/sea detection, and country boundary lookups. The service is critical for determining the human impact of disaster events -- answering questions like "How many people live within 50km of this earthquake?"

The service runs on port 5605 and is deployed as a Docker image (theekshana2/geopop-api). Source code lives in the TerraGuard/tg-geo-pop repository.

Architecture

Key Features

Population Exposure Assessment

The /analyse endpoint performs auto-expanding radius searches to estimate disaster impact. Given a coordinate and event type, it:

1. Starts with a small radius and expands outward
2. Counts population within the affected area using high-resolution population grids
3. Returns population breakdowns by distance band
4. Considers event type -- earthquakes use different radii than floods

Batch Population Queries

The /population/batch endpoint accepts up to 1000 coordinates in a single request and returns population estimates for each point. This is used during event ingestion to quickly assess affected areas without making hundreds of individual API calls.

Land/Sea Detection

The /geocoding/land-check endpoint determines whether a coordinate is on land or at sea. This is important for maritime disaster events (e.g., earthquakes in the ocean, tropical cyclones over water) where population exposure calculations differ significantly.

Country Identification

Multiple endpoints support country-level analysis:

• /geocoding/nearby-countries -- Find countries within a radius of a coordinate
• /geocoding/reverse -- Get the country and administrative regions for a coordinate
• Country boundary polygon lookups for spatial containment queries

Configuration

API Endpoints

The service exposes 13 endpoints under /api/v1:

Analysis

Geocoding

Population

Countries

Health

Example: Analyse Request

{
  "lat": 37.7749,
  "lon": 29.0875,
  "event_type": "EARTHQUAKE",
  "magnitude": 6.5
}

Example: Analyse Response

{
  "location": {
    "lat": 37.7749,
    "lon": 29.0875,
    "country": "Turkey",
    "country_code": "TR",
    "is_land": true
  },
  "exposure": {
    "radius_km": 50,
    "total_population": 284500,
    "bands": [
      { "radius_km": 10, "population": 45000 },
      { "radius_km": 25, "population": 125000 },
      { "radius_km": 50, "population": 284500 }
    ]
  },
  "nearby_countries": ["TR"]
}

Example: Batch Population

{
  "coordinates": [
    { "lat": 37.7749, "lon": 29.0875 },
    { "lat": 35.6762, "lon": 139.6503 }
  ],
  "radius_km": 25
}

Directory Structure

tg-geo-pop/
├── src/
│   ├── main.rs                 # Entry point and HTTP server setup
│   ├── api/
│   │   ├── mod.rs              # Route registration
│   │   ├── analyse.rs          # Impact analysis endpoints
│   │   ├── exposure.rs         # Exposure assessment
│   │   ├── geocoding.rs        # Reverse geocoding, land check
│   │   ├── population.rs       # Population queries
│   │   └── countries.rs        # Country lookup endpoints
│   ├── geo/
│   │   ├── population.rs       # Population grid processing
│   │   ├── country.rs          # Country boundary operations
│   │   └── land_sea.rs         # Land/sea mask operations
│   └── config.rs               # Configuration
├── data/                       # Geospatial data files
│   ├── population/             # Population raster grids
│   ├── countries/              # Country boundary polygons
│   └── land_sea/               # Land/sea mask data
├── Dockerfile
└── Cargo.toml

Running

The GeoPop API is typically run as a Docker container because it requires large geospatial data files that are bundled in the image:

# Pull and run the Docker image
docker run -p 5605:5605 theekshana2/geopop-api:latest

# Health check
curl http://localhost:5605/api/v1/health

For local development, refer to the TerraGuard/tg-geo-pop repository.

Performance

The Rust implementation provides:

• Sub-millisecond reverse geocoding lookups
• Batch population queries processing 1000 coordinates in under 500ms
• Efficient memory-mapped geospatial raster data
• Minimal resource footprint suitable for single-instance deployment