training

Jira Story: Integrate EV Charging Station Availability Along Selected Route

Issue Type: Story
Priority: High
Component: EV Navigation / Maps & Routing
Labels: EV-Charging, API-Integration, Route-Navigation

Summary

Integrate an EV charging station API to retrieve and display charging stations along a user's selected route, including real-time availability status where supported.

Description

As an EV driver, I want to view charging stations along my selected route and check their availability so that I can plan charging stops and avoid unavailable charging stations during my journey.

The application will integrate with a suitable EV charging station provider, such as TomTom EV Search API, to retrieve charging station information based on the calculated route geometry.

Scope of Work
Evaluate the EV charging API provider and confirm API access, pricing, regional coverage, and live-status support.
Integrate the routing service to obtain the selected route's coordinates or polyline.
Develop a backend API to search for charging stations along the route.
Retrieve available station details, including:
Charging station name and location
Connector types and charging power
Availability status, where supported
Station identifiers and provider details
Filter stations based on route proximity and vehicle connector compatibility.
Display charging stations on the map with distinct status indicators.
Handle API errors, rate limits, missing data, and unknown availability status.
Secure API credentials and implement appropriate logging and monitoring.
Acceptance Criteria
Given a user has selected a source and destination, when a route is calculated, then the system retrieves charging stations along the route.
Given charging station data is available, when results are returned, then the application displays station markers and relevant station details.
Given live availability data is supported by the provider, when station status is retrieved, then the application identifies available, occupied, and offline chargers where those statuses are supplied.
Given a station's availability cannot be confirmed, then the application displays its status as Unknown rather than Available.
Given a vehicle's connector requirements are configured, then incompatible charging stations can be filtered out.
Given the API request fails or exceeds a rate limit, then the application handles the error gracefully and provides appropriate feedback.
Given the user changes the selected route, then the charging station results are refreshed for the new route.
Given API credentials are configured, then secrets are not exposed in frontend or mobile application code.
Technical Approach
Routing: Obtain route geometry from the existing routing service or integrate a routing API.
Charging station search: Evaluate TomTom EV Search Along Route API or an alternative provider with suitable coverage.
Backend: Expose an endpoint such as POST /api/ev-chargers.
Request: Accept route coordinates, search corridor width, and applicable connector filters.
Response: Return normalized station details and availability status.
Frontend: Render station markers and status indicators on the route map.
Dependencies
API provider account and credentials
Provider approval or subscription, if required
Existing route calculation and map rendering functionality
Confirmation of target-market coverage and real-time availability support
Definition of Done
API integration is implemented and reviewed.
Unit and integration tests cover successful responses, failures, and missing status data.
Charging stations are displayed correctly on the map.
API keys are stored securely.
Error handling and logging are implemented.
API documentation and setup instructions are updated.
Acceptance criteria are verified in the test environment.
Out of Scope
Reserving or booking charging stations
Processing charging payments
Initiating or stopping a charging session
Guaranteeing charger availability at the time of arrival
Deliverables
Backend charging station search endpoint
Frontend map integration
Availability status handling
Automated tests and integration documentation