Backend API Reference¶
App Entrypoint¶
Request and Response Schemas¶
Pydantic schemas for API payloads, GeoJSON documents, and HATEOAS metadata.
FireRiskRequest
¶
Bases: BaseModel
Request model for fire risk prediction.
Link
¶
Bases: BaseModel
HATEOAS link object used in _links collections.
FireRiskResponse
¶
Bases: BaseModel
Response model for fire risk prediction.
MonitoredZoneSchema
¶
Bases: BaseModel
Schema for a monitored zone.
RiskLevel
¶
Bases: BaseModel
Describes a single level of risk.
RiskLegend
¶
Bases: BaseModel
Provides a key for interpreting risk scores and categories.
FireRiskReadingSchema
¶
Bases: BaseModel
Schema for a fire risk reading.
The database model uses location_name for the stored geohash; allow
location_name as an alias so Pydantic can validate SQLAlchemy objects
without requiring changes to the DB models.
SubscriptionRequest
¶
Bases: BaseModel
Request model for user subscription.
SubscriptionResponse
¶
Bases: BaseModel
Response model for user subscription.
UserSubscriptionListResponse
¶
Bases: BaseModel
Response model for listing a user's subscriptions.
GeoJSONGeometry
¶
Bases: BaseModel
GeoJSON geometry object used by zone and history features.
GeoJSONProperties
¶
Bases: BaseModel
Properties payload for each GeoJSON zone feature.
GeoJSONFeature
¶
Bases: BaseModel
GeoJSON feature representing one monitored zone.
GeoJSONFeatureCollection
¶
Bases: BaseModel
GeoJSON feature collection wrapper returned by zone/subscription APIs.
Routers¶
Risk endpoints for latest readings and historical time series.
get_risk_history(request, geohash, start_date=Query(None, description='Start date for the history (ISO 8601 format).Defaults to the beginning of time.'), end_date=Query(None, description='End date for the history (ISO 8601 format).Defaults to the present.'), db=Depends(get_db), user=Depends(get_current_user))
async
¶
Return historical fire-risk readings for one geohash.
The endpoint is authenticated and returns a collection enriched with risk legend metadata and HATEOAS navigation links.
get_risk_by_coords(request, latitude, longitude, db=Depends(get_db), user=Depends(get_current_user_optional))
async
¶
Return the latest fire-risk reading for a latitude/longitude pair.
Authentication is optional; authenticated users also receive subscription and history links in the response.
get_risk_by_geohash(request, geohash, db=Depends(get_db), user=Depends(get_current_user_optional))
async
¶
Return the latest fire-risk reading for a specific geohash.
Authentication is optional; authenticated users receive additional HATEOAS links to subscription and history endpoints.
Zone discovery and regional history endpoints.
get_zones(request, db=Depends(get_db))
async
¶
Return all regional monitored zones as a GeoJSON feature collection.
get_zones_history(request, db=Depends(get_db), geohashes=Query(None, description='Comma-separated string of geohashes to filter by. If omitted, returns history for all regional zones.'), start_date=Query(None, description='Start date for the history (ISO 8601 format).'), end_date=Query(None, description='End date for the history (ISO 8601 format).'))
async
¶
Return historical risk readings for regional zones or selected geohashes.
The endpoint is public. If geohashes is omitted, data is scoped to
predefined regional zones.
Authenticated subscription endpoints and SSE updates for user locations.
create_subscription(request, payload, db=Depends(get_db), user=Depends(get_current_user))
async
¶
Create a monitored-location subscription for the current user.
get_my_subscriptions(request, db=Depends(get_db), user=Depends(get_current_user))
async
¶
Return all active subscriptions for the current user as GeoJSON.
delete_subscription(geohash, db=Depends(get_db), user=Depends(get_current_user))
async
¶
Delete one subscription for the authenticated user.
stream_subscription_updates(geohash, user=Depends(get_current_user_ws_or_sse))
async
¶
Stream fire-risk updates for a geohash over Server-Sent Events (SSE).
Global historical readings endpoint for regional and filtered queries.
get_zones_history(request, db=Depends(get_db), geohashes=Query(None, description='Comma-separated string of geohashes to filter by. If omitted, returns history for all regional zones.'), start_date=Query(None, description='Start date for the history (ISO 8601 format).'), end_date=Query(None, description='End date for the history (ISO 8601 format).'))
async
¶
Return historical fire-risk readings for regional or selected zones.
This endpoint returns the normalized FireRiskReadingSchema collection
enriched with legend metadata and HATEOAS links.
Services¶
Risk service helpers for current-risk lookups and fallback scoring.
calculate_fire_risk_logic(payload)
¶
Compute a simplified fire-risk score from weather parameters.
This is a lightweight fallback/illustrative calculation, not the production intelligence pipeline model.
get_latest_risk_reading(db, geohash)
async
¶
Get the latest fire risk reading for a specific geohash from the CurrentFireRisk table.
get_latest_risk_by_coords(db, latitude, longitude)
async
¶
Get the latest fire risk reading for given coordinates by converting to a geohash and reusing the geohash lookup.
get_historical_readings(db, geohashes=None, start_date=None, end_date=None)
async
¶
Retrieves historical fire risk readings from the database, with flexible filtering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
db
|
AsyncSession
|
The database session. |
required |
geohashes
|
Optional[List[str]]
|
An optional list of geohashes to filter by. If None, it will default to all regional zones. |
None
|
start_date
|
Optional[datetime]
|
The start of the date range. |
None
|
end_date
|
Optional[datetime]
|
The end of the date range. |
None
|
Returns:
| Type | Description |
|---|---|
Sequence[FireRiskReading]
|
A sequence of historical fire risk readings. |
get_historical_readings_by_geohash(db, geohash, start_date=None, end_date=None)
async
¶
A convenience wrapper to get historical readings for a single geohash.
process_hourly_data_ready_event()
async
¶
Main orchestration function triggered by the HOURLY_DATA_READY Redis event.
process_mqtt_alerts(db)
async
¶
Finds geohashes with active user subscriptions that are in High or Extreme risk, and publishes MQTT alerts for them.
process_thingspeak_analytics(db)
async
¶
Pushes fire risk analytics with fixed ThingSpeak mapping: field1..field7 city risk_score, field8 national average. to a ThingSpeak channel.
backfill_thingspeak_last_24h(hours=24)
async
¶
Push historical hourly analytics for the last 24h so the ThingSpeak channel has immediate chart history after deployment/startup.
Data Layer¶
create_db_and_tables()
async
¶
Creates the database and tables if they do not exist.
Includes retry logic to handle timing issues where the database container is healthy but not yet accepting connections.
get_monitored_zones()
async
¶
Returns all active monitored zones.
get_db()
async
¶
Dependency for getting an async database session.
Base
¶
Bases: DeclarativeBase
Base class for all database models, providing a common metadata store.