GeoPop API Reference

API reference for the TerraGuard GeoPop service, providing reverse geocoding, population analysis, exposure assessment, and country lookups.

Overview

The GeoPop API is a high-performance Rust service that provides reverse geocoding, population density analysis, and disaster exposure assessment. Given geographic coordinates and a radius, it returns affected population estimates, country identification, and administrative region details.

Base URL: /api/v1

Authentication: X-API-Key header required on all endpoints except /health.

Response Envelope: All responses use a standard envelope format:

{
  "code": 200,
  "payload": { ... }
}

Endpoints

Analyse

GET /api/v1/analyse

Comprehensive analysis combining reverse geocoding, population exposure, and country data for a given point and radius.

Parameter	Type	Required	Description
`lat`	float	Yes	Latitude (-90 to 90)
`lon`	float	Yes	Longitude (-180 to 180)
`radius_km`	float	Yes	Analysis radius in kilometers

curl -H "X-API-Key: your-key" \
  "http://localhost:5605/api/v1/analyse?lat=20.88&lon=95.95&radius_km=100"

{
  "code": 200,
  "payload": {
    "location": {
      "country": "Myanmar",
      "country_iso3": "MMR",
      "admin1": "Mandalay Region",
      "admin2": "Meiktila District",
      "is_land": true
    },
    "population": {
      "total_exposed": 2450000,
      "density_per_km2": 78.3,
      "breakdown": {
        "0_10km": 125000,
        "10_50km": 890000,
        "50_100km": 1435000
      }
    },
    "nearby_countries": [
      {"country": "Thailand", "iso3": "THA", "distance_km": 280}
    ]
  }
}

Reverse Geocode

GET /api/v1/reverse

Returns location information for a coordinate pair.

Parameter	Type	Required	Description
`lat`	float	Yes	Latitude
`lon`	float	Yes	Longitude

curl -H "X-API-Key: your-key" \
  "http://localhost:5605/api/v1/reverse?lat=20.88&lon=95.95"

{
  "code": 200,
  "payload": {
    "country": "Myanmar",
    "country_iso3": "MMR",
    "admin1": "Mandalay Region",
    "admin2": "Meiktila District",
    "nearest_city": "Meiktila",
    "nearest_city_distance_km": 12.4,
    "is_land": true
  }
}

Exposure Assessment

GET /api/v1/exposure

Returns population exposure estimates for a disaster event centered at a point.

Parameter	Type	Required	Description
`lat`	float	Yes	Latitude
`lon`	float	Yes	Longitude
`radius_km`	float	Yes	Exposure radius in kilometers

curl -H "X-API-Key: your-key" \
  "http://localhost:5605/api/v1/exposure?lat=20.88&lon=95.95&radius_km=50"

{
  "code": 200,
  "payload": {
    "total_exposed": 1015000,
    "radius_km": 50,
    "breakdown": {
      "0_10km": 125000,
      "10_25km": 410000,
      "25_50km": 480000
    },
    "density_per_km2": 129.2
  }
}

Population Endpoints

Endpoint	Method	Description
`/api/v1/population`	GET	Population density at a coordinate (`lat`, `lon` params)
`/api/v1/population/batch`	POST	Population data for multiple points (JSON body with `points` array)

Single point response returns population_density and grid_resolution. Batch accepts up to 100 points per request.

Country Endpoints

Endpoint	Method	Description
`/api/v1/country`	GET	Country info for a coordinate (`lat`, `lon` params)
`/api/v1/country/{iso3}`	GET	Country details by ISO 3166-1 alpha-3 code
`/api/v1/countries`	GET	List all countries with basic metadata

curl -H "X-API-Key: your-key" \
  "http://localhost:5605/api/v1/country/MMR"

{
  "code": 200,
  "payload": {
    "country": "Myanmar",
    "iso3": "MMR",
    "iso2": "MM",
    "continent": "Asia",
    "region": "South-Eastern Asia",
    "population": 54410000,
    "area_km2": 676578
  }
}

Land Check

GET /api/v1/geocoding/land-check

Determines whether a coordinate is on land or water.

Parameter	Type	Required	Description
`lat`	float	Yes	Latitude
`lon`	float	Yes	Longitude

{
  "code": 200,
  "payload": {
    "is_land": true,
    "nearest_coast_km": 145.2
  }
}

Geocoding & Proximity Endpoints

Endpoint	Method	Params	Description
`/api/v1/geocoding/nearby-countries`	GET	`lat`, `lon`, `radius_km` (default 500)	Countries within radius
`/api/v1/geocoding/nearby-cities`	GET	`lat`, `lon`, `radius_km` (default 100), `limit` (default 10)	Cities near a point
`/api/v1/exposure/places`	GET	`lat`, `lon`, `radius_km`	Populated places in exposure radius, sorted by population

curl -H "X-API-Key: your-key" \
  "http://localhost:5605/api/v1/geocoding/nearby-cities?lat=20.88&lon=95.95&radius_km=100"

{
  "code": 200,
  "payload": {
    "cities": [
      {"name": "Meiktila", "distance_km": 12.4, "population": 252000},
      {"name": "Mandalay", "distance_km": 89.1, "population": 1225000}
    ]
  }
}

Health Check

GET /api/v1/health

No authentication required.

{
  "status": "healthy",
  "datasets_loaded": true,
  "population_grid": "loaded",
  "country_boundaries": "loaded"
}

Error Responses

{
  "code": 400,
  "payload": {
    "error": "Invalid coordinates: latitude must be between -90 and 90"
  }
}

Status Code	Description
400	Invalid parameters (out-of-range coordinates, missing required fields)
401	Missing or invalid API key
404	Country ISO3 code not found
500	Internal server error (dataset loading failure)

On this page