Guides
HomeFAQSupportSDK

Quickstart guide

Suggest Edits

Welcome to the Jedlix API. This guide is designed to get you up and running with our API as quickly as possible. It will walk you through the steps needed to get an access token, register a user, add a vehicle And optimise the charging process at a charging location.

Step 1: Get a management access token

After subscribing to our service, you will receive an ApiKey and client_id and client_secret. You need to obtain an access token for the desired environment (QA or Production) by sending a POST request to https://jedlix-b2e.eu.auth0.com/oauth/token.

To get the access token, specify the environment in the audience parameter, and include your client_id and client_secret in the header. The response will contain the access_token that you will use in the Authorization header of your API requests.

curl -X POST 'https://jedlix-b2e.eu.auth0.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'audience={YOUR_ENVIRONMENT}'

Step 2: Register a user

Before using the Jedlix platform, you must register a user. To create a user, you need to provide at least the defaultCountry (country of residence) for the user. You can also optionally specify the language for communication with the user by setting the locale. If no locale is specified, English will be used as the default.

To create a user, send a POST request to https://{YOUR_ENVIRONMENT}.jedlix.com/api/v1/users with the required headers and the user details in the body of the request.

curl --request POST \
  --url https://{YOUR_ENVIRONMENT}.jedlix.com/api/v1/users \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'ApiKey: {YOUR_API_KEY}' \
  --header 'content-type: application/json' \
  --data '
{
  "defaultCountry": "NL",
  "locale": "EN"
}
'

On success, the API will return a response containing the user's id, which you will use to identify the user in the platform.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "locale": "string",
  "tenant": "string",
  "createdAt": "2022-11-12T06:32:56.423Z",
  "updatedAt": "2022-11-12T06:32:56.423Z",
  "chargingLocations": []
}

Step 3: Add a vehicle

It's time to add a vehicle to the user account. You can connect a vehicle from the list of supported car brands and models available here, or use a simulation vehicle, which can only be used in the QA environment. More information about testing with the Jedlix Test Car can be found here.

To start a vehicle connection session, use the Connect Vehicle endpoint with a POST request.

Here's an example:

curl --request POST \
     --url https://qa-{TENANT}-smartcharging.jedlix.com/api/v1/users/{userId}/vehicles/connect-sessions \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {USER_ACCESS_TOKEN}'

The response to this request contains a startUrl, which opens the Jedlix Connect Webview. The user selects the car on this page, and if using the QA environment, the Jedlix Test Car will be available for selection.

{
  "vehicleId": null,
  "isFinished": false,
  "startUrl": "<https://qa-assetsconnection.jedlix.com/web/start?sessionId=2714bd6e704940c4a7908a5a0f51b706>",
  "redirectUrl": "<https://qa-assetsconnection.jedlix.com/web/end>",
  "id": "2714bd6e-7049-40c4-a790-8a5a0f51b706",
  "redirectInfo": null
}

Once the redirectUrl is reached and the isFinished field is set to true, the session ends, and you can return to your interface.

{
  "vehicleId": "16a30724-3e51-42b1-9ac1-b7fec24d5750",
  "isFinished": true,
  "startUrl": null,
  "redirectUrl": null,
  "id": "2714bd6e-7049-40c4-a790-8a5a0f51b706",
  "redirectInfo": null
}

Tip: Our SDKs simplify initiating Jedlix Connect Sessions in your app.

Once the vehicle is successfully connected, telemetry will be collected regularly, and charging sessions will be recorded. With the provided vehicleId, you can access the following:

  • Vehicle details here
  • Charge state here and request an update of the charge state here
  • Retrieve Charge settings here and modify them here
  • Retrieve Latest charge session here, all charge sessions here, and details for a session here.

Step 4: Set User Charge Preferences

To optimize the charging process for your user, it is important to set their charge preferences. The platform takes these preferences into account when optimizing charging sessions.

The most critical preference is to determine when the vehicle's battery needs to be ready for the next journey and at what level it needs to be charged. The user can adjust their charging preferences in the departureTimes schedule, or by setting a single custom departure time using the departureTimeOverride option.

The car will be charged without interruptions to the directChargingBatteryLevel and optimally scheduled to reach the desiredBatteryLevel before the departure time.

Here's an example of how to set charge preferences for a user who needs their car to be charged to 90% before 7am during weekdays and before 10am in the weekend:

curl --request POST \
     --url https://qa-{TENANT}-smartcharging.jedlix.com/api/v1/users/{userId}/vehicles/{vehicleId}/charge-settings \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {USER_ACCESS_TOKEN}' \
     --header 'content-type: application/json' \
     --data '
{
     "departureTimes": {
          "monday": "07:00",
          "tuesday": "07:00",
          "wednesday": "07:00",
          "thursday": "07:00",
          "friday": "07:00",
					"saturday": "10:00",
          "sunday": "10:00"
     },
     "isSmartChargingEnabled": true,
     "timeZone": "Europe/Amsterdam",
     "directChargingBatteryLevel": 25,
     "desiredBatteryLevel": 90
}
'

By providing the departureTimes and isSmartChargingEnabled options, the system will automatically optimize the charging sessions for the user's specified preferences.

Step 5: Define a Charging Location to Optimize Charging Sessions

After connecting a car, recording of charge sessions begins, but without defining a Charging Location, the platform will not optimize the charging process. This results in unmanaged charging sessions.

To create a charging location for the user and optimize the charging process, follow these steps:

  1. Use the Create a charging location endpoint to create a charging location. You must provide the coordinates of the location, which are used by the platform to generate a geofence, and the country and postal code to identify the electricity grid area of the location. You can also add optional address details such as the street, city, and region.
  2. If the creation of the charging location is successful, the response will include the id of the newly created charging location, which is referred to as chargingLocationId.
  3. Once the car starts charging within the geofence, the matching chargingLocationId will be added to the charge session data, and the system will optimize the charging process based on the user preferences and charging location details, such as energy tariffs and solar PV setup installed.

Step 6: Add a charger to a charge location

Note that if you are a Charge Point Operator on the Jedlix platform, you can use this guide to connect a charger.

Adding a connected charger to a charge location enables the platform to optimize the charging process in case the user's vehicle charging cannot be remotely controlled. If the user has both a connected car and charger, data from both can be used to optimize the charge session.

To initiate a charger connection session, you can send a POST request to the Connect a Charger endpoint.

Here's an example of the POST request using curl:

curl --request POST \
--url [https://demo-smartcharging.jedlix.com/api/v1/users/userId/charging-locations/chargingLocationId/chargers/connect-sessions](https://demo-smartcharging.jedlix.com/api/v1/users/userId/charging-locations/chargingLocationId/chargers/connect-sessions) \
--header 'accept: application/json'

After sending the POST request, the startUrl returned opens a webview for the user to select a charger. Once the user reaches the redirectUrl and the isFinished field is set to true, the session ends and you can return to your interface.

Step 7: Optimize charging costs by adding electricity tariffs to a location

To help your users reducecharging costs, it's important to add electricity tariffs to the platform. By doing so, the platform can take into account the tariffs and optimize the charging process for lowest possible costs.

To add electricity tariffs use the Create electricity tariffs endpoint to create an electricity tariff for a charging location. You will need to provide the tariff type and currency, along with the pricing structure. You can use a wide range of tariff types such as Fixed or Dynamic tariffs. For example, for a user that has dynamic tariffs, you would create an electricity tariff by specifying the currency and by setting the tariff type to dynamic. The platform will then automatically use the Spot electricity prices applicable at that charging location to optimize the charge session and calculate the charge costs.

Thats it! The charging session will now be optimized by the platform according to the added electricity tariffs, resulting in the lowest possible costs.

After the charge session has ended, the chargingCost of the charge session and savings created by the service are automatically calculated and added to the Session details under the financials object.

Step 8: Add solar panel configuration to a location to increase self-consumption

If your user has solar panels at their charging location and wants to optimize their solar self-consumption, the Jedlix platform enables Solar Smart Charging to make it easy for you.

Solar Smart Charging uses the most advanced solar forecasting technology based on a global fleet of weather satellites. The algorithm predicts how much power the solar panels will generate based on the charging location and PV system details. With this information, the platform determines the optimal charging times to use the solar electricity to charge the car.

To configure Solar Smart Charging, you only need to add the technical specifications of the Solar configuration to the Charging Location using the following API:

curl --request POST \\
     --url https://qa-{TENANT}-smartcharging.jedlix.com/api/v1/users/{userId}/charging-locations/{chargingLocationId}/solar-settings \\
     --header 'accept: application/json' \\
     --header 'authorization: Bearer {USER_ACCESS_TOKEN}'
     --header 'content-type: application/json' \\
     --data '
{
     "solarMaxProduction": 4,
     "solarOrientation": 180,
     "solarTiltAngle": 23,
     "solarEfficiency": 90,
     "solarProductionThreshold": 5
}
'

To get started with solar smart charging, you only need to provide the maximum capacity of the solar PV installation in kWp using the solarMaxProduction parameter. The other parameters are optional and come with default values that work well for most cases.

If you want to tweak the settings to improve the forecast accuracy of your Solar output, you can adjust the following parameters:

  • solarOrientation: Orientation of the solar panels in degrees
  • solarTiltAngle: Tilt angle of the solar panels in degrees
  • solarEfficiency: Efficiency of the solar panels in percentage
  • solarProductionThreshold: Minimum solar power that the algorithm should consider when optimizing the charging session.

With Solar Smart Charging, you can maximize the use of solar energy and reduce your carbon footprint.

Updated 11 months ago

What’s Next

Quick access? Use the Demo account which has all of the above