Report Generation Guide

This comprehensive guide walks you through generating reports using the AquaGen API, from basic daily reports to advanced custom configurations.

🎯 Quick Start

Generate Your First Report

Let's start by generating a simple daily water consumption report in HTML format.

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=daily&\
reportFormat=html&\
service=water&\
startDate=09/11/2024" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"

What this does:

Generates a daily report for water consumption
Returns HTML output for browser display
Shows data for November 9, 2024

📊 Report Types Explained

1. Daily Reports

Best for: Daily operations, shift reports, compliance

Time Range: Single day (00:00 to 23:59)

Example Use Cases:

Daily consumption summary for management
Shift performance analysis
Daily compliance reports

How to Generate:

GET /api/user/report?reportType=daily&reportFormat=pdf&service=water&startDate=09/11/2024

Data Included:

Hourly breakdown
Total consumption
Min/max/average values
Shift-wise data (if configured)

Sample Output Structure:

Time	Consumption (KL)	Rate (L/min)
00:00-01:00	45.2	753
01:00-02:00	38.7	645
...	...	...
Total	1,245.6	Avg: 864

2. Monthly Reports

Best for: Billing, trend analysis, regulatory compliance

Time Range: Entire month (1st to last day)

Example Use Cases:

Monthly billing reports
Regulatory submissions
Month-over-month trend analysis

How to Generate:

GET /api/user/report?reportType=monthly&reportFormat=xlsx&service=energy&startDate=01/11/2024

Date Selection

For monthly reports, just specify the first day of the month. The system automatically calculates the month end.

Data Included:

Daily aggregates for entire month
Month-to-date totals
Peak usage analysis
Comparison with previous month

Sample Output Structure:

Date	Consumption (kWh)	Peak Demand (kW)	Cost (₹)
01/11/2024	3,456	245	24,192
02/11/2024	3,287	238	23,009
...	...	...	...
Total	98,765	Max: 278	₹6,91,355

3. Hourly Reports

Best for: Operational optimization, peak hour identification

Time Range: Multiple days with hourly breakdown

Example Use Cases:

Identify peak consumption hours
Optimize shift schedules
Troubleshoot operational issues

How to Generate:

GET /api/user/report?\
reportType=hourly&\
reportFormat=html&\
service=water&\
startDate=09/11/2024&\
endDate=10/11/2024&\
unitId=unit-123

Custom Time Range:

# Only business hours (9 AM to 5 PM)
&startTime=9&endTime=17

Data Included:

Hour-by-hour breakdown for each day
Hourly averages
Peak hour identification

4. Granular Reports

Best for: Detailed analysis, troubleshooting, pattern recognition

Time Range: Up to 7 days with 5-minute intervals

Example Use Cases:

Troubleshoot equipment issues
Identify micro-patterns
Detect anomalies

How to Generate:

GET /api/user/report?\
reportType=granular&\
reportFormat=csv&\
service=quality&\
startDate=09/11/2024&\
endDate=09/11/2024&\
unitId=unit-123

Data Volume

Granular reports contain 288 readings per day per unit. For multiple units over several days, use CSV format for better performance.

Data Included:

5-minute interval readings
288 data points per day
High-resolution trends

5. Custom Range Reports

Daily Range: Custom date range with daily aggregation

GET /api/user/report?\
reportType=daily_range&\
startDate=01/11/2024&\
endDate=07/11/2024&\
reportFormat=xlsx&\
service=water

Monthly Range: Custom date range with monthly aggregation

GET /api/user/report?\
reportType=monthly_range&\
startDate=01/01/2024&\
endDate=31/10/2024&\
reportFormat=pdf&\
service=energy

🎨 Output Formats

HTML Format

Best for: Web display, printing, quick review

Advantages:

✅ Fast generation
✅ Responsive design
✅ Print-optimized
✅ Interactive tables

How to Use:

?reportFormat=html

Opening in Browser:

curl -X GET "https://api.aquagen.com/api/user/report?..." \
-H "Authorization: Bearer TOKEN" \
> report.html

# Open in browser
open report.html  # macOS
xdg-open report.html  # Linux
start report.html  # Windows

PDF Format

Best for: Distribution, archiving, email attachments

Advantages:

✅ Professional formatting
✅ Portable and secure
✅ Print-ready
✅ Consistent rendering

How to Use:

?reportFormat=pdf

Saving PDF:

curl -X GET "https://api.aquagen.com/api/user/report?..." \
-H "Authorization: Bearer TOKEN" \
--output water_report.pdf

Features:

Page numbering
Headers and footers
Industry branding (logo, colors)
Charts and graphs

XLSX Format (Excel)

Best for: Data analysis, manipulation, pivot tables

Advantages:

✅ Editable spreadsheets
✅ Multiple worksheets
✅ Formulas and calculations
✅ Charts (optional)

How to Use:

?reportFormat=xlsx

Worksheet Structure:

📊 Report.xlsx
├── Summary        # Overview and totals
├── Detailed Data  # Full data table
├── Charts        # Visualizations (if applicable)
└── Metadata      # Report generation info

Opening in Excel:

curl -X GET "https://api.aquagen.com/api/user/report?..." \
-H "Authorization: Bearer TOKEN" \
--output report.xlsx

# Open in Excel
open report.xlsx  # macOS with Excel

CSV Format

Best for: Data export, system integration, analytics

Advantages:

✅ Universal compatibility
✅ Small file size
✅ Easy to parse programmatically
✅ Import into databases/analytics tools

How to Use:

?reportFormat=csv

Sample CSV:

Time,Source 1 (KL),Source 2 (KL),Total (KL)
00:00-01:00,12.5,8.3,20.8
01:00-02:00,11.2,7.9,19.1
...

Importing into Python:

import pandas as pd

df = pd.read_csv('report.csv')
print(df.describe())

🎛️ Advanced Configurations

Multi-Unit Reports

Generate reports for multiple units simultaneously:

GET /api/user/report?\
reportType=daily&\
reportFormat=pdf&\
service=water&\
startDate=09/11/2024&\
unitIds=unit-123,unit-456,unit-789

Output: Combined report with separate sections for each unit

Shift-Based Reports

Align reports with your operational shifts:

# Enable shift alignment
?useShift=true

Shift Configuration:

Industries can define custom shifts:

Shift A: 06:00 - 14:00
Shift B: 14:00 - 22:00
Shift C: 22:00 - 06:00

Shift Report Features:

Data aligned to shift boundaries
Shift-wise totals
Inter-shift comparisons

Division Factor

Customize unit display:

# Display in kiloliters (÷ 1000)
?divisionFactor=1000

# Display in megaliters (÷ 1,000,000)
?divisionFactor=1000000

Example:

Raw Value (L)	Division Factor	Display
1,245,678	1000	1,245.68 KL
1,245,678	1000000	1.25 ML

Sub-Category Filtering

Filter smart city reports by specific sources:

GET /api/user/report?\
service=smart_city&\
subCategories=municipal-water,groundwater&\
...

💼 Real-World Examples

Example 1: Daily Operations Report

Scenario: Generate daily water consumption report for operations team

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=daily&\
reportFormat=pdf&\
service=water&\
startDate=09/11/2024&\
useShift=true" \
-H "Authorization: Bearer YOUR_TOKEN" \
--output daily_operations_$(date +%Y%m%d).pdf

Example 2: Monthly Billing Report

Scenario: Generate monthly energy bill with detailed consumption

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=monthly&\
reportFormat=xlsx&\
service=energy&\
startDate=01/11/2024" \
-H "Authorization: Bearer YOUR_TOKEN" \
--output energy_bill_november_2024.xlsx

Example 3: Compliance Report

Scenario: Generate quality compliance report for regulatory submission

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=daily_range&\
reportFormat=pdf&\
service=quality&\
startDate=01/11/2024&\
endDate=30/11/2024&\
unitId=effluent-treatment-plant" \
-H "Authorization: Bearer YOUR_TOKEN" \
--output quality_compliance_nov_2024.pdf

Example 4: Troubleshooting with Granular Data

Scenario: Investigate water pressure issue on specific date

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=granular&\
reportFormat=csv&\
service=level&\
startDate=09/11/2024&\
endDate=09/11/2024&\
unitId=overhead-tank-1&\
startTime=10&\
endTime=14" \
-H "Authorization: Bearer YOUR_TOKEN" \
--output pressure_issue_analysis.csv

Example 5: Executive Summary

Scenario: Generate AI-powered executive summary

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=summary&\
reportFormat=pdf&\
service=aqua_gpt&\
startDate=01/11/2024&\
endDate=30/11/2024" \
-H "Authorization: Bearer YOUR_TOKEN" \
--output executive_summary_november.pdf

🔄 Automating Report Generation

Using Scripts

Bash Script for Daily Reports:

#!/bin/bash
# daily_report.sh

API_URL="https://api.aquagen.com/api/user/report"
TOKEN="YOUR_JWT_TOKEN"
DATE=$(date +%d/%m/%Y)
OUTPUT_FILE="daily_water_report_$(date +%Y%m%d).pdf"

curl -X GET "${API_URL}?\
reportType=daily&\
reportFormat=pdf&\
service=water&\
startDate=${DATE}" \
-H "Authorization: Bearer ${TOKEN}" \
--output "${OUTPUT_FILE}"

echo "Report generated: ${OUTPUT_FILE}"

Schedule with Cron:

# Generate report daily at 6 AM
0 6 * * * /path/to/daily_report.sh

Python Integration

import requests
from datetime import datetime

def generate_report(report_type, service, start_date, format='pdf'):
    url = "https://api.aquagen.com/api/user/report"

    params = {
        'reportType': report_type,
        'reportFormat': format,
        'service': service,
        'startDate': start_date
    }

    headers = {
        'Authorization': f'Bearer {YOUR_TOKEN}'
    }

    response = requests.get(url, params=params, headers=headers)

    if response.status_code == 200:
        filename = f"{service}_report_{start_date.replace('/', '')}.{format}"
        with open(filename, 'wb') as f:
            f.write(response.content)
        print(f"Report saved: {filename}")
    else:
        print(f"Error: {response.json()}")

# Generate today's report
today = datetime.now().strftime('%d/%m/%Y')
generate_report('daily', 'water', today, 'pdf')

Automated Report Service

Use the built-in automated report service:

bash scripts/auto_reports.sh

See Automated Reports Guide for details.

🎯 Best Practices

1. Choose the Right Report Type

Frequency	Report Type	Format
Daily operations	Daily	PDF/HTML
Weekly review	Daily Range (7 days)	XLSX
Monthly billing	Monthly	PDF/XLSX
Troubleshooting	Granular	CSV
Executive review	Summary	PDF

2. Optimize Date Ranges

✅ Use specific date ranges to minimize processing time
✅ For large periods, use monthly aggregation
✅ Use granular reports only for short periods (1-2 days)
✅ Consider time zones for accurate reporting

3. Format Selection

Purpose	Best Format
Email distribution	PDF
Web display	HTML
Data analysis	XLSX/CSV
Archiving	PDF
System integration	CSV

4. Performance Tips

🚀 Use CSV for large datasets
🚀 Generate reports during off-peak hours
🚀 Cache frequently accessed reports
🚀 Use specific unit IDs to reduce data volume

❓ Troubleshooting

Error: "No data found"

Cause: No sensor data available for the specified date range

Solutions:

Verify the date format (DD/MM/YYYY)
Check if devices were online during that period
Ensure the unit ID is correct
Try a different date range

Error: "Token expired"

Cause: JWT token has expired (4-hour lifetime)

Solution:

# Refresh your token
POST /api/user/refreshToken

Large File Sizes

Cause: Too much data in the report

Solutions:

Use CSV instead of PDF/XLSX
Reduce date range
Filter by specific units
Use monthly aggregation instead of daily

Slow Report Generation

Causes: Large date range, multiple units, complex calculations

Solutions:

Generate reports during off-peak hours
Use automated report scheduling
Split large reports into smaller chunks
Use appropriate aggregation levels

Next Steps

Learn about Automated Report Scheduling to generate and email reports automatically.

Reports API Reference - Complete API documentation
Report System Concepts - Understanding the report system
Automated Reports - Schedule reports via email

🎯 Quick Start​

Generate Your First Report​

📊 Report Types Explained​

1. Daily Reports​

2. Monthly Reports​

3. Hourly Reports​

4. Granular Reports​

5. Custom Range Reports​

🎨 Output Formats​

HTML Format​

PDF Format​

XLSX Format (Excel)​

CSV Format​

🎛️ Advanced Configurations​

Multi-Unit Reports​

Shift-Based Reports​

Division Factor​

Sub-Category Filtering​

💼 Real-World Examples​

Example 1: Daily Operations Report​

Example 2: Monthly Billing Report​

Example 3: Compliance Report​

Example 4: Troubleshooting with Granular Data​

Example 5: Executive Summary​

🔄 Automating Report Generation​

Using Scripts​

Python Integration​

Automated Report Service​

🎯 Best Practices​

1. Choose the Right Report Type​

2. Optimize Date Ranges​

3. Format Selection​

4. Performance Tips​

❓ Troubleshooting​

Error: "No data found"​

Error: "Token expired"​

Large File Sizes​

Slow Report Generation​

📚 Related Documentation​

🎯 Quick Start

Generate Your First Report

📊 Report Types Explained

1. Daily Reports

2. Monthly Reports

3. Hourly Reports

4. Granular Reports

5. Custom Range Reports

🎨 Output Formats

HTML Format

PDF Format

XLSX Format (Excel)

CSV Format

🎛️ Advanced Configurations

Multi-Unit Reports

Shift-Based Reports

Division Factor

Sub-Category Filtering

💼 Real-World Examples

Example 1: Daily Operations Report

Example 2: Monthly Billing Report

Example 3: Compliance Report

Example 4: Troubleshooting with Granular Data

Example 5: Executive Summary

🔄 Automating Report Generation

Using Scripts

Python Integration

Automated Report Service

🎯 Best Practices

1. Choose the Right Report Type

2. Optimize Date Ranges

3. Format Selection

4. Performance Tips

❓ Troubleshooting

Error: "No data found"

Error: "Token expired"

Large File Sizes

Slow Report Generation

📚 Related Documentation