FEATURE: Server-side aggregation endpoint for agency contract analytics

[MikeC-A6]

FEATURE: Server-side aggregation endpoint for agency contract analytics

Summary

The /api/agencies/{code}/contracts/awarding/ endpoint is limited to 100 results per request. For agencies with thousands of contracts (e.g., VA has 17,000+ in FY2024), client-side analytics only cover 0.57% of data, making vendor rankings and NAICS breakdowns unreliable.

Use Case

Users need accurate agency spending analytics for:

• Market sizing (total spend by NAICS code)
• Vendor landscape analysis (top vendors by obligated amount)
• Set-aside breakdowns (small business participation rates)

Currently, fetching 100 contracts ordered by -award_amount skews results toward large primes and misses small business activity entirely.

Current Limitation

• API limit: 100 contracts per request (max)
• VA FY2024: 17,483 contracts available, 100 analyzed = 0.57% sample
• Pagination exists but 175 API calls to get complete data is impractical
• No server-side aggregation endpoint exists (only /api/idvs/{id}/summary/ for IDV-specific data)

Proposed Solution

Add a dedicated aggregation endpoint, e.g.:

GET /api/agencies/{code}/contracts/analytics/
?fiscal_year=2024
&group_by=vendor|naics|psc|set_aside

Returns:

{
  "total_contracts": 17483,
  "total_obligated": 12500000000,
  "breakdown": [
    {"key": "541512", "label": "Computer Systems Design", "count": 2341, "obligated": 890000000},
    ...
  ]
}

This would eliminate the need for multi-page fetching and provide accurate analytics in a single request.