Archived: This repository is a historical academic artifact and is no longer actively maintained. It is public solely for reference purposes and is published without an open-source license. Public availability should not be interpreted as permission to use, modify, or redistribute the material.

PisAPI

PisAPI is the client-facing FastAPI service for the Bus PIS System. It exposes schedule data from PostgreSQL and real-time vehicle locations and arrival predictions from Redis.

Architecture

flowchart LR
       client[Client applications] --> api[PisAPI]
       api -->|locations and predictions| redis[(Redis)]
       api -->|schedule data| postgres[(PostgreSQL)]
       location[BusLocationHandler] -->|latest locations| redis
       prediction -->|arrival predictions| redis

Loading

API Endpoints

Use the interactive Swagger UI at /docs to inspect request parameters and response schemas, or to try requests against a running instance. FastAPI also exposes /redoc and /openapi.json.

Method	Path	Description
GET	/	Redirects to /docs with HTTP status 301. This route is excluded from the OpenAPI schema.
GET	/info	Returns the service name, version, description, and links to the main endpoint groups.
GET	/health	Returns service status, the UTC health-check timestamp, and API version.
GET	/v1/locations/route/{route_id}/{direction}	Returns the current locations of all vehicles on a route and direction, including coordinates, stop information, and update time. Data is read from Redis.
GET	/v1/predictions/route/{route_id}/{direction}	Returns the current arrival predictions for vehicles on a route and direction, including predicted stop arrival times, confidence values, and update times. Data is read from Redis.
GET	/v1/schedule/route/{route_id}/{direction}	Returns a route with its name and ordered stops, including stop IDs, names, sequence numbers, and coordinates.
GET	/v1/schedule/routes	Returns all available routes with their route IDs and names, without detailed stop data.
GET	/v1/schedule/stop_routes/{stop_id}	Returns a stop's name and coordinates, together with the routes, directions, and stop sequences serving it.

Configuration

Configuration is loaded from environment variables.

Common Settings

Variable	Default	Purpose
LOG_LEVEL	INFO	Logging level, including the custom TRACE level.
LOG_DIR	./logs	Directory for timestamped log files.
LOG_FILENAME_PREFIX	app	Prefix for log filenames.
POSTGRES_HOST	localhost	PostgreSQL hostname.
POSTGRES_PORT	5432	PostgreSQL port.
POSTGRES_USER	postgres	PostgreSQL username.
POSTGRES_PASSWORD	postgres	PostgreSQL password. Change this outside development.
POSTGRES_DB	bus_transit_system	PostgreSQL database name.
REDIS_HOST	redis_stack	Redis hostname.
REDIS_PORT	6379	Redis port.
REDIS_PASSWORD	empty	Redis password.
REDIS_DB	0	Redis database number.

API Settings

Variable	Default	Purpose
API_HOST	0.0.0.0	Configured API host value.
API_PORT	8003	Configured API port value.
BUS_LOCATION_REDIS_KEY_PREFIX	bus_location	Prefix for Redis location keys.
BUS_PREDICTION_REDIS_KEY_PREFIX	bus_prediction	Prefix for Redis prediction keys.