AR: no bulk/batch validation endpoint — clients processing large lists must serialize requests

[gregoryfoster]

Problem

Each /api/v1/validate request validates exactly one address. Callers processing large address lists (e.g., database backfills, batch geocoding) must either serialize requests one at a time or implement their own fan-out with rate limiting.

Opportunity

A POST /api/v1/validate/batch endpoint accepting a list of address inputs would:

• Allow clients to amortize HTTP overhead across many addresses
• Benefit disproportionately from the SQLite cache — many addresses in a batch are likely cache hits at near-zero marginal cost
• Be implementable with minimal new code by mapping the existing validate_address_v1 logic over a list

Design considerations

• Max batch size (e.g., 100 items) to prevent runaway requests
• Response shape: array of ValidateResponseV1 items, index-aligned with input
• Error handling: per-item errors or fail-fast?
• Rate limiting: batch counts as N provider calls toward the token bucket
• Cache interaction: batch lookups could be batched into fewer SQLite queries

Source

AR finding #9 (architectural review 2026-03-18).