Real, unedited excerpts straight from the production source — the API contract you'd integrate against, a representative slice of the core resolution logic, and exactly what comes back out. Nothing here is a mockup.
Two endpoints. One crash at a time, or a whole CSV batch at once. Both return strongly-typed, documented shapes — not a loose bag of JSON.
app.MapPost("/api/v1/crash-locations", HandleAsync)
.WithName("ResolveCrashLocation")
.Produces<SpotMappingResponse>(StatusCodes.Status200OK)
.ProducesValidationProblem();
app.MapPost("/api/v1/crash-locations/batch", HandleBatchAsync)
.WithName("ResolveCrashLocationsBatch")
.Accepts<IFormFile>("multipart/form-data")
.Produces(StatusCodes.Status200OK, contentType: "text/csv")
.ProducesValidationProblem();
How to link to it — a single crash, from anything that can make an HTTP call:
# One crash coordinate in, one resolved location out.
curl -X POST https://<your-host>/api/v1/crash-locations \
-H "Content-Type: application/json" \
-d '{"crashKey":"223000016","latitude":41.256538,"longitude":-95.934502}'
# Same gateway-proxied pattern the evaluation UI uses under the hood. curl -X POST https://<your-host>/api/v1/crash-locations/batch \ -F "file=@crashes.csv" # Response: a CSV, one row per input row, ready to open in Excel.
The shape of a single request and response — plain, self-describing C# records:
/// Called either when a reviewer confirms the officer-submitted point as-is, or after they
/// click/drag a corrected point on the map.
public sealed record SpotMappingRequest(string CrashKey, double Latitude, double Longitude);
public sealed record SpotMappingResponse(
string CrashKey,
LocationResolutionMethod ResolutionMethod,
LinearReferenceLocation? LinearReference, // state-highway reference post answer
NearestReferenceFeatureLocation? NearestFeature, // local-road MMUCC answer
NearestMunicipalityContext? OutsideCityLimitsContext,
MireDataElementSet MireElements, // the full 20-element roadway dataset
ResolutionDiagnostics Diagnostics, // what succeeded, what degraded, and why
DateTimeOffset ResolvedAtUtc);
Every batch fans out to several outbound GIS calls per crash, run concurrently. This class caps how many are in flight at once — root-caused against a real production incident, not a guess — with a one-line switch to disable it entirely once this runs on trusted network infrastructure instead of the open internet.
/// THROTTLE, EXTERNAL TO THIS CODEBASE -- NOT A CORRECTNESS REQUIREMENT. /// /// Caps how many outbound GIS requests this process has in flight at once. This exists /// purely because of how this connection was treated on the open internet during testing -- /// it is not a property of the resolution logic itself, and whoever hosts this on trusted /// network infrastructure may not need it at all. Set MaxConcurrentGisRequests to 0 to /// disable it entirely, without touching this file. public sealed class ArcGisConcurrencyGate : IDisposable { private readonly SemaphoreSlim? _semaphore; public ArcGisConcurrencyGate(IOptions<ArcGisOptions> options) { var limit = options.Value.MaxConcurrentGisRequests; // 0 or negative = disabled: every EnterAsync below becomes a no-op immediately. _semaphore = limit > 0 ? new SemaphoreSlim(limit, limit) : null; } public async Task<IDisposable> EnterAsync(CancellationToken ct) { if (_semaphore is null) { return NoOpReleaser.Instance; } await _semaphore.WaitAsync(ct); return new Releaser(_semaphore); } }
Zero business logic in this file — it's pure operational resilience, built the same way as everything else: real incident, root-caused, documented, and switchable without a redeploy. That pattern shows up everywhere in this codebase, not just here.
Every resolved crash carries the full FHWA MIRE roadway dataset — not just a location. Elements this service can't authoritatively source say so, explicitly, instead of guessing:
/// Elements with no confirmed authoritative source layer (SurfaceType, FunctionalClass, MedianType, /// NumberOfThroughLanes) always report IsAvailable = false rather than being silently omitted. public sealed record MireDataElementSet( MireElement<string> SegmentIdentifier, MireElement<string> RouteNumber, MireElement<bool> RuralUrbanDesignation, MireElement<string> SurfaceType, // honestly Unavailable -- no source exists yet MireElement<int> Aadt, MireElement<string> GovernmentalOwnership, MireElement<int> SpeedLimitMph, // ...12 more elements: the 18 federally-required MIRE elements, plus 2 more MireElement<int> DotDistrictNumber);
A batch upload runs every row concurrently against live state GIS data, with a per-row safety timeout so one unresponsive lookup can't stall the whole file:
await Parallel.ForEachAsync(
Enumerable.Range(0, validRows.Count),
new ParallelOptions { MaxDegreeOfParallelism = BatchConcurrency, CancellationToken = ct },
async (i, innerCt) =>
{
using var rowCts = CancellationTokenSource.CreateLinkedTokenSource(innerCt);
rowCts.CancelAfter(PerRowTimeout); // one slow row degrades -- it never blocks the rest
try
{
var response = await spotMappingService.ResolveAsync(request, rowCts.Token);
resolved[i] = new BatchResultRow(row.RowNumber, row.CrashKey, ..., response);
}
catch (OperationCanceledException) when (!innerCt.IsCancellationRequested)
{
resolved[i] = new BatchResultRow(row.RowNumber, row.CrashKey, ...,
$"Resolution timed out after {PerRowTimeout.TotalSeconds:F0}s...", null);
}
});
The output file always has exactly one row per input row — a bad coordinate gets an error column, never a silently dropped row — and every one of the 20 MIRE elements is its own column, ready to open directly in Excel: