Sportstime/SportsTime/Core/EVChargingFeature.md

EV Charging Feature

Overview

When FeatureFlags.enableEVCharging = true, the app discovers EV charging stations along planned trip routes using Apple's MapKit APIs.

Feature Flag

// SportsTime/Core/FeatureFlags.swift
enum FeatureFlags {
    static let enableEVCharging = false  // Set to true to enable
}

API Calls

1. MKDirections (Route Calculation)

Purpose: Get actual driving route polylines between stops

When called: After trip planning completes, for each travel segment

Call pattern:

• 1 call per travel segment (city-to-city)
• A 5-city trip = 4 MKDirections calls

Response includes:

• Route polyline (used for EV charger search)
• Actual driving distance (replaces Haversine estimate)
• Expected travel time

2. MKLocalPointsOfInterestRequest (EV Charger Search)

Purpose: Find EV charging stations near sample points along the route

When called: For each sample point along the route polyline

Call pattern:

• Routes are sampled every 100 miles
• Each sample point triggers 1 POI search
• 5-mile search radius around each point

Example:

Route Distance	Sample Points	POI Searches
100 miles	2 (start+end)	2 calls
300 miles	4	4 calls
500 miles	6	6 calls

Total API Overhead

Per Travel Segment

1 MKDirections call + (distance_miles / 100) MKLocalSearch calls

Example: Boston → New York → Philadelphia → Washington DC

Segment	Distance	MKDirections	POI Searches	Total
BOS→NYC	215 mi	1	3	4
NYC→PHL	95 mi	1	2	3
PHL→DC	140 mi	1	2	3
Total		3	7	10 calls

Performance Impact

Latency Added to Trip Planning

Component	Time per Call	Notes
MKDirections	200-500ms	Network round-trip
MKLocalSearch (POI)	100-300ms	Per sample point

Typical overhead: 2-5 seconds added to trip planning

Parallel Processing

• All travel segments are enriched in parallel (using Swift TaskGroup)
• POI searches within a segment are sequential (to avoid rate limiting)

Rate Limiting

Apple MapKit Limits

• MapKit has daily quotas based on your Apple Developer account
• Free tier: ~25,000 service requests/day
• Paid tier: Higher limits available

Our Mitigations

1. Feature is opt-in - Only runs when user enables "EV Charging Needed"
2. Reasonable sampling - 100-mile intervals, not every mile
3. Deduplication - Chargers appearing in multiple searches are deduplicated
4. Fail gracefully - If POI search fails, trip planning continues without chargers

Data Flow

User enables "EV Charging Needed" toggle
            ↓
Trip planning runs (sync, Haversine estimates)
            ↓
ItineraryBuilder.enrichWithEVChargers() called
            ↓
For each travel segment (in parallel):
    ├── MKDirections.calculate() → Get polyline
    └── EVChargingService.findChargersAlongRoute()
            ├── Sample polyline every 100 miles
            ├── MKLocalPointsOfInterestRequest per sample
            ├── Filter to .evCharger category
            └── Deduplicate results
            ↓
TravelSegment.evChargingStops populated
            ↓
TripDetailView shows expandable charger list

Files Involved

File	Purpose
Core/FeatureFlags.swift	Feature toggle
Core/Services/EVChargingService.swift	POI search logic
Planning/Engine/ItineraryBuilder.swift	Enrichment orchestration
Features/Trip/ViewModels/TripCreationViewModel.swift	Triggers enrichment
Features/Trip/Views/TripDetailView.swift	Displays chargers
Core/Models/Domain/TravelSegment.swift	EVChargingStop model

Testing Notes

1. Simulator limitations - MapKit POI results may be limited in simulator
2. Test on device - Real EV charger data requires physical device
3. Monitor console - Look for [ItineraryBuilder] log messages showing charger counts

Future Improvements

• Cache EV charger results to reduce API calls on re-planning
• Allow configurable sample interval (50mi for shorter range EVs)
• Show chargers on the map view
• Filter by charger network (Tesla, Electrify America, etc.)