Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ihfaz297/MND/llms.txt

Use this file to discover all available pages before exploring further.

​
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

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
​
distanceMatrix
object
Google Distance Matrix API integration status and usage statistics

​
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

MetricExpected ValueDescription
nodes19Total locations in the network
routes7Total 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

API Info

API version and endpoints list

Nodes

Verify node count

Bus Routes

Verify route count

Route Planning

Test core functionality

Build docs developers (and LLMs) love

Get started for freeTalk to us