Getting Started with Drive API

This guide will walk you through the essential steps to integrate Plugsurfing's Drive API into your application, enabling you to provide comprehensive EV charging services to your users.

Integration Overview

Here's what a typical integration journey usually starts like:

1. Get API credentials and understand authentication
2. Search for charging locations using geosearch
3. Create users
4. Start and stop charging sessions

1. Authentication

All requests to the Drive API require an API key for authentication. The API key must be included in the HTTP header of every request.

X-API-Key: your-api-key-here

URLs for our different environments

• Staging: https://drive-api-stage.plugsurfing.com/drive
• Production: https://drive-api.plugsurfing.com/drive

Example request:

curl --request POST \
     --url 'https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius?latitude=52.52&longitude=13.41' \
     --header 'X-API-Key: your-api-key'

⚠️

Security Note

Never expose your API key in client-side code or public repositories. Store it securely and use it only in server-to-server communications.

📘

Learn More

For detailed information about authentication and authorization, check API Key Access & Permissions

2. Searching for Charging Locations

One of the first features you'll likely implement is helping users find charging stations.
Here is how to find available charging stations within a specified distance from a point:

curl --request POST \
     --url 'https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius?latitude=52.52&longitude=13.41&distance=3000' \
     --header 'X-API-Key: your-api-key' \
     --data '
{
  "filters": {
    "locationStatuses": [
      "AVAILABLE"
    ],
    "powerType": "DC"
  }
}
'

This searches for available DC chargers within 3km of the specified coordinates.
The response contains a list of locations data (address, opening hours, chargers, connectors, availability)

📘

Learn More

For more ways to find charging locations and detailed information about the data and filtering options, see the our dedicated guide.

3. Managing Users

Before users can start charging, you need to sync your users with out system. The most common approach is to send us the user identifier you use in your system. That way, you can easily use the same identifier later on to identify the user on other endpoints. You can also pass the user's email.

Creating a User

curl --request POST \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users \
     --header 'X-API-Key: your-api-key' \
     --data '
{
  "id": "9064b366-80cf-47f2-a6d0-e9960c06fc1f",
  "email": "[email protected]"
}
'

Getting User Information

Let's try to retrieve information from the user we just created:

curl --request GET \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f \
     --header 'X-API-Key: your-api-key'

📘

Learn More

For more details on User Management, checkout our dedicated guide.

4. Managing Charging Keys

Charging keys authorize users to start charging sessions. There are two types:

• Physical cards (RFID cards/tags), used for local charging
• Virtual keys, used for remote charging

Listing a User's Charging Keys

When a user is created, a Virtual key is automatically created. Let's confirm that:

curl --request GET \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f/charging-keys \
     --header 'X-API-Key: your-api-key'

The response should look like this:

{
  "keys": [
    {
      "name": "App Charging Key",
      "enabled": true,
      "keyId": "80c5f015582cb2",
      "contractId": "DE-8PS-C8Z1CAHJM-U",
      "type": "virtual",
      "validFrom": "2025-03-07T10:18:02.000Z",
      "validTo": "2035-03-07T10:18:02.000Z",
      "created": "2025-03-07T10:18:02.000Z",
      "updated": "2025-03-07T10:18:02.000Z"
    }
  ]
}

📘

Learn More

For more details on Charging Keys, checkout our dedicated guide.

5. Managing Charging Sessions

Now that our user is created, they can start and stop remote charging sessions.

Starting a Remote Charging Session

To start a remote session, you need to provide two things:

• user id (to identify who requests the charging session)
• connector id (to identify which connector should be requested to start delivering energy)

curl --request POST \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f/sessions/start \
     --header 'X-API-Key: your-api-key' \
     --data '{"connectorId":"QsxRV9B8qSa8dV/U+/lOCQ=="}'

The response will include a sessionId that you'll need for checking status or stopping the session:

{
  "sessionId": "Nx5NomJyaMD"
}

Checking Session Status

curl --request GET \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f/sessions/Nx5NomJyaMD \
     --header 'X-API-Key: your-api-key'

Stopping a Charging Session

curl -X POST \
  "https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f/sessions/Nx5NomJyaMD/stop" \
     --header 'X-API-Key: your-api-key'

📘

Learn More

For detailed information about Remote Charging and Sessions, checkout our dedicated guide

Next Steps

Now that you understand the basics of the Drive API, you might want to explore:

• In-depth Geosearch capabilities
• User management
• Charging key management
• Sessions
• Payment options and configurations

If you have any questions or need assistance with your integration, please contact us.