Health Check

System health status, statistics, and monitoring

Overview

The health check endpoint provides real-time system status, graph statistics, and API usage metrics. Use this for monitoring, debugging, and verifying system availability.

Get System Health

Request

GET /api/health

Response Fields

status · string

Overall system health status

• healthy: System is operational
• unhealthy: System has errors

timestamp · string

ISO 8601 timestamp of the health check

graph · object

Graph data statistics

Show properties

nodes · number

Total number of locations in the network (should be 19)

routes · number

Total number of bus routes (should be 7)

distanceMatrix · object

Google Distance Matrix API integration status and usage statistics

Show properties

available · boolean

Whether the Distance Matrix API key is configured

usage · object

API quota usage

Show properties

monthly · string

Monthly usage in format “used/limit” (limit: 700)

daily · string

Daily usage in format “used/limit” (limit: 25)

cache · object

Cache performance metrics

Show properties

hits · number

Number of cache hits (requests served from cache)

misses · number

Number of cache misses (new API requests)

hitRate · string

Cache hit rate percentage

System Status Values

Healthy

All systems operational:

{
  "status": "healthy",
  "graph": {
    "nodes": 19,
    "routes": 7
  }
}

Unhealthy

System error detected:

{
  "status": "unhealthy",
  "error": "Failed to load graph data"
}

Graph Statistics

The graph object provides information about the transportation network:

Expected Values

Metric	Expected Value	Description
nodes	19	Total locations in the network
routes	7	Total bus routes (bus1 through bus7)

Verifying Data Integrity

If the counts don’t match expected values, the graph data may not have loaded correctly:

# Check health
curl http://localhost:3000/api/health | jq '.graph'

# Expected output:
# {
#   "nodes": 19,
#   "routes": 7
# }

Distance Matrix Monitoring

API Availability

{
  "distanceMatrix": {
    "available": true
  }
}

• true: Google Distance Matrix API key is configured (env: GOOGLE_DM_API_KEY)
• false: API key not configured, local transport calculations may be limited

Usage Tracking

The API tracks usage to avoid exceeding Google’s quota:

Monthly Limit: 700 requests

{
  "usage": {
    "monthly": "145/700"
  }
}

Daily Limit: 25 requests

{
  "usage": {
    "daily": "23/25"
  }
}

When approaching limits (>90%), consider:

• Reviewing cache efficiency
• Reducing local transport calculations
• Upgrading Google Cloud billing plan

Cache Performance

The cache stores Distance Matrix results to minimize API calls:

{
  "cache": {
    "hits": 456,
    "misses": 145,
    "hitRate": "76%"
  }
}

Interpreting Cache Metrics:

• High Hit Rate (above 70%): Good cache utilization, most requests served from cache
• Medium Hit Rate (40-70%): Moderate efficiency, some new routes being calculated
• Low Hit Rate (below 40%): Many unique routes, consider increasing cache size

Monitoring & Alerting

Health Check Monitoring

#!/bin/bash
# health-monitor.sh

STATUS=$(curl -s http://localhost:3000/api/health | jq -r '.status')

if [ "$STATUS" != "healthy" ]; then
  echo "⚠️ API is unhealthy!"
  # Send alert (email, Slack, etc.)
  exit 1
fi

echo "✓ API is healthy"

Quota Monitoring

#!/bin/bash
# quota-monitor.sh

HEALTH=$(curl -s http://localhost:3000/api/health)
DAILY=$(echo $HEALTH | jq -r '.distanceMatrix.usage.daily')
USED=$(echo $DAILY | cut -d'/' -f1)
LIMIT=$(echo $DAILY | cut -d'/' -f2)

USAGE_PCT=$((100 * $USED / $LIMIT))

if [ $USAGE_PCT -gt 90 ]; then
  echo "⚠️ Daily quota at ${USAGE_PCT}%"
  # Send alert
fi

Cache Performance Tracking

#!/bin/bash
# cache-monitor.sh

HEALTH=$(curl -s http://localhost:3000/api/health)
HIT_RATE=$(echo $HEALTH | jq -r '.distanceMatrix.cache.hitRate' | tr -d '%')

if [ $HIT_RATE -lt 50 ]; then
  echo "⚠️ Low cache hit rate: ${HIT_RATE}%"
  # Consider investigating cache configuration
fi

Usage in Load Balancers

Use the health endpoint for load balancer health checks:

Nginx

upstream mnd_api {
    server localhost:3000;
    
    # Health check
    check interval=3000 rise=2 fall=3 timeout=1000;
    check_http_send "GET /api/health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx;
}

Docker Compose

services:
  api:
    image: mnd-api:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Kubernetes

apiVersion: v1
kind: Pod
metadata:
  name: mnd-api
spec:
  containers:
  - name: api
    image: mnd-api:latest
    livenessProbe:
      httpGet:
        path: /api/health
        port: 3000
      initialDelaySeconds: 15
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /api/health
        port: 3000
      initialDelaySeconds: 5
      periodSeconds: 5

Startup Verification

The API logs health information on startup:

🚌 University Bus Routing API

Loading graph data...
✓ Loaded 19 nodes, 58 edges, 7 routes

✓ Server running on http://localhost:3000
✓ Network access: http://192.168.1.100:3000

Verify immediately after startup:

curl http://localhost:3000/api/health | jq '.graph'

# Should return:
# {
#   "nodes": 19,
#   "routes": 7
# }

Troubleshooting

Graph Not Loaded

{
  "status": "unhealthy",
  "error": "Graph not initialized"
}

Solution: Check that data files exist:

ls -la src/data/
# Should see: nodes.json, edges.json, routes.json

Distance Matrix Unavailable

{
  "distanceMatrix": {
    "available": false
  }
}

Solution: Configure Google Distance Matrix API key:

echo "GOOGLE_DM_API_KEY=your-api-key-here" >> .env

Low Cache Hit Rate

{
  "cache": {
    "hitRate": "15%"
  }
}

Possible Causes:

• Users requesting many unique routes
• Cache cleared recently
• Cache file corrupted or missing

Solution: Check cache file:

ls -la src/data/distance_cache.json

Related Endpoints

API Info

API version and endpoints list

Nodes

Verify node count

Bus Routes

Verify route count

Route Planning

Test core functionality