Locations Module - Plugsurfing Developer

Delta pull behavior, inlined tariffs, pagination rules, and relaxed field validations for Roam OCPI locations.

Locations module adjustments

Deviation	Plugsurfing solution
Tariff inlined in locations object	The relevant tariffs are inlined on the connector
PUSH of Locations / EVSEs / connectors not supported	An EMP can do very frequent (up to once per minute) delta pulls to get the locations that have been updated since the last delta pull
No deep pagination	A hash to the next page is provided as part of the Link header
Location field validations	Relaxed validations, as specified below, to accept locations that are not fully OCPI compliant
EVSE capabilities	Non-supported capabilities will be stripped from the EVSEs returned via the API
Removed locations	Conduct a full PULL to understand which locations have been removed

Tariff inlined in locations object

The relevant tariffs are inlined on the connector, via the location module. Using delta pulls (date_from/date_to) will return locations where the location data or the tariff data has changed. The response has the tariff object inlined for each connector. You can do delta pulls up to once per minute. Example:

{
  // location properties...
  "evses": [
    {
      // evse properties...
      "connectors": [
        {
          "id": "ec00d01637753c4c4acd8e67d09b8b94a80f",
          "standard": "Type2",
          "power_type": "AC_3_PHASE",
          "max_voltage": 230,
          "max_amperage": 32,
          "max_electric_power": 22000,
          "tariffs": [
            {
              "country_code": "SE",
              "party_id": "CPO",
              "id": "6307fc109da88e3a_7e27b28369e4c986",
              "currency": "SEK",
              "elements": [
                {
                  "price_components": [
                    {
                      "type": "ENERGY",
                      "price": 0.7016,
                      "step_size": 1
                    }
                  ]
                }
              ],
              "last_updated": "2025-05-27T00:55:25.634Z"
            }
          ],
          "last_updated": "2024-12-06T04:40:10Z"
        }
      ]
    }
  ],
  "operator": {
    "name": "CPO Name"
  },
  "time_zone": "Europe/Stockholm",
  "last_updated": "2025-02-13T16:13:23.783Z"
}

PUSH of Locations / EVSEs / connectors not supported

Plugsurfing does not support pushing updates of charging stations. The amount of updates that Plugsurfing receives from CPOs would lead to a massive amount of data being sent through to all partners if it would be shared unfiltered. Instead, you can do delta pulls which will give you the necessary location updates without unnecessary traffic.

Pagination

For performance reasons Plugsurfing doesn’t use deep pagination, instead a hash to the next page is provided as part of the Link header (The header will contain an additional query param named smart_paging). If your OCPI implementation already follows the Link header, no changes are needed. The maximum page size returned is 250 locations. Parallel pulling of locations is not supported, since smart pagination is used. Example getting page 1 Request:

GET https://ocpi-stage.plugsurfing.com/cpo/2.2.1/locations?offset=0&limit=100

Response header (if another page exist):

Link: <https://ocpi-stage.plugsurfing.com/cpo/2.2.1/locations/?offset=100&limit=100&smart_paging=hash1>; rel="next"

Example getting page 2 Request:

GET https://ocpi-stage.plugsurfing.com/cpo/2.2.1/locations?offset=100&limit=100&smart_paging=hash1

Response header (if another page exist):

Link: <https://ocpi-stage.plugsurfing.com/cpo/2.2.1/locations/?offset=200&limit=100&smart_paging=hash2>; rel="next" 

Location field validations

Plugsurfing is a bit more lenient than the OCPI specification for a set of properties when receiving Locations from CPOs. This means outgoing Locations from Plugsurfing will also not fully comply with the OCPI specification for these fields.

Field	OCPI specification	Plugsurfing implementation
coordinates.latitude	5-7 decimals	4-8 decimals
coordinates.longitude	5-7 decimals	4-8 decimals
address	string(45)	string(255)
city	string(45)	string(255)
state	string(20)	string(255)

EVSE capabilities

The following capabilities are not supported, and they will be stripped from the EVSEs returned via the API:

CHARGING_PROFILE_CAPABLE
CHARGING_PREFERENCES_CAPABLE
RESERVABLE
TOKEN_GROUP_CAPABLE
UNLOCK_CAPABLE

Removed locations

Locations that have previously been available to you can be removed for different reasons.

A CPO has removed a location
A CPO is no longer part of the network
You have updated your country filtering and removed a previously supported country
You have requested to block a CPO with network filtering configured on the Plugsurfing Power Platform

When a location is no longer available, it will no longer be returned when pulling locations. Based on the absence of a location in a full PULL, you should delete it in your system. A full PULL is recommended on a nightly basis in order to keep the available locations synchronised.

Routing headers

Plugsurfing supports OCPI routing headers on the Locations pull endpoint. For the general OCPI message routing model, refer to the OCPI 2.2.1 specification. When OCPI-to-country-code and OCPI-to-party-id are provided, Plugsurfing uses the routed party as a location filter within the requesting EMP’s accessible charging network. The request returns locations only for that routed CPO, provided that the party can be resolved and is available to the requesting EMP. If the routed party cannot be resolved, is not available through the requesting EMP’s network, or the OCPI-to-* routing headers are incomplete, Plugsurfing returns an OCPI response with status_code 2001 and an empty data array. The routing target DE*8PS requests the full Plugsurfing CPO network available to the requesting EMP; it does not apply a single-CPO location filter. If the request includes complete OCPI-from-* and OCPI-to-* headers, Plugsurfing still returns the corresponding OCPI response routing headers. Plugsurfing offers a generous Fair Usage Policy, but routing headers are not intended for extensive parallelization of location pulls. You may pull up to five routed country-code and party-id combinations in parallel. The calling client is expected to track this limit. Plugsurfing may introduce rate limiting if usage affects platform stability or other customers.

​Locations module adjustments

​Tariff inlined in locations object

​PUSH of Locations / EVSEs / connectors not supported

​Pagination

​Location field validations

​EVSE capabilities

​Removed locations

​Routing headers