Planning Long-Distance EV Trips with EV Routing API

Hey EV enthusiasts! 🌿🔋 Planning a long-distance journey with your electric vehicle (EV) just got much easier. Today, we’re diving into an amazing API that calculates the optimal route for your trip, including automatic charging stops based on your vehicle's consumption and charging model. Grab your charging cable, and let’s get started!

What is the Long Distance EV Routing API?

The Long Distance EV Routing API calculates a route between a given origin and destination, including necessary charging stops along the way. These stops are intelligently determined based on your vehicle's consumption and charging model, ensuring you have a smooth and efficient journey.

Key features

- Automatic charging stops are added based on vehicle consumption. - Detailed charging information at each leg of the route. - Optimal route planning considering charging times and battery levels.

Making your first API request

Getting started with the Long Distance EV Routing API is straightforward. Let’s walk through making a request step-by-step.

Endpoint URL: The base URL for the API is:

   https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute

Required parameters:
- key: Your API key. (Don't have one? Grab it from the API provider's website!)
- vehicleEngineType: Set to electric.
- constantSpeedConsumptionInkWhPerHundredkm: Your vehicle's consumption at various speeds.
- currentChargeInkWh: Current charge in your vehicle's battery.
- maxChargeInkWh: Maximum battery capacity.
- minChargeAtDestinationInkWh: Minimum charge to have upon arrival.
- minChargeAtChargingStopsInkWh: Minimum charge to have at each charging stop.

Example URL: Let's say you have an API key your_api_key and you're planning a route from Berlin to Frankfurt. Your request URL would look like this:

markdown 
https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/52.507,13.492:50.104,8.624/json?key=your_api_key&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=32,10.87:77,18.01&currentChargeInkWh=20&maxChargeInkWh=40&minChargeAtDestinationInkWh=4&minChargeAtChargingStopsInkWh=4

Making the request: You can use the curl command to make the request via the terminal:

bash
curl -X POST 'https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/52.507,13.492:50.104,8.624/json&key=your_api_key&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=32,10.87:77,18.01&currentChargeInkWh=20&maxChargeInkWh=40&minChargeAtDestinationInkWh=4&minChargeAtChargingStopsInkWh=4' \ 
  -H 'Content-Type: application/json' -d '{ 
    "chargingParameters": { 
      "batteryCurve": [ 
        {"stateOfChargeInkWh": 50.0, "maxPowerInkW": 200}, 
        {"stateOfChargeInkWh": 70.0, "maxPowerInkW": 100}, 
        {"stateOfChargeInkWh": 80.0, "maxPowerInkW": 40} 
      ], 
      "chargingConnectors": [ 
        { 
          "currentType": "AC3", 
          "plugTypes": ["IEC_62196_Type_2_Outlet"], 
          "efficiency": 0.9, 
          "baseLoadInkW": 0.2, 
          "maxPowerInkW": 11 
        }, 
        { 
          "currentType": "DC", 
          "plugTypes": ["IEC_62196_Type_2_Outlet"], 
          "voltageRange": { 
            "minVoltageInV": 0, 
            "maxVoltageInV": 500 
          }, 
          "efficiency": 0.9, 
          "baseLoadInkW": 0.2, 
          "maxPowerInkW": 150 
        } 
      ], 
      "chargingTimeOffsetInSec": 60 
    } 
  }'

Or you can use JavaScript with the fetch API to make the request within your web application:

javascript
const url = 'https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/52.507,13.492:50.104,8.624/json?key=your_api_key&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=32,10.87:77,18.01&currentChargeInkWh=20&maxChargeInkWh=40&minChargeAtDestinationInkWh=4&minChargeAtChargingStopsInkWh=4';
const body = { 
    "chargingParameters": { 
        "batteryCurve": [ 
            { "stateOfChargeInkWh": 50.0, "maxPowerInkW": 200 }, 
            { "stateOfChargeInkWh": 70.0, "maxPowerInkW": 100 }, 
            { "stateOfChargeInkWh": 80.0, "maxPowerInkW": 40 } 
        ], 
        "chargingConnectors": [ 
            { 
                "currentType": "AC3", 
                "plugTypes": ["IEC_62196_Type_2_Outlet"], 
                "efficiency": 0.9, 
                "baseLoadInkW": 0.2, 
                "maxPowerInkW": 11 
            }, 
            { 
                "currentType": "DC", 
                "plugTypes": ["IEC_62196_Type_2_Outlet"], 
                "voltageRange": { 
                    "minVoltageInV": 0, 
                    "maxVoltageInV": 500 
                }, 
                "efficiency": 0.9, 
                "baseLoadInkW": 0.2, 
                "maxPowerInkW": 150 
            } 
        ], 
        "chargingTimeOffsetInSec": 60 
    } 
};

Understanding the response

When you make a successful call to the API, you'll receive a JSON object with detailed route and charging stop information. Here's a peek at what the response looks like:

json
{ 
    "summary": { 
        "remainingChargeAtArrivalInkWh": 16.5, 
        "totalChargingTimeInSeconds": 2542 
    }, 
    "routes": [ 
        { 
            "legs": [ 
                { 
                    "summary": { 
                        "remainingChargeAtArrivalInkWh": 12.5, 
                        "chargingInformationAtEndOfLeg": { 
                            "targetChargeInkWh": 30.0, 
                            "chargingTimeInSeconds": 2542, 
                            "chargingConnectors": [ 
                                { 
                                    "facilityType": "Charge_380_to_480V_3_Phase_at_32A", 
                                    "plugType": "NEMA_5_20" 
                                }, 
                                { 
                                    "facilityType": "Charge_Direct_Current_at_50kW", 
                                    "plugType": "IEC_62196_Type_2_Outlet" 
                                } 
                            ], 
                            "chargingParkUuid": "a4b60dff-b599-339a-0a1b-aae200153b86", 
                            "chargingParkName": "Charging park 1", 
                            "chargingParkOperatorName": "Charging park operator name", 
                            "chargingParkLocation": { 
                                "coordinate": { 
                                    "latitude": 0.6666667, 
                                    "longitude": -33.3333333 
                                }, 
                                "street": "Main street", 
                                "houseNumber": "42a", 
                                "city": "New Berlin", 
                                "postalCode": "32606", 
                                "countryCode": "US" 
                            }, 
                            "chargingConnectionInfo": { 
                                "chargingCurrentType": "Direct_Current", 
                                "chargingPowerInkW": 25.0, 
                                "chargingPlugType": "IEC_62196_Type_2_Outlet" 
                            }, 
                            "chargingParkPaymentOptions": [ 
                                { 
                                    "method": "Direct" 
                                } 
                            ], 
                            "chargingStopType": "Auto_Generated", 
                            "chargingParkPowerInkW": 50.0 
                        } 
                    } 
                } 
            ] 
        } 
    ] 
}

Let's break down some key parts of the response:

- summary: Contains overall route information including total charging time.

- routes: An array containing route details.

- legs: Information about each leg of the journey.

- chargingInformationAtEndOfLeg: Detailed charging information at the end of each leg.

Integrating the API in Android

To integrate the Long Distance EV Routing API into an Android application, follow these steps:

Add an Internet permission: Add the following permission to your AndroidManifest.xml:
```
xml 
    <uses-permission android:name="android.permission.INTERNET" /> 
```

Create an AsyncTask Class: Create a class to perform the network operation in the background.

java
public class FetchEVRouteTask extends AsyncTask<String, Void, String> {    
    @Override 
    protected String doInBackground(String... params) { 
        String apiKey = params[0]; 
        String origin = params[1]; 
        String destination = params[2]; 
        
        String urlString = "https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/" 
            + origin + ":" + destination 
            + "/json?key=" + apiKey 
            + "&vehicleEngineType=electric" 
            + "&constantSpeedConsumptionInkWhPerHundredkm=32,10.87:77,18.01" 
            + "&currentChargeInkWh=20" 
            + "&maxChargeInkWh=40" 
            + "&minChargeAtDestinationInkWh=4" 
            + "&minChargeAtChargingStopsInkWh=4";        
        // Implement network call 
    }     
    @Override 
    protected void onPostExecute(String result) { 
        // Handle the API response 
    } 
}

Execute the AsyncTask: Call the AsyncTask from your Activity or Fragment:

java 
    String apiKey = "your_api_key"; 
    String origin = "52.507,13.492"; 
    String destination = "50.104,8.624"; 
    new FetchEVRouteTask().execute(apiKey, origin, destination);

Integrating the API in iOS

To integrate the Long Distance EV Routing API into an iOS application using Swift, follow these steps:

Add the Network Layer: Create a function to make the network call using URLSession.

swift 
func fetchEVRoute(apiKey: String, origin: String, destination: String) { 
    let urlString = """
        https://api.tomtom.com/routing/1/calculateLongDistanceEVRoute/\(origin):\(destination)/json?key=\(apiKey)
        &vehicleEngineType=electric
        &constantSpeedConsumptionInkWhPerHundredkm=32,10.87:77,18.01
        &currentChargeInkWh=20
        &maxChargeInkWh=40
        &minChargeAtDestinationInkWh=4
        &minChargeAtChargingStopsInkWh=4
    """.replacingOccurrences(of: "\n", with: "")
    guard let url = URL(string: urlString) else { return }     
    let task = URLSession.shared.dataTask(with: url) { data, response, error in 
        if let error = error { 
            print("Error: \(error)") 
            return 
        }       
        guard let data = data else { return }         
        do { 
            // Parse the JSON response 
            let json = try JSONSerialization.jsonObject(with: data, options: []) 
            print(json) 
        } catch { 
            print("Error parsing JSON: \(error)") 
        } 
    } 
    task.resume() 
}

Call the function: Call the function from your View Controller:

swift 
    let apiKey = "your_api_key" 
    let origin = "52.507,13.492" 
    let destination = "50.104,8.624" 
    fetchEVRoute(apiKey: apiKey, origin: origin, destination: destination)

Bring it all together

Now that you know how to make requests and understand the responses, you can integrate this API into your app to provide real-time long-distance route planning with charging stops for your users. Whether you’re building a mobile app or a web dashboard, this API ensures a seamless experience for EV drivers.

Happy driving! If you have any questions or run into any issues, feel free to leave a comment below. Until next time, drive green and stay charged! 🌱🔋

Happy mapping!