Guides

Getting Started

Getting Started

This guide aims to walk you through the endpoints, from creating a user to looking at their charging sessions history.
For detailed information on each endpoint, please go in to the respective endpoints description in the menu to the left.

Base URLs:

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

1. Create a user - POST

The provided id needs to be a way to uniquely identify your users.
The email is optional.

Endpoint: /v1/user

API Reference

{
  "id": "ourTestUser",
  "email": "[email protected]"
}

curl -X POST \
    "https://drive-api.plugsurfing.com/drive/v1/users" \
    -H "x-api-key: my-key" \
    -H "Content-Type: application/json" \
    -d "{
          \"id\": \"ourTestUser\",
          \"email\": \"[email protected]\"
        }"

Expected return

201 - Created (no body)

2. Get charging keys list - GET

This endpoint lets you retrieve all the charging keys stored in our system for the user you provided.
The response includes relevant information such as key type and validity dates.

Endpoint: /v1/users/{userId}/charging-keys

curl -X GET \
    "https://drive-api.plugsurfing.com/drive/v1/users/ourTestUser/charging-keys" \
    -H "x-api-key: my-key" \
    -H "Content-Type: application/json"

Expected return

200 - OK

{
  "keys": [
    {
      "name": "key 4390b827",
      "enabled": true,
      "keyId": "27b89043",
      "referenceId": "DE*8PS*CD0C00*2",
      "contractId": "DE-8PS-C0CD0C002-Q",
      "type": "tag",
      "validFrom": "2021-12-08T00:00:00.000Z",
      "validTo": "2031-12-08T23:59:59.000Z",
      "created": "2021-12-08T10:33:01.000Z",
      "updated": "2021-12-08T10:33:01.000Z"
    }
  ]
}

3. Geosearch radius - POST

This endpoint allows you to search for chargers within a specified radius from a given point. Filters can be applied, but they are optional.
If no valid chargers are found within the given parameters, an empty array of locations will be returned.
Otherwise, you will receive locations that contain charging stations, each with available connectors.
The connector id is what you will use for a remote start (described below).

Endpoint: /v1/geosearch/radius

API Reference

curl -X 'POST' \
  'https://drive-api.plugsurfing.com/drive/v1/geosearch/radius?latitude=52.331142&longitude=13.145221&distance=3000&aggregate=false' \
  -H 'accept: */*' \
  -H "x-api-key: my-key" \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "connectorStandards": [
      "3PinSquare"
    ],
    "locationStatuses": [
      "AVAILABLE"
    ],
    "powerType": "AC",
  }
}'

Expected return

200 - OK

{
  "locations": [
    {
      "id": "connectorId",
      "name": "string",
      "coordinates": {
        "latitude": "string",
        "longitude": "string"
      },
      "evses": [
        {
          "uid": "string",
          "evse_id": "string",
          "status": "AVAILABLE",
          "connectors": [
            {
              "id": "string",
              "standard": "3PinSquare",
              "power": 0,
              "power_type": "AC_1_PHASE"
            }
          ],
          "capabilities": ["CHARGING_PROFILE_CAPABLE"],
          "last_updated": "2022-06-07T06:12:15.806Z"
        }
      ],
      "operator": {
        "id": "string",
        "name": "string"
      },
      "opening_times": {
        "twentyfourseven": true,
        "regular_hours": [
          {
            "weekday": 0,
            "period_begin": "string",
            "period_end": "string"
          }
        ],
        "exceptional_openings": [
          {
            "period_begin": "2022-06-07T06:12:15.806Z",
            "period_end": "2022-06-07T06:12:15.806Z"
          }
        ],
        "exceptional_closings": [
          {
            "period_begin": "2022-06-07T06:12:15.806Z",
            "period_end": "2022-06-07T06:12:15.806Z"
          }
        ]
      },
      "directions": [
        {
          "language": "st",
          "text": "string"
        }
      ],
      "country": "str",
      "city": "string",
      "postal_code": "string",
      "address": "string"
    }
  ],
  "aggregates": [
    {
      "coordinates": {
        "latitude": "string",
        "longitude": "string"
      },
      "count": 2
    }
  ]
}

4. Remote start - POST

This endpoint starts a charging session for the provided user and connector.
The response will always include a session id, regardless of whether the start was successful or not (all sessions and session attempts are stored).

You must store the session id to be able to check its status, stop charging, etc.

Endpoint: /v1/users/{userId}/sessions/start

API Reference

curl -X 'POST' \
  'https://drive-api.plugsurfing.com/drive/v1/users/ourTestUser/sessions/start' \
  -H 'accept: */*' \
  -H "x-api-key: my-key" \
  -H 'Content-Type: */*' \
  -d '{
  "connectorId": "connectorId"
}'

Expected return

200 - OK

{
  "sessionId": "LWO89J3mDJr"
}

5. Get session by id - GET

This endpoint returns the status of a charging session. The session id is obtained when calling the remote start endpoint.

The response will indicate whether the session is starting, started, failed, or complete.

When a session is complete, you will also have an additional field called balanceStatus which will give you the payment info as one of 4 options (PROCESSING, PAID, DEBT, REFUND).

Endpoint: /v1/users/{userId}/sessions/{sessionId}

API Reference

curl -X 'GET' \
  'https://drive-api.plugsurfing.com/drive/v1/users/ourTestUser/sessions/hiJKlMn' \
  -H 'accept: */*'
  -H "x-api-key: my-key" \

Expected return

200 - OK

{
  "sessionStatus": "STARTED",
  "charger": {
    "chargingStationName": "ZzZ 220218114136937169",
    "connectorLabel": "1",
    "evseId": "NO*XXX*EZzZ220218114136937169*1"
  },
  "connectorId": "abcJd/vR5fvzBa0X/gxaXA==",
  "duration": "PT21.379S",
  "receiptAvailable": false,
  "sessionId": "LWO89J3mDJr",
  "site": "ZzZ 220218114135485264",
  "startTime": "2022-06-07T06:49:59.811Z"
}

or with a COMPLETE session:

{
  "sessionStatus": "COMPLETE",
  "balanceStatus": "PAID",
  "charger": {
    "chargingStationName": "ZzZ 220218114136937169",
    "connectorLabel": "1",
    "evseId": "NO*XXX*EZzZ220218114136937169*1"
  },
  "connectorId": "abcJd/vR5fvzBa0X/gxaXA==",
  "duration": "PT15M",
  "energy": {
    "unit": "WH",
    "value": 1840
  },
  "price": {
    "currencyCode": "NOK",
    "minorExclVat": 0,
    "minorInclVat": 0,
    "vat": "25"
  },
  "receiptAvailable": false,
  "sessionId": "LWO89J3mDJr",
  "site": "ZzZ 220218114135485264",
  "startTime": "2022-02-18T10:41:39.148Z"
}

6. Remote stop - POST

To stop a charging session, call this endpoint with the session id you received from remote start.
Calling this endpoint with a session id pointing to an already stopped session will not cause any harm, but you will still receive a 200 - OK.
You will only receive error messages for an invalid request.

Endpoint: /v1/users/{userId}/sessions/{sessionId}/stop

API Reference

curl -X 'POST' \
  'https://drive-api.plugsurfing.com/drive/v1/users/ourTestUser/sessions/LWO89J3mDJr/stop' \
  -H 'accept: */*' \
  -H 'X-API-Key: my-key' \
  -d ''

Expected return

200 - OK (No body)

7. Get session history - POST

This endpoint can be used to retrieve the complete history of charging sessions for a given user.
The response will contain an array of sessions, each with the same details to those provided by the Get Session by id endpoint.

Endpoint: /v1/users/{userId}/sessions/history

API Reference

curl -X 'POST' \
  'https://drive-api.plugsurfing.com/drive/v1/users/ourTestUser/sessions/history' \
  -H 'accept: */*' \
  -H 'X-API-Key: my-key' \
  -H 'Content-Type: */*' \
  -d '{
  "sessionStatus": [
    "COMPLETE"
  ],
  "limit": 50
}'

Expected return

200 - OK

{
  "sessions": [
    {
      "sessionStatus": "COMPLETE",
      "balanceStatus": "PAID",
      "charger": {
        "chargingStationName": "ZzZ 220218114136937169",
        "connectorLabel": "1",
        "evseId": "NO*XXX*EZzZ220218114136937169*1"
      },
      "connectorId": "abcJd/vR5fvzBa0X/gxaXA==",
      "duration": "PT30.234S",
      "energy": {
        "unit": "WH",
        "value": 61
      },
      "paymentMethod": "EXTERNAL",
      "price": {
        "currencyCode": "NOK",
        "minorExclVat": 160,
        "minorInclVat": 200,
        "vat": "25"
      },
      "receiptAvailable": true,
      "sessionId": "LWO89J3mDJr",
      "site": "ZzZ 220218114135485264",
      "startTime": "2022-06-07T06:49:59.811Z"
    }
  ]
}

Updated 3 months ago