OCPI 2.2: Open Charge Point Interface

OCPI 2.2

Open Charge Point Interface

https://github.com/ocpi & https://ocpi-protocol.org

document version 2.2-d2, 12-06-2020

Table of Contents

1. OCPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1. OCPI 2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1. Changes/New functionality: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.2. OCPI 2.2-d2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2. Introduction and background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2. Terminology and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.1. Requirement Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.2. Abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.3. EV Charging Market Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.3.1. Typical OCPI implementations per Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.4. Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.5. Provider and Operator abbreviation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.5.1. The Netherlands, Belgium and Luxembourg (BeNeLux) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.5.2. Germany. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.5.3. Austria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.5.4. France . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.6. Charging topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.7. Variable names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.8. Cardinality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.9. Data Retention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.9.1. Between OCPI version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3. Supported Topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.1. Peer-to-peer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.2. Multiple peer-to-peer connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.3. Peer-to-peer multiple the same roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.4. Peer-to-peer dual roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.5. Peer-to-peer mixed roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.6. Multiple peer-to-peer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.7. Platforms via Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.8. Platforms via Hub and direct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4. Transport and format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.1. JSON / HTTP implementation guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.1.1. Security and authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.1.2. Authorization header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.1.3. Pull and Push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.1.4. Request format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.1.4.1. GET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.1.4.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.1.4.3. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.1.5. Client Owned Object Push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.1.5.1. Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.1.6. Response format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.1.6.1. Example: Version information response (list of objects) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.1.6.2. Example: Version details response (one object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.1.6.3. Example: Tokens GET Response with one Token object. (CPO end-point) (one object) . . . . . . . . . . . . . . . . . . 21

4.1.6.4. Example: Tokens GET Response with list of Token objects. (eMSP end-point) (list of objects) . . . . . . . . . . . . . 21

4.1.6.5. Example: Response with an error (contains no data field) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.1.7. Message Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.1.7.1. Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.1.7.2. Message Routing Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.1.7.3. Broadcast Push. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4.1.7.4. Open Routing Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4.1.7.5. GET All via Hubs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.1.7.6. Overview of required/optional routing headers for different scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.1.7.7. GET All via Hubs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

4.1.7.8. Timestamps and Objects send via Hubs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

4.2. Unique message IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

4.3. Interface endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

4.4. Offline behaviour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

5. Status codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5.1. 1xxx: Success . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5.2. 2xxx: Client errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5.3. 3xxx: Server errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

5.4. 4xxx: Hub errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6. Versions module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.1. Version information endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.1.1. Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.1.2. Version class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.1.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.1.3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.2. Version details endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.2.1. Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.2.2. Endpoint class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.2.3. InterfaceRole enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.2.4. ModuleID enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.2.5. VersionNumber enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.2.5.1. Custom Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6.2.6. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6.2.6.1. Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

7. Credentials module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

7.1. Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

7.1.1. Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

7.1.2. Updating to a newer version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

7.1.3. Changing endpoints for the current version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

7.1.4. Updating the credentials and resetting the credentials token. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

7.1.5. Errors during registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7.1.6. Required endpoints not available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7.2. Interfaces and endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7.2.1. GET Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7.2.2. POST Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7.2.3. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

7.2.4. DELETE Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

7.3. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

7.3.1. Credentials object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

7.3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

7.4. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

7.4.1. CredentialsRole class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

8. Locations module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8.1. Flow and Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8.1.1. No public charging or roaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8.1.2. Group of Charge Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8.1.3. OCPP 1.x Charge Points with multiple connectors per EVSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

8.2. Interfaces and endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

8.2.1. Sender Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

8.2.1.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

8.2.2. Receiver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

8.2.2.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

8.2.2.2. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

8.2.2.3. PATCH Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

8.3. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

8.3.1. Location Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

8.3.1.1. Example public charging location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

8.3.1.2. Example destination charging location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

8.3.1.3. Example destination charging location not published, but paid guest usage possible . . . . . . . . . . . . . . . . . . . . 58

8.3.1.4. Example charging location with limited visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

8.3.1.5. Example private charge point with eMSP app control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

8.3.1.6. Example charge point in a parking garage with opening hours. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

8.3.2. EVSE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

8.3.3. Connector Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

8.4. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

8.4.1. AdditionalGeoLocation class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

8.4.2. BusinessDetails class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

8.4.3. Capability enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

8.4.4. ConnectorFormat enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

8.4.5. ConnectorType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

8.4.6. EnergyMix class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

8.4.6.1. Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

8.4.7. EnergySource class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

8.4.8. EnergySourceCategory enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

8.4.9. EnvironmentalImpact class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

8.4.10. EnvironmentalImpactCategory enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

8.4.11. ExceptionalPeriod class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

8.4.12. Facility enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

8.4.13. GeoLocation class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

8.4.14. Hours class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

8.4.14.1. Example: 24/7 open with exceptional closing.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

8.4.14.2. Example: Opening Hours with exceptional closing.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

8.4.14.3. Example: Opening Hours with exceptional opening.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

8.4.15. Image class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

8.4.16. ImageCategory enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

8.4.17. ParkingRestriction enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

8.4.18. ParkingType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

8.4.19. PowerType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

8.4.20. PublishTokenType class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

8.4.21. RegularHours class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

8.4.21.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

8.4.22. Status enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

8.4.23. StatusSchedule class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

9. Sessions module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

9.1. Flow and Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

9.1.1. Push model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

9.1.2. Pull model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

9.1.3. Set: Charging Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

9.1.4. Reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

9.2. Interfaces and Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

9.2.1. Sender Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

9.2.1.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

9.2.1.2. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

9.2.1.3. Receiver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

9.2.1.4. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

9.2.1.5. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

9.2.1.6. PATCH Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

9.3. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

9.3.1. Session Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

9.3.1.1. Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

9.3.2. ChargingPreferences Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

9.4. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

9.4.1. ChargingPreferencesResponse enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

9.4.2. ProfileType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

9.4.3. SessionStatus enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

10. CDRs module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

10.1. Flow and Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

10.1.1. Credit CDRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

10.1.2. Push model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

10.1.3. Pull model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

10.2. Interfaces and Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

10.2.1. Sender Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

10.2.1.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

10.2.2. Receiver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

10.2.2.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

10.2.2.2. POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

10.3. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

10.3.1. CDR Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

10.3.1.1. Example of a CDR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

10.4. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

10.4.1. AuthMethod enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

10.4.2. CdrDimension class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

10.4.3. CdrDimensionType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

10.4.4. CdrLocation class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

10.4.5. CdrToken class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

10.4.6. ChargingPeriod class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

10.4.7. SignedData class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

10.4.8. SignedValue class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

11. Tariffs module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

11.1. Flow and Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

11.1.1. Push model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

11.1.2. Pull model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

11.2. Interfaces and Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

11.2.1. Sender Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

11.2.1.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

11.2.2. Receiver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

11.2.2.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

11.2.2.2. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

11.2.2.3. DELETE Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

11.3. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

11.3.1. Tariff Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

11.3.1.1. Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

11.4. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

11.4.1. DayOfWeek enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

11.4.2. PriceComponent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

11.4.2.1. Example Tariff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

11.4.3. ReservationRestrictionType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

11.4.4. TariffElement class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

11.4.5. TariffDimensionType enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

11.4.6. TariffRestrictions class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

11.4.6.1. Example: Tariff with max_power Tariff Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

11.4.6.2. Example: Tariff with max_duration Tariff Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

11.4.7. TariffType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

12. Tokens module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

12.1. Flow and Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

12.1.1. Push model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

12.1.2. Pull model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

12.1.3. Real-time authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

12.2. Interfaces and endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

12.2.1. Receiver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

12.2.1.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

12.2.1.2. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

12.2.1.3. PATCH Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

12.2.2. Sender Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

12.2.2.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

12.2.2.2. POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

12.3. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

12.3.1. AuthorizationInfo Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

12.3.2. Token Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

12.3.2.1. Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

12.4. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

12.4.1. AllowedType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

12.4.2. EnergyContract class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

12.4.3. LocationReferences class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

12.4.4. TokenType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

12.4.5. WhitelistType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

13. Commands module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

13.1. Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

13.2. Interfaces and endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

13.2.1. Receiver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

13.2.1.1. POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

13.2.1.2. Request Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

13.2.2. Sender Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

13.2.2.1. POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

13.2.2.2. Request Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

13.3. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

13.3.1. CancelReservation Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

13.3.2. CommandResponse Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

13.3.3. CommandResult Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

13.3.4. ReserveNow Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

13.3.5. StartSession Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

13.3.6. StopSession Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

13.3.7. UnlockConnector Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

13.4. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

13.4.1. CommandResponseType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

13.4.2. CommandResultType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

13.4.3. CommandType enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

14. ChargingProfiles module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

14.1. Smart Charging Topologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

14.1.1. The eMSP generates ChargingProfiles.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

14.1.2. The eMSP delegated Smart Charging to SCSP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

14.1.3. The CPO delegated Smart Charging to SCSP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

14.2. Use Cases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

14.3. Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

14.3.1. Example of setting/updating a ChargingProfile by the Sender (typically the SCSP or eMSP). . . . . . . . . . . . . . . . . 152

14.3.2. Example of a setting/updating a ChargingProfile by the SCSP via the eMSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

14.3.3. Example of a removing/clearing ChargingProfile sent by the Sender (typically the eMSP or SCSP) . . . . . . . . . . . 153

14.3.4. Example of a removing/clearing ChargingProfile send by the SCSP via the eMSP. . . . . . . . . . . . . . . . . . . . . . . . . 154

14.3.5. Example of a GET ActiveChargingProfile send by the Sender (typically the eMSP or SCSP) . . . . . . . . . . . . . . . . 155

14.3.6. Example of a GET ActiveChargingProfile send by the SCSP via eMSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

14.3.7. Example of the Receiver (typically the CPO) sending an updated ActiveChargingProfile . . . . . . . . . . . . . . . . . . . . 156

14.3.8. Example of the Receiver (typically the CPO) sending an updated ActiveChargingProfile to the SCSP via the

eMSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

14.4. Interfaces and endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

14.4.1. Receiver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

14.4.1.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

14.4.1.2. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

14.4.1.3. Request Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

14.4.1.4. DELETE Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

14.4.2. Sender Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

14.4.2.1. POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

14.4.2.2. Request Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

14.4.2.3. Response Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

14.4.2.4. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

14.4.2.5. Request Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

14.4.2.6. Response Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

14.5. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

14.5.1. ChargingProfileResponse Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

14.5.2. ActiveChargingProfileResult Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

14.5.3. ChargingProfileResult Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

14.5.4. ClearProfileResult Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

14.5.5. SetChargingProfile Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

14.6. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

14.6.1. ActiveChargingProfile class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

14.6.2. ChargingRateUnit enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

14.6.3. ChargingProfile class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

14.6.4. ChargingprofilePeriod class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

14.6.5. ChargingProfileResponseType enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

14.6.6. ChargingProfileResultType enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

15. HubClientInfo module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

15.1. Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

15.1.1. Another Party becomes CONNECTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

15.1.2. Another Party goes OFFLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

15.1.3. Another Party becomes PLANNED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

15.1.4. Another Party becomes SUSPENDED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

15.2. Flow and Life-cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

15.2.1. Push model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

15.2.2. Pull model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

15.2.3. Still alive check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

15.3. Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

15.3.1. Receiver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

15.3.1.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

15.3.1.2. PUT Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

15.3.2. Sender Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

15.3.2.1. GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

15.3.2.2. Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

15.3.2.3. Response Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

15.4. Object description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

15.4.1. ClientInfo Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

15.5. Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

15.5.1. ConnectionStatus enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

16. Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

16.1. CiString type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

16.2. DateTime type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

16.3. DisplayText class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

16.4. number type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

16.5. Price class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

16.5.1. Role enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

16.6. string type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

16.7. URL type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

17. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

17.1. Changes between OCPI 2.1.1 and 2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

This document is made available under the Creative Commons Attribution- NoDerivatives 4.0 International Public License

(https://creativecommons.org/licenses/by-nd/4.0/legalcode).

OCPI 2.2-d2

Version History

Version Date Author Description

2.2-d2 12-06-2020 Robert de Leeuw

ihomer

2nd documentation revision of the OCPI 2.2 spec.

Contains textual improvements and fixes some of the examples.

Most improvements in the tarrifs module, especially step_size

is better explained.

2.2 30-09-2019 Robert de Leeuw

ihomer

Added support for Roaming Hubs

Adds support for Platforms with multiple/different roles, additional

roles

Adds support for smart charging

Lots of improvements to existing modules

See changelog

2.1.1-d2 21-06-2019 Robert de Leeuw

ihomer

Fixes the command module documentation, fixes a lot of

examples, lots of small textual improvements: see changelog

2.1.1 08-06-2017 Robert de Leeuw

ihomer

Fixed 4 bugs found in OCPI 2.1, lots of small textual

improvements: see changelog

2.1 08-04-2016 Robert de Leeuw

ihomer

Added command module.

Added support for real-time authorization.

Lots of small improvements: see changelog

2.0-d2 15-02-2016 Robert de Leeuw

ihomer

2nd documentation revision of the OCPI 2.0 spec.

Only documentation updated: ConnectorType of Connector

was not visible, credentials clarified, location URL

segments incorrect (now string, was int),

minor textual updates.

DateTime with timezones is still an issue

2.0 30-12-2015 Robert de Leeuw

ihomer

Simon Philips

Becharged

Chris Zwirello

The New Motion

Simon Schilling

First official release of OCPI.

0.4 04-11-2014 Olger Warnier

The New Motion

First draft of OCPI. (Also known as Draft v4)

0.3 06-05-2014 Olger Warnier

The New Motion

First draft of OCPI. (Also known as Draft v3)

Document revisions There can be multiple documentation revisions of the same version of the OCPI protocol.

The newer documentation revisions of the same protocol version can never change the content of the messages: no new fields or

renaming of fields. A new revision can only clarify/fix texts/descriptions and fix typos etc.

These documentation revisions (not the first) will be named: d2, d3, d4 etc.

Examples:

• OCPI 2.1.1 is a different protocol version of OCPI than OCPI 2.1.

• OCPI 2.2-d2 is the same protocol version as OCPI 2.2, but a newer documentation revision.

OCPI 2.2-d2

1. OCPI

1.1. OCPI 2.2

OCPI 2.2 includes new functionality and improvements, compared to OCPI 2.1.1.

1.1.1. Changes/New functionality:

• Support for Hubs

• Message routing headers

• Hub Client Info

• Support Platforms with multiple/different roles, additional roles

• Charging Profiles

• Preference based Smart Charging

• Improvements:

• CDRs: Credit CDRs, VAT, Calibration law/Eichrecht support, Session_id, AuthorizationReference, CdrLocation,

CdrToken

• Sessions: VAT, CdrToken, How to add a Charging Period

• Tariffs: Tariff types, Min/Max price, reservation tariff, Much more examples

• Locations: Multiple Tariffs, Lost of small improvements

• Tokens: Group_id, energy contract

• Commands: Cancel Reservation added

For more information on detailed changes see changelog.

1.1.2. OCPI 2.2-d2

This new documentation revision of OCPI 2.2 contains textual improvements and fixes to JSON examples. The Tariff module

contains most of the improvements, and especially step_size needed a much better explanation and examples.

Many thanks to all the contributors that have taken the time and effort to commit issues and pushed pull requests with

improvements.

1.2. Introduction and background

The Open Charge Point Interface (OCPI) enables a scalable, automated EV roaming setup between Charge Point Operators and e-

Mobility Service Providers. It supports authorization, charge point information exchange (including live status updates and

transaction events), charge detail record exchange, remote charge point commands and the exchange of smart-charging related

information between parties.

It offers market participants in EV an attractive and scalable solution for (international) roaming between networks, avoiding the

costs and innovation-limiting complexities involved with today’s non-automated solutions or with central roaming hubs. As such it

helps to enable EV drivers to charge everywhere in a fully-informed way, helps the market to develop quickly and helps market

players to execute their business models in the best way.

What does it offer (main functionality):

• A good roaming system (for bilateral usage and/or via a hub).

• Real-time information about location, availability and price.

OCPI 2.2-d2

• A uniform way of exchanging data (Notification Data Records and Charge Data Records), before during and after the

transaction.

• Remote mobile support to access any Charge Point without pre-registration.

An international group of over 200 companies from all over the world already supports OCPI. Initiators are EV Box, New Motion,

ElaadNL, BeCharged, GreenFlux and Last Mile Solutions. Other participants include: Next Charge, Freshmile, Plugsurfing, E55C,

GIREVE, OCN, ihomer, Rexel, Stromnetz Hamburg, Enervalis, Place to plug, Plugsurfing, Ecomovement, Allego, Gronn Kontakt

Norway, ENIO, Fastned, AvantIT, Chargemap, Involtum, Capitol Region Denmark, Vattenfall, EON, ECY Conseil Emeric Chardiny,

Eneco Mobility, Jedlix, MTC, Smartlab, Sodetrel, XXIMO, Mnemonics, Share & Charge, Service House, Alfen / ICU, PI2

Consultancy, Pitpoint, Blue Corner, Building Energy, Chargestorm, Chargepoint, ESARJ, Chargelab.co, MUVEXT, Next Green Car /

Zap Map, Be Mo Tech, Parking Eagle, GraphDefined, Chargecloud, Rutgerplantengaconsulting, Everon, Tanqyou, Electric Vehicle

Association Scotland (EVA NCS), EV-Tech, Plugin Power, Last Mile Solutions, BIA Power, IBIL, Gridscape, Maxem, Virta,

EasyCharger, Total EV Charge, Gowithflow, EKAROS, Rexel US, Stekker App, Travelcard, Emobility Consulting. The EVRoaming

foundation supported by the Netherlands Knowledge Platform for Charging Infrastructure (NKL) facilitates and coordinates this

protocol to guarantee progress and ensure development and results.

This document describes a combined set of standards based on the work done in the past. Next to that, the evolution of these

standards and their use are taken into account and some elements have been updated to match nowadays use.

OCPI is developed with support of:

evRoaming4EU project and its partners:

https://www.evroaming4.eu

ECISS project and its partners:

https://www.nklnederland.nl/eciss

The latest version of this specification can be found here: https://github.com/ocpi/ocpi

OCPI 2.2-d2

2. Terminology and Definitions

2.1. Requirement Keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",

"MAY", and "OPTIONAL" in this document are to be interpreted as described in https://www.ietf.org/rfc/rfc2119.txt.

2.2. Abbreviations

Abbr. Description

CDR Charge Detail Record.

CPO Charging Point Operator.

eMSP e-Mobility Service Provider.

EV Electric Vehicle.

EVSE Electric Vehicle Supply Equipment. Is considered as an independently operated and managed part of a

Charge Point that can deliver energy to one EV at a time.

JSON JavaScript Simple Object Notation.

NAP National Access Point.

NSP Navigation Service Provider.

OCPP Open Charge Point Protocol.

SCSP Smart Charging Service Provider.

2.3. EV Charging Market Roles

In the EV Charging landscape, different market roles can be identified.

Role Description

CPO Charging Point Operator. Operates a network of Charge Points.

eMSP e-Mobility Service Provider. Gives EV drivers access to charging services.

Hub Can connect one or more CPOs to one or more eMSPs.

NAP National Access Point. Provides a national database with all (public) charging locations.

Information can be sent and retrieved from the NAP. This makes it different from a typical NSP.

NSP Navigation Service Provider. Provides EV drivers with location information of Charge Points.

Usually only interested in Location information.

Roaming Hub See: Hub.

SCSP Smart Charging Service Provider. Provides Smart Charging service to other parties. Might use a

lot of different inputs to calculate Smart Charging Profiles.

Some of these roles can be combined in one company. A Platform can provide service for multiple CPOs or eMSPs, but also for

both eMSPs and CPOs.

OCPI 2.2-d2

OCPI 2.0/2.1.1 had a very strict definition of roles: only CPO and eMSP. But this is rare in the real world, there are almost no

parties that are strictly CPO or eMSP and have their own platform. In the real world, lots of parties provide service to CPOs that are

not running their own platform. A lot of CPOs are also eMSP. With OCPI 2.1.1 and earlier that meant having to set up an OCPI

connection per role.

OCPI 2.2 introduces more roles and abstracts the role from the OCPI connection itself. OCPI 2.2 talks about Platforms connecting

to Platforms, or Platforms connecting via Hubs to other Platforms. The Platform itself is not a role. The Platform provides services

for 1 or more roles.

Examples of platforms:

• A pure CPO: Not providing services to other CPOs. Not being an eMSP. Running its own software that connects via OCPI.

Is defined in OCPI as a Platform has 1 CPO role, the CPO role of that company.

• A Company that has a cloud-based eMSP software solution, it offers to companies that want to be eMSP, but don’t want to

host/run their own software.

Is a Platform that has a number of eMSP roles, one for each eMSP the company is providing services for. Not for this

company itself because the company itself is not an eMSP.

• A Company that operates public Charge Points and also provides eMSP service to EV drivers, running their own software

platform.

Is seen in OCPI as a Platform that has 2 roles: CPO and eMSP for this company.

• If one the companies above starts to offer their service to other CPOs and eMSP, it is in OCPI still seen as 1 platform. This

platform then provides multiple CPO and eMSP roles.

2.3.1. Typical OCPI implementations per Role

The following table shows the typical modules implemented by the different roles. These are not required. The table shows the

typical communication role: Receiver, Sender or Both.

Modules CPO eMSP Hub NSP NAP SCSP

CDRs Sender Receiver Both

Charging Profiles Receiver Both Sender

Commands Receiver Sender Both

Credentials Both Both Both Both Both Both

Hub Client Info Receiver Receiver Sender Receiver Receiver Receiver

Locations Sender Receiver Both Receiver Both

Sessions Sender Receiver Both Receiver

Tariffs Sender Receiver Both Receiver Both

Tokens Receiver Sender Both

Versions Both Both Both Both Both Both

2.4. Terminology

Term Description

Broadcast Push When communicating via a Hub, a data owner can do a single call to the Hub, the Hub then calls

all receiving systems.

See: Broadcast push

OCPI 2.2-d2

Term Description

Charge Point The physical system where an EV can be charged. A Charge Point has one or more EVSEs.

Sometimes called Charging Station

Client Owned Objects In a normal REST interface the server is the owner of data, when a new resource is created by

calling POST, the server creates the URL where the resource can be found by a client.

OCPI is different, in most modules the owner is the party pushing data to a server, to inform

them of updates.

For example Locations, the CPO owns a Location (Charge Point), when a new Charge Point is

added, the CPO calls PUT on the eMSP systems to inform them about new locations.

See: Client Owned Objects

Configuration Module OCPI Module needed to setup and maintain OCPI connections, but does not provide information

for the EV driver: Credentials, Versions and Hub Client Info.

Configuration Modules use message routing.

Functional Module OCPI Module that provides functionality/information for the EV Driver, such as: Tokens,

Locations, CDRs etc.

Functional Modules do NOT use message routing.

Open Routing Request This is for Platforms that are connected via a Hub. When a system sends a pull request to the

Hub, and does not know, or care about, the owner of information, but asks the Hub to route the

GET to the correct Platform. The Hub finds the correct Platform and routes the request to that

Platform.

See: Open Routing Request

Platform Software that provides services via OCPI. A platform can provide service for a single eMSP or

CPO, or for multiple CPOs or eMSPs. It can even provide services for both eMSPs and CPOs at

the same time.

Pull A system calls GET request to retrieve information from the system that owns the data.

Push The system (owning the data) actively calls POST/PUT/PATCH to update other systems with

new/updated information.

2.5. Provider and Operator abbreviation

In OCPI it is advised to use eMI3 compliant names for Contract IDs and EVSE IDs. The provider and the operator name is

important here, to target the right provider or operator, they need to be known upfront, at least between the cooperating parties.

In several standards, an issuing authority is mentioned that will keep a central registry of known Providers and Operators. At this

moment, the following countries have an authority that keeps track of the known providers and operators:

2.5.1. The Netherlands, Belgium and Luxembourg (BeNeLux)

The Dutch foundation, named eViolin keeps the registry for The Netherlands, Belgium and Luxembourg.

• The list of operator IDs and provider IDs can be viewed on their website eViolin/Leden.

2.5.2. Germany

The BDEW organisation keeps the registry for Germany in their general code number service bdew-codes.de.

• Provider ID List See https://bdew-codes.de/Codenumbers/EMobilityId/ProviderIdList

• EVSE Operator ID List See https://bdew-codes.de/Codenumbers/EMobilityId/OperatorIdList

OCPI 2.2-d2

2.5.3. Austria

Austrian Mobile Power GmbH maintains a registry for Austria. This list is not publicly available. For more information visit austrian-

mobile-power.at

2.5.4. France

The AFIREV* organization will keep/keeps the registry for France. It provides operation Id for CPO and eMSP in compliance with

eMI3 id structure. The prefix of these Ids is the “fr” country code. AFIREV will also be in charge of the definition of EVSE-Id

structure, Charging-Pool-Id structure (location), and Contract-Id structure for France. AFIREV bases its requirements and

recommendations on eMI3 definitions.

AFIREV stands for: Association Française pour l’Itinérance de la Recharge Électrique des Véhicules

2.6. Charging topology

The charging topology, as relevant to the eMSP, consists of three entities:

• Connector is a specific socket or cable available for the EV to make use of.

• EVSE is the part that controls the power supply to a single EV in a single session. An EVSE may provide multiple

connectors but only one of these can be active at the same time.

• Location is a group of one or more EVSEs that belong together geographically or spatially.

EVSE A3

EVSE A2

EVSE A1

Location A

EVSE B1

Location B

EVSE B4

Connectors

EVSE B3

Connectors

EVSE B2

Figure 1. Charging Topology schematic

A Location is typically the exact location of one or more EVSEs, but it can also be the entrance of a parking garage or a gated

community. It is up to the CPO to use whatever makes the most sense in a specific situation. Once arrived at the location, any

further instructions to reach the EVSE from the Location are stored in the EVSE object itself (such as the floor number, visual

identification or manual instructions).

OCPI 2.2-d2

2.7. Variable names

To prevent issues with capitals in variable names, the naming in JSON is not CamelCase but snake_case. All variables are

lowercase and include an underscore for a whitespace.

2.8. Cardinality

When defining the cardinality of a field, the following symbols are used throughout this document:

Symbol Description Type

? An optional object. If not set, it might be null, or the field might be omitted. When the field is set to null or

omitted and it has a default value, the value is the default value.

Object

1 Required object. Object

* A list of zero or more objects. If empty, it might be null, [] or the field might be omitted. [Object]

+ A list of at least one object. [Object]

2.9. Data Retention

OCPI does not specify how long a system should store data. Companies are RECOMMENDED to make this part of business

contracts. Parties also will need to oblige to local legislation.

2.9.1. Between OCPI version

When a new version of OCPI is implemented, the data exchanged via the old version does not have to be available via the newer

version of OCPI. Hence, the Version end-point will probably have different end-points per version. So when an object is stored with

a URL that contains a version, it is NOT REQUIRED to be available at a URL with a different version number.

OCPI 2.2-d2

3. Supported Topologies

OCPI started as a bilateral protocol, for peer-to-peer communication. Soon parties started to use OCPI via Hubs, but OCPI 2.1.1

and earlier were not designed for that. OCPI 2.2 introduces a solution for this: message routing.

OCPI 2.2 introduces Platforms that connect via OCPI instead of CPO and eMSP, more on this in: EV Charging Market Roles

3.1. Peer-to-peer

The simplest topology is a bilateral connection: peer-to-peer between two platforms, and in the most simple version each platform

only has 1 role.

PLATFORM PLATFORM

eMSP

CPO

OCPI

Figure 2. peer-to-peer topology example

3.2. Multiple peer-to-peer connections

A more real-world topology where multiple parties connect their platforms and each platform only has 1 role. (Not every party

necessarily connects with all the other parties with the other role).

PLATFORM PLATFORMPLATFORM PLATFORM

PLATFORM

eMSP1 eMSP2eMSP3 eMSP4

CPO1CPO2 CPO3

OCPI

Figure 3. Multiple peer-to-peer topology example

OCPI 2.2-d2

3.3. Peer-to-peer multiple the same roles

Some parties provide for example CPO or eMSP services for other companies. So the platform hosts multiple parties with the same

role. This topology is a bilateral connection: peer-to-peer between two platforms, and both platforms can have multiple roles.

PLATFORM

eMSP1

eMSP2

eMSP3

CPO1

CPO2

OCPI

Figure 4. peer-to-peer with multiple roles topology example

3.4. Peer-to-peer dual roles

Some parties have dual roles, most of the companies are CPO and eMSP. This topology is a bilateral connection: peer-to-peer

between two platforms, and both platforms have the CPO and the eMSP roles.

PLATFORM

eMSP1

CPO1

eMSP2

CPO2

OCPI

Figure 5. peer-to-peer with both CPO and eMSP roles topology example

OCPI 2.2-d2

3.5. Peer-to-peer mixed roles

Some parties have dual roles, or provide them to other parties and then connect to other companies that do the same. This

topology is a bilateral connection: peer-to-peer between two platforms, and both platforms have multiple different and also the same

roles.

PLATFORM PLATFORM

eMSP1

eMSP2

CPO1

CPO2

eMSP4

CPO5

CPO6

CPO7

OCPI

Figure 6. peer-to-peer with mixed roles topology example

OCPI 2.2-d2

3.6. Multiple peer-to-peer

More a real-world topology when OCPI is used between market parties without a hub, all parties are platforms with multiple roles.

Disadvantage of this: requires a lot of connections between platforms to be setup, tested and maintained.

PLATFORM

eMSP1

eMSP2

CPO1

CPO2

eMSP3

CPO3

eMSP4

CPO4

OCPI

Figure 7. peer-to-peer with mixed roles topology example

OCPI 2.2-d2

3.7. Platforms via Hub

This topology has all Platforms only connect via a Hub, all communication goes via the Hub.

PLATFORM

eMSP1

CPO1

eMSP3

eMSP4

eMSP5

eMSP2

CPO2

CPO3

CPO4

CPO5

Hub

OCPI

Figure 8. Platforms connected via a Hub topology example

OCPI 2.2-d2

3.8. Platforms via Hub and direct

Not all Platforms will only communicate via a Hub. There might be different reasons for Platforms to still have peer-to-peer

connections. The Hub might not yet support new functionality. The Platforms use a custom module for some new project, which is

not supported by the Hub. etc.

PLATFORM

eMSP1

CPO1

eMSP3

eMSP4

eMSP5

eMSP2

CPO2

CPO3

CPO4

CPO5

Hub

OCPI

Figure 9. Platforms connected via a Hub and directly topology example

OCPI 2.2-d2

4. Transport and format

4.1. JSON / HTTP implementation guide

The OCPI protocol is based on HTTP and uses the JSON format. It follows a RESTful architecture for web services where possible.

4.1.1. Security and authentication

The interfaces are protected on the HTTP transport level, with SSL and token-based authentication. Please note that this

mechanism does not require client-side certificates for authentication, only server-side certificates to set up a secure SSL

connection.

4.1.2. Authorization header

Every OCPI HTTP request MUST add an 'Authorization' header. The header looks as follows:

Authorization: Token IpbJOXxkxOAuKR92z0nEcmVF3Qw09VG7I7d/WCg0koM=

The literal 'Token' indicates that the token-based authentication mechanism is used, in OCPI this is called the 'credentials token'.

'Credentials tokens' are exchanged via the credentials module. These are different 'tokens' then the Tokens exchanged via the

Token Module: Tokens used by drivers to authorize charging. To prevent confusion, when talking about the token used here in the

HTTP Authorization header, call them: 'Credentials Tokens'.

Its parameter is a string consisting of printable, non-whitespace ASCII characters. It contains the 'credentials token' Base64

encoded.

The credentials token must uniquely identify the requesting party. This way, the server can use the information in the Authorization

header to link the request to the correct requesting party’s account.

If the header is missing or the credentials token doesn’t match any known party then the server SHALL respond with an HTTP 401

- Unauthorized status code.

When a server receives a request with a valid CREDENTIALS_TOKEN_A, on another module then: credentials or versions,

the server SHALL respond with an HTTP 401 - Unauthorized status code.

4.1.3. Pull and Push

OCPI supports both Pull and Push models.

• Push: Changes in objects and new objects are sent (semi) real-time to the receiver.

• Pull: Receiver request a (full) list of objects every X times.

OCPI doesn’t require parties to implement Push. Pull is required, a receiver needs to be able to get in-sync after a period of

connection loss.

It is possible to implement a Pull only OCPI implementation, it might be a good starting point for an OCPI implementation. However,

it is strongly advised to implement Push for production systems that have to handle some load, especially when several clients are

requesting long lists frequently. Push implementations tend to use fewer resources. It is therefore advised to clients pulling lists from

a server to do this on a relative low polling interval: think in hours, not minutes, and to introduce some splay (randomize the length

of the poll interface a bit).

OCPI 2.2-d2

4.1.4. Request format

The request method can be any of GET, POST, PUT, PATCH or DELETE. The OCPI protocol uses them in a way similar to REST

APIs.

Method Description

GET Fetches objects or information.

POST Creates new objects or information.

PUT Updates existing objects or information.

PATCH Partially updates existing objects or information.

DELETE Removes existing objects or information.

The HTTP header: Content-Type SHALL be set to application/json for any request that contains a message body: POST,

PUT and PATCH. When no body is present, probably in a GET or DELETE, then the Content-Type header MAY be omitted.

4.1.4.1. GET

A server is not required to return all objects to a client, the server might for example not send all CDRs to a client, because some

CDRs do not belong to this client.

When a client receives objects from the server that contain invalid JSON or invalid OCPI objects (For example: missing fields), the

client has no way of letting this know to the server. It is advised to log these errors and contact the server administrator about this.

When a list of objects contains some objects that are correct and some with 'problems' the client should at least process the correct

OCPI objects.

Pagination

All GET methods that return a list of objects have pagination, this allows a client and server to control the number of objects

returned in the response to a GET request, while still enabling the client to retrieve all objects by doing multiple requests with

different parameters. Without pagination, the server has to return all objects in one response that could potentially contain millions

of objects.

To enable pagination of the returned list of objects, additional URL parameters are allowed for the GET request and additional

headers need to be added to the response.

Paginated Request

The following table lists all the parameters that have to be supported but might be omitted by a client request.

Parameter Datatype Description

date_from DateTime Only return objects that have last_updated after or equal to this Date/Time (inclusive).

date_to DateTime Only return objects that have last_updated up to this Date/Time, but not including (exclusive).

offset int The offset of the first object returned. Default is 0 (the first object).

limit int The maximum number of objects to GET. The server might decide to return fewer objects, either

because there are no more objects, or the server limits the maximum number of objects to

return. This is to prevent, for example, overloading the system.

The date_from is inclusive and date_to exclusive, this way, when sequential requests with to the same end-point are done, the

next interval will have no overlap and the date_from of the next interval is simply the date_to of the previous interval.

OCPI 2.2-d2

Example: With offset=0 and limit=10 the server shall return the first 10 records (if 10 objects match the request). Then the next

page starts with offset=10.

Paginated Response

For pagination to work correctly, it is important that multiple calls to the same URL (including query parameters): result in the same

objects being returned by the server. For this to be the case, the sequence of objects mustn’t change, or as little as possible. It is

best practice to return the oldest (by creation date, not the last_updated field) first. While a client crawls over the pages (multiple

GET requests every time to the 'next' page Link), a new object might be created on the server. The client detects this: the X-

Total-Count will be higher on the next call. But the client doesn’t have to correct for this. Only the last page will be different (or an

additional page). So the client will not be required to crawl all pages all over again when the client has reached to last page it has

retrieved all relevant pages and is up to date.

NOTE

Some query parameters can cause concurrency problems. For example the date_to query parameter. When

there are for example 1000 objects matching a query for all objects with date_to before 2016-01-01. While

crawling over the pages one of these objects is updated. The client detects this: X-Total-Count will be lower in

the next request. It is advised to redo the previous GET but then with the offset lowered by 1 (if the offset

was not 0) and after that continue crawling the 'next' page links. When an object before this page has been

updated, then the client has missed 1 object.

HTTP headers that have to be added to any paginated GET response.

HTTP Header Datatype Description

Link String Link to the 'next' page should be provided when this is NOT the last page. The Link

should also contain any filters present in the original request. See the examples

below.

X-Total-Count int (Custom HTTP Header) The total number of objects available in the server system

that match the given query (including the given query parameters, for example:

date_to and date_from but excluding limit and offset) and that are available

to this client. For example: The CPO server might return less CDR objects to an

eMSP then the total number of CDRs available in the CPO system.

X-Limit int (Custom HTTP Header) The maximum number of objects that the server can return.

Note that this is an upper limit. If there are not enough remaining objects to return,

fewer objects than this upper limit number will be returned, X-Limit SHALL then still

show the upper limit, not the number of objects returned.

Pagination Examples

Example of a required OCPI pagination link header:

Link: <https://www.server.com/ocpi/cpo/2.2/cdrs/?offset=150&limit=50>; rel="next"

After the client has called the given "next" page URL above the Link parameter will most likely look like this:

Link: <https://www.server.com/ocpi/cpo/2.2/cdrs/?offset=200&limit=50>; rel="next"

Example of a query with filters: Client does a GET to:

https://www.server.com/ocpi/cpo/2.2/cdrs/?date_from=2016-01-01T00:00:00Z&date_to=2016-12-31T23:59:59Z

The server should return (when the server has enough objects and the limit is the amount of objects the server wants to send is

100.) (This example should have been on 1 line, but didn’t fit the paper width.)

OCPI 2.2-d2

Link: <https://www.server.com/ocpi/cpo/2.2/cdrs/?offset=100

&limit=100&date_from=2016-01-01T00:00:00Z&date_to=2016-12-31T23:59:59Z>; rel="next"

Example of a server limiting the amount of objects returned: Client does a GET to:

https://www.server.com/ocpi/cpo/2.2/cdrs/?limit=2000

The server should return (when the server has enough objects and the limit is the amount of objects the server wants to send is

100.) The X-Limit HTTP header should be set to 100 as well.

Link: <https://www.server.com/ocpi/cpo/2.2/cdrs/?offset=100&limit=100>; rel="next"

4.1.4.2. PUT

A PUT request must specify all required fields of an object (similar to a POST request). Optional fields that are not included will

revert to their default value which is either specified in the protocol or NULL.

4.1.4.3. PATCH

A PATCH request must only specify the object’s identifier (if needed to identify this object) and the fields to be updated. Any fields

(both required or optional) that are left out remain unchanged.

The MIME-type of the request body is: application/json and may contain the data as documented for each endpoint.

In case a PATCH request fails, the client is expected to call the GET method to check the state of the object in the other party’s

system. If the object doesn’t exist, the client should do a PUT.

4.1.5. Client Owned Object Push

Normal client/server RESTful services work in a way where the Server is the owner of the objects that are created. The client

requests a POST method with an object to the end-point URL. The response sent by the server will contain the URL to the new

object. The client will request only one server to create a new object, not multiple servers.

Many OCPI modules work differently: the client is the owner of the object and only pushes the information to one or more servers

for information sharing purposes. For example the CPO owns the Tariff objects and pushes them to a couple of eMSPs, so each

eMSP gains knowledge of the tariffs that the CPO will charge them for their customers' sessions. eMSP might receive Tariff objects

from multiple CPOs. They need to be able to make a distinction between the different tariffs from different CPOs.

The distinction between objects from different CPOs/eMSPs is made based on a {country_code} and {party_id}. The country_code

and party_id of the other party are received during the credentials handshake, so that a server might know the values a client will

use in an URL.

Client Owned Object URL definition: {base-ocpi-url}/{end-point}/{country-code}/{party-id}/{object-id}

Example of a URL to a Client Owned Object

https://www.server.com/ocpi/cpo/2.2/tariffs/NL/TNM/14

POST is not supported for these kinds of modules. PUT is used to send new objects to the servers.

If a client tries to access an object with a URL that has a different country_code and/or party_id then given during the credentials

handshake, it is allowed the respond with an HTTP 404 status code, this way blocking client access to objects that do not belong to

them.

OCPI 2.2-d2

To identify the owner of data, the party generating the information that is provided to other parties via OCPI, a 'Data owner' is

provided at the beginning of every module that has a clear owner.

4.1.5.1. Errors

When a client pushes a Client Owned Object, but the {object-id} in the URL is different from the id in the object being pushed,

server implementations are advised to return an OCPI status code: 2001.

4.1.6. Response format

The content that is sent with all the response messages is an 'application/json' type and contains a JSON object with the following

properties:

Property Type Card. Description

data Array or

Object or

String

* or ? Contains the actual response data object or list of objects from each request,

depending on the cardinality of the response data, this is an array (card. * or +),

or a single object (card. 1 or ?)

status_code int 1 OCPI status code, as listed in Status Codes, indicates how the request was

handled. To avoid confusion with HTTP codes, OCPI status codes consist of

four digits.

status_message string ? An optional status message which may help when debugging.

timestamp DateTime 1 The time this message was generated.

For brevity’s sake, any further examples used in this specification will only contain the value of the "data" field. In reality, it will

always have to be wrapped in the above response format.

When a request cannot be accepted, the type response depends on the type of error. For more information see: Status codes

For errors on the HTTP layer, use HTTP error response codes, including the response format above, that contains more details.

HTTP status codes are described on w3.org.

4.1.6.1. Example: Version information response (list of objects)

{

"data": [{

"version": "2.1.1",

"url": "https://example.com/ocpi/cpo/2.1.1/"

}, {

"version": "2.2",

"url": "https://example.com/ocpi/cpo/2.2/"

}],

"status_code": 1000,

"status_message": "Success",

"timestamp": "2015-06-30T21:59:59Z"

}

4.1.6.2. Example: Version details response (one object)

OCPI 2.2-d2

{

"data": {

"version": "2.2",

"endpoints": [{

"identifier": "credentials",

"url": "https://example.com/ocpi/cpo/2.2/credentials/"

}, {

"identifier": "locations",

"url": "https://example.com/ocpi/cpo/2.2/locations/"

}]

"status_code": 1000,

"status_message": "Success",

"timestamp": "2015-06-30T21:59:59Z"

}

4.1.6.3. Example: Tokens GET Response with one Token object. (CPO end-point) (one

object)

{

"data": {

"uid": "012345678",

"type": "RFID",

"contract_id": "FA54320",

"visual_number": "DF000-2001-8999",

"issuer": "TheNewMotion",

"valid": true,

"whitelist": "ALLOWED",

"last_updated": "2015-06-29T22:39:09Z"

"status_code": 1000,

"status_message": "Success",

"timestamp": "2015-06-30T21:59:59Z"

}

4.1.6.4. Example: Tokens GET Response with list of Token objects. (eMSP end-point) (list of

objects)

OCPI 2.2-d2

{

"data": [{

"uid": "100012",

"type": "RFID",

"contract_id": "FA54320",

"visual_number": "DF000-2001-8999",

"issuer": "TheNewMotion",

"valid": true,

"whitelist": "ALWAYS",

"last_updated": "2015-06-21T22:39:05Z"

}, {

"uid": "100013",

"type": "RFID",

"contract_id": "FA543A5",

"visual_number": "DF000-2001-9000",

"issuer": "TheNewMotion",

"valid": true,

"whitelist": "ALLOWED",

"last_updated": "2015-06-28T11:21:09Z"

}, {

"uid": "100014",

"type": "RFID",

"contract_id": "FA543BB",

"visual_number": "DF000-2001-9010",

"issuer": "TheNewMotion",

"valid": false,

"whitelist": "ALLOWED",

"last_updated": "2015-05-29T10:12:26Z"

}],

"status_code": 1000,

"status_message": "Success",

"timestamp": "2015-06-30T21:59:59Z"

}

4.1.6.5. Example: Response with an error (contains no data field)

{

"status_code": 2001,

"status_message": "Missing required field: type",

"timestamp": "2015-06-30T21:59:59Z"

}

4.1.7. Message Routing

When the development of OCPI was started, it was designed for peer-to-peer communication between CPO and eMSP. This has

advantages, but also disadvantages. Having to set up and maintain OCPI connections to a lot of parties requires more effort than

doing it for only a couple of connections. By communication via one or more Hubs, the amount of OCPI connections is reduced,

while still being able to offer roaming to a lot of different parties and customers.

With the introduction of Message Routing, OCPI is now better usable for communication via Hubs.

All examples/sequence diagrams in this section use the roles CPO and eMSP as examples, they could be switched, it could be

other roles.

4.1.7.1. Platforms

With Message Routing functionality it also becomes possible to support Platforms that host multiple roles. A lot of parties are not

only CPO or eMSP. Most are both CPO and eMSP. Some parties are doing business in multiple counties, which means to operate

with different country_codes Some parties have a platform on which the host service for other CPOs/eMSPs. Some parties are

themselves CPO and host CPO services for others, but other parties are (themselves) not a CPO or other role in the EV charging

landscape but do provide service to CPOs/eMSPs, etc.

OCPI 2.2-d2

4.1.7.2. Message Routing Headers

When OCPI is used to communicate to/from a Platform or via a Hub (which is almost always the case) the following four HTTP

headers are to be added to any request/response to allow messages to be routed.

When implementing OCPI these four headers SHALL be implemented for any request/response to/from a Functional Module. This

does not mean they have to be present in all request. There are situation/special request where some headers can or shall be

omitted, more on this later.

Only requests/responses from Function Modules: such as: Tokens, Locations, CDRs etc. SHALL be routed, so need the routing

headers.

The requests/responses to/from Configuration Modules: Credentials, Versions and Hub Client Info are not to be routed, and are for

Platform-to-Platform or Platform-to-Hub communication. Thus routing headers SHALL NOT be used with these modules.

HTTP Header Datatype Description

OCPI-to-party-id CiString(3) 'party id' of the connected party this message is to be sent to.

OCPI-to-country-code CiString(2) 'country code' of the connected party this message is to be sent to.

OCPI-from-party-id CiString(3) 'party id' of the connected party this message is sent from.

OCPI-from-country-

code

CiString(2) 'country code' of the connected party this message is sent from.

CPO1

HUB

MSP1

HTTP: GET

TO: MSP1

FROM: CPO1

HTTP: GET

TO: MSP1

FROM: CPO1

HTTP: RESPONSE

TO: CPO1

FROM: MSP1

HTTP: RESPONSE

TO: CPO1

FROM: MSP1

Figure 10. Example sequence diagram of a GET for 1 Object from a CPO to an eMSP.

OCPI 2.2-d2

CPO1

HUB1 HUB2

MSP1

HTTP: PUT

TO: MSP1

FROM: CPO1

HTTP: PUT

TO: MSP1

FROM: CPO1

HTTP: PUT

TO: MSP1

FROM: CPO1

HTTP: RESPONSE 200

TO: CPO1

FROM: MSP1

HTTP: RESPONSE 200

TO: CPO1

FROM: MSP1

HTTP: RESPONSE 200

TO: CPO1

FROM: MSP1

Figure 11. Example sequence diagram of a PUT via 2 Hubs.

4.1.7.3. Broadcast Push

For simplicity, connected clients might push (POST, PUT, PATCH) information to all connected clients with an "opposite role", for

example: CPO pushing information to all eMSPs and NSPs, eMSP pushing information to all CPOs. (The role "Other" is seen as an

eMSP type of role, so Broadcast Push from a CPO is also sent to "Other". Messages from "Other" are only sent to CPOs and not to

eMSPs though.)

When using Broadcast Push, the Hub broadcasts received information to all connected clients. To send data through a Hub might

be very useful to share information like Locations or Tokens with all parties connected to the Hub that have implemented the

corresponding module. This means only one request to the Hub will be necessary, as all connected clients will be served by the

Hub.

To send a Broadcast Push, the client uses the party-id and country-code of the Hub in the 'OCPI-to-' headers. The Hub parses the

request and sends a response to the client, which optionally contains its own party-id and country-code in the 'OCPI-from-'

headers. The Hub then sends the pushed data to any client implementing the corresponding applicable module, using its own

party-id and country-code in the 'OCPI-from-' headers. The client receiving a Push from a Hub (with the Hubs information in the

'OCPI-from-' headers) will respond to this Push with the Hubs party-id and country-code in the 'OCPI-to-' headers.

GET SHALL NOT be used in combination with Broadcast Push. If the requesting party wants to GET information of which it does

not know the receiving party, an Open Routing Request MUST be used. (see below)

Broadcast Push SHALL only be used with information that is meant to be sent to all other parties. It is useful to share data like

Tokens and Locations, but not so much for CDRs and Sessions as these pieces of information are specific to only one party and

are possibly even protected by GDPR or other laws.

NOTE

For "Client Owned Objects", the party-id and country-code in the URL segments will still be the original party-id

and country-code from the original client sending the Broadcast Push to the Hub.

OCPI 2.2-d2

CPO1

HUB

MSP1 MSP2 MSP3

HTTP: PUT

TO: HUB

FROM: CPO1

HTTP: RESPONSE 200?

TO: CPO1

FROM: HUB

HTTP: PUT

TO: MSP1

FROM: HUB

HTTP: RESPONSE 401

TO: HUB

FROM: MSP1

HTTP: PUT

TO: MSP2

FROM: HUB

HTTP: RESPONSE 200

TO: HUB

FROM: MSP2

HTTP: PUT

TO: MSP3

FROM: HUB

HTTP: RESPONSE 200

TO: HUB

FROM: MSP3

Figure 12. Example sequence diagram of a Broadcast Push from a CPO to multiple eMSPs.

4.1.7.4. Open Routing Request

When a Hub has the intelligence to route messages based on the content of the request, or the requesting party does not know the

destination of a request, the 'OCPI-to-' headers can be omitted in the request towards the Hub. The Hub can then decide to which

party a request needs to be routed, or that it needs to be broadcasted if the destination cannot be determined.

This has nothing to do with Broadcast Push though, as Broadcast Push only works for the Push model, not for GET requests.

Open Routing Requests are possible for GET (Not GET ALL), POST, PUT, PATCH and DELETE.

OCPI 2.2-d2

CPO1

HUB

eMSP1 eMSP2 eMSP3

HTTP: GET

FROM: CPO1

Determine

routing

HTTP: GET

TO: MSP2

FROM: CPO1

HTTP: RESPONSE 200

TO: CPO1

FROM: MSP2

HTTP: RESPONSE 200

TO: CPO1

FROM: MSP2

Figure 13. Example sequence diagram of a open routing GET from a CPO via the Hub.

4.1.7.5. GET All via Hubs

A client (Receiver) can request a GET on the Sender interface of a module implemented by a Hub. To request a GET All from a

Hub, the client uses the party-id and country-code of the Hub in the 'OCPI-to-' headers, and calls the GET method on the Sender

interface of a module.

The Hub can then combine objects from different connected parties and return them to the client.

The client can determine the owner of the objects by looking at the county_code and party_id in the individual objects returned

by the hub.

OCPI 2.2-d2

CPO1

HUB

eMSP1 eMSP2 eMSP3

HTTP: PUT

TO:HUB

FROM: MSP1

HTTP: RESPONSE 200

TO: MSP1

FROM: HUB

HTTP: PUT

TO:HUB

FROM: MSP3

HTTP: RESPONSE 200

TO: MSP3

FROM: HUB

HTTP: PUT

TO:HUB

FROM: MSP2

HTTP: RESPONSE 200

TO: MSP2

FROM: HUB

HTTP: GET

TO:HUB

FROM: CPO1

HTTP: RESPONSE 200

TO: CPO1

FROM: HUB

Figure 14. Example sequence diagram of a GET All via the Hub, .

4.1.7.6. Overview of required/optional routing headers for different scenarios

The following section shows which headers are required/optional and which 'OCPI-to-'/'OCPI-from-' IDs need to be used.

This is not an exclusive list, combinations are possible.

Party to Party (without Hub)

This table contains the description of which headers are required to be used for which message when a request is sent directly

from one platform provider to another platform provider, without a Hub in between. The headers are addressing the parties to/from

which the message is sent, not the platform itself.

Name Route TO Headers FROM Headers

Direct request Requesting platform provider to

Receiving platform provider

Receiving-party Requesting-party

Direct response Receiving platform provider to

Requesting platform provider

Requesting-party Receiving-party

OCPI 2.2-d2

Platform Platform

CPO1 MSP1

HTTP: GET

TO: MSP1

FROM: CPO1

HTTP: RESPONSE

TO: CPO1

FROM: MSP1

Figure 15. Example sequence diagram of a GET for 1 Object from a CPO on one platform to an MSP on another platform directly

(without a Hub)

Party to Party via Hub

This table contains the description of which headers are required to be used for which message when a request is routed from one

platform to another platform via a Hub.

Name Route TO Headers FROM Headers

Direct request Requesting platform to Hub Receiving-party Requesting-party

Direct request Hub to receiving platform Receiving-party Requesting-party

Direct response Receiving platform to Hub Requesting-party Receiving-party

Direct response Hub to requesting platform Requesting-party Receiving-party

Platform Platform

CPO1

HUB

MSP1

HTTP: GET

TO: MSP1

FROM: CPO1

HTTP: GET

TO: MSP1

FROM: CPO1

HTTP: RESPONSE

TO: CPO1

FROM: MSP1

HTTP: RESPONSE

TO: CPO1

FROM: MSP1

Figure 16. Example sequence diagram of a GET for 1 Object from one Platform to another Platform via a Hub

Party to Party Broadcast Push

This table contains the description of which headers are required to be used for which message when a request is a Broadcast

Push to the Hub.

OCPI 2.2-d2

Name Route TO Headers FROM Headers

Broadcast request Requesting platform to Hub Hub Requesting-party

Broadcast response Hub to requesting platform Requesting-party Hub

Broadcast request Hub to receiving platform Receiving-party Hub

Broadcast response Receiving platform to Hub Hub Receiving-party

Platform Platform

CPO1

HUB

MSP1

HTTP: GET

TO: HUB

FROM: CPO1

HTTP: RESPONSE

TO: CPO1

FROM: HUB

HTTP: GET

TO: MSP1

FROM: HUB

HTTP: RESPONSE

TO: HUB

FROM: MSP1

Figure 17. Example sequence diagram of Broadcast Push from one Platform to another Platform via a Hub

Party to Party Open Routing Request

This table contains the description of which headers are required to be used for which message when the routing of a request

needs to be determined by the Hub itself. For an Open Routing Request, the TO headers in the request from the requesting party

to the Hub MUST be omitted.

Name Route TO Headers FROM Headers

Open request Requesting platform to Hub Requesting-party

Open request Hub to receiving platform Receiving-party Requesting-party

Open response Receiving platform to Hub Requesting-party Receiving-party

Open response Hub to requesting platform Requesting-party Receiving-party

OCPI 2.2-d2

Platform Platform Platform Platform

CPO1

HUB

eMSP1 eMSP2 eMSP3

HTTP: GET

FROM: CPO1

Determine

routing

HTTP: GET

TO: MSP2

FROM: CPO1

HTTP: RESPONSE 200

TO: CPO1

FROM: MSP2

HTTP: RESPONSE 200

TO: CPO1

FROM: MSP2

Figure 18. Example sequence diagram of a open routing between platforms GET from a CPO via the Hub

4.1.7.7. GET All via Hubs

This table contains the description of which headers are required to be used when doing a GET All via a Hub. For a GET All via

Hub: The HTTP Method SHALL be GET, The call is to a Senders Interface, the TO headers in the request to the Hub has to be set

to the Hub.

Name Route TO Headers FROM Headers

GET All via Hubs request Requesting platform to Hub Hub Requesting-party

GET All via Hubs response Hub to receiving platform Requesting-party Hub

Platform

CPO1

HUB

HTTP: GET

TO:HUB

FROM: CPO1

HTTP: RESPONSE 200

TO: CPO1

FROM: HUB

Figure 19. Example sequence diagram of a GET All via the Hub, .

4.1.7.8. Timestamps and Objects send via Hubs

When OCPI Objects are sent via Hubs, the last_updated fields SHALL NOT be updated by the Hub.

OCPI 2.2-d2

4.2. Unique message IDs

For debugging issues, OCPI implementations are required to include unique IDs via HTTP headers in every request/response.

HTTP Header Description

X-Request-ID Every request SHALL contain a unique request ID, the response to this request SHALL contain the

same ID.

X-Correlation-ID Every request/response SHALL contain a unique correlation ID, every response to this request

SHALL contain the same ID.

It is advised to used GUID/UUID as values for X-Request-ID and X-Correlation-ID.

When a Hub forwards a request to a party, the request to this party SHALL contain a new unique value in the X-Request-ID HTTP

header, not a copy of the X-Request-ID HTTP header taken from the incoming request that is being forwarded.

When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same

value).

CPO MSP

Request

X-Request-ID: 774321

X-Correlation-ID: 123456

Request

X-Request-ID: 774321

X-Correlation-ID: 123456

Figure 20. Example sequence diagram of the uses of X-Request-ID and X-Correlation-ID in a peer-to-peer topology.

CPO

HUB

MSP

Request

X-Request-ID: 774321

X-Correlation-ID: 123456

Request

X-Request-ID: 991234

X-Correlation-ID: 123456

Response

X-Request-ID: 991234

X-Correlation-ID: 123456

Request

X-Request-ID: 774321

X-Correlation-ID: 123456

Figure 21. Example sequence diagram of the uses of X-Request-ID and X-Correlation-ID in a topology with a Hub.

OCPI 2.2-d2

4.3. Interface endpoints

As OCPI contains multiple interfaces. Different endpoints are available for messaging. The protocol is designed such that the exact

URLs of the endpoints can be defined by each party. It also supports an interface per version.

The locations of all the version-specific endpoints can be retrieved by fetching the API information from the versions endpoint. Each

version-specific endpoint will then list the available endpoints for that version. It is strongly recommended to insert the protocol

version into the URL.

For example: /ocpi/cpo/2.2/locations and /ocpi/emsp/2.2/locations.

The URLs of the endpoints in this document are descriptive only. The exact URL can be found by fetching the endpoint information

from the API info endpoint and looking up the identifier of the endpoint.

Operator interface Identifier Example URL

Credentials credentials

https://example.com/ocpi/cpo/2.2/credentials

Charging location details locations

https://example.com/ocpi/cpo/2.2/locations

eMSP interface Identifier Example URL

Credentials credentials

https://example.com/ocpi/emsp/2.2/credentials

Charging location updates locations

https://example.com/ocpi/emsp/2.2/locations

4.4. Offline behaviour

During communication over OCPI, one of the communicating parties might be unreachable for an undefined amount of time. OCPI

works event-based, new messages and status are pushed from one party to another. When communication is lost, updates cannot

be delivered.

OCPI messages SHOULD NOT be queued. When a client does a POST, PUT or PATCH request and that request fails or times out,

the client should not queue the message and retry the same message again later.

When the connection is re-established, it is up to the target-server of a connection to GET the current status from to source-server

to get back to a synchronized state.

For example:

• CDRs of the period of communication loss can be retrieved with a GET command on the CDRs module, with filters to

retrieve only CDRs of the period since the last CDR has been received.

• Status of EVSEs (or Locations) can be retrieved by calling a GET on the Locations module.

OCPI 2.2-d2

5. Status codes

There are two types of status codes:

• Transport related (HTTP)

• Content related (OCPI)

The transport layer ends after a message is correctly parsed into a (semantically unvalidated) JSON structure. When a message

does not contain a valid JSON string, the HTTP error 400 - Bad request MUST be returned.

If a request is syntactically valid JSON and addresses an existing resource, a HTTP error MUST NOT be returned. Those requests

are supposed to have reached the OCPI layer.

In case of a GET request, when the resource does NOT exist, the server SHOULD return a HTTP 404 - Not Found.

When the server receives a valid OCPI object it SHOULD respond with:

• HTTP 200 - Ok when the object already existed and has successfully been updated.

• HTTP 201 - Created when the object has been newly created in the server system.

Requests that reach the OCPI layer SHOULD return an OCPI response message with a status_code field as defined below.

Custom status code range values SHALL NOT be used by standard OCPI module as described in this document! When custom

status codes are used, keep in mind that different custom modules could use the same values with a different meaning, as they are

not standardized.

Range Description

1xxx Success

2xxx Client errors – The data sent by the client can not be processed by the server

3xxx Server errors – The server encountered an internal error

When the status code is in the success range (1xxx), the data field in the response message SHOULD contain the information as

specified in the protocol. Otherwise the data field is unspecified and MAY be omitted, set to null or something else that could

help to debug the problem from a programmer’s perspective. For example, it could specify which fields contain an error or are

missing.

5.1. 1xxx: Success

Code Description

1000 Generic success code

19xx Reserved range for custom success status codes (1900-1999).

5.2. 2xxx: Client errors

Errors detected by the server in the message sent by a client where the client did something wrong.

Code Description

2000 Generic client error

OCPI 2.2-d2

Code Description

2001 Invalid or missing parameters

2002 Not enough information, for example: Authorization request with too little information.

2003 Unknown Location, for example: Command: START_SESSION with unknown location.

2004 Unknown Token, for example: 'real-time' authorization of an unknown Token.

29xx Reserved range for custom client error status codes (2900-2999).

5.3. 3xxx: Server errors

Error during processing of the OCPI payload in the server. The message was syntactically correct but could not be processed by

the server.

Code Description

3000 Generic server error

3001 Unable to use the client’s API. For example during the credentials registration: When the initializing

party requests data from the other party during the open POST call to its credentials endpoint. If

one of the GETs can not be processed, the party should return this error in the POST response.

3002 Unsupported version

3003 No matching endpoints or expected endpoints missing between parties. Used during the

registration process if the two parties do not have any mutual modules or endpoints available, or

the minimal implementation expected by the other party is not been met.

39xx Reserved range for custom server error status codes (3900-3999).

5.4. 4xxx: Hub errors

When a server encounters an error, client side error (2xxx) or server side error (3xxx), it sends the status code to the Hub. The Hub

SHALL then forward this error to the client which sent the request (when the request was not a Broadcast Push).

For errors that a Hub encounters while routing messages, the following OCPI status codes shall be used.

Code Description

4001 Unknown receiver (TO address is unknown)

4002 Timeout on forwarded request (message is forwarded, but request times out)

4003 Connection problem (receiving party is not connected)

49xx Reserved range for custom hub error status codes (4900-4999).

OCPI 2.2-d2

6. Versions module

Type: Configuration Module

This is the required base module of OCPI. This module is the starting point for any OCPI connection. Via this module, clients can

learn which versions of OCPI a server supports, and which modules it supports for each of the versions.

6.1. Version information endpoint

This endpoint lists all the available OCPI versions and the corresponding URLs to where version specific details such as the

supported endpoints can be found.

Endpoint structure definition:

No structure defined. This is open for every party to define themselves.

Examples:

https://www.server.com/ocpi/cpo/versions

https://www.server.com/ocpi/emsp/versions

https://ocpi.server.com/versions

The exact URL to the implemented version endpoint should be given (offline) to parties that want to communicate with your OCPI

implementation.

Both, CPOs and eMSPs MUST implement such a version endpoint.

Method Description

GET Fetch information about the supported versions.

6.1.1. Data

Type Card. Description

Version + A list of supported OCPI versions.

6.1.2. Version class

Property Type Card. Description

version VersionNumber 1 The version number.

url URL 1 URL to the endpoint containing version specific information.

6.1.3. GET

Fetch all supported OCPI versions of this CPO or eMSP.

6.1.3.1. Example

OCPI 2.2-d2

[

{

"version": "2.1.1",

"url": "https://www.server.com/ocpi/2.1.1/"

{

"version": "2.2",

"url": "https://www.server.com/ocpi/2.2/"

}

]

6.2. Version details endpoint

Via the version details, the parties can exchange which modules are implemented for a specific version of OCPI, which interface

role is implemented, and what the endpoint URL is for this interface.

Parties that are both CPO and eMSP (or a Hub) can implement one version endpoint that covers both roles. With the information

that is available in the version details, parties don’t need to implement a separate endpoint per role (CPO or eMSP) anymore. In

practice this means that when a company is both a CPO and an eMSP and it connects to another party that implements both

interfaces, only one OCPI connection is needed.

NOTE

OCPI 2.2 introduces the role field in the version details. Older versions of OCPI do not support this.

Endpoint structure definition:

No structure defined. This is open for every party to define themselves.

Examples:

https://www.server.com/ocpi/cpo/2.2

https://www.server.com/ocpi/emsp/2.2

https://ocpi.server.com/2.2/details

This endpoint lists the supported endpoints and their URLs for a specific OCPI version. To notify the other party that the list of

endpoints of your current version has changed, you can send a PUT request to the corresponding credentials endpoint (see the

credentials chapter).

Both the CPO and the eMSP MUST implement this endpoint.

Method Description

GET Fetch information about the supported endpoints for this version.

6.2.1. Data

Property Type Card. Description

version VersionNumber 1 The version number.

endpoints Endpoint + A list of supported endpoints for this version.

6.2.2. Endpoint class

OCPI 2.2-d2

Property Type Card. Description

identifier ModuleID 1 Endpoint identifier.

role InterfaceRole 1 Interface role this endpoint implements.

url URL 1 URL to the endpoint.

NOTE

for the credentials module, the role is not relevant as this module is the same for all roles.

6.2.3. InterfaceRole enum

Value Description

SENDER Sender Interface implementation. Interface implemented by the owner of data, so the Receiver can

Pull information from the data Sender/owner.

RECEIVER Receiver Interface implementation. Interface implemented by the receiver of data, so the

Sender/owner can Push information to the Receiver.

6.2.4. ModuleID enum

The Module identifiers for each endpoint are described in the beginning of each Module chapter. The following table contains the

list of modules in this version of OCPI. Most modules (except Credentials & Registration) are optional, but there might be

dependencies between modules. If there are dependencies between modules, it will be mentioned in the affected module

description.

Module ModuleID Remark

CDRs cdrs

Charging Profiles chargingprofiles

Commands commands

Credentials & Registration credentials Required for all implementations.

The role field has no function for this module.

Hub Client Info hubclientinfo

Locations locations

Sessions sessions

Tariffs tariffs

Tokens tokens

6.2.5. VersionNumber enum

List of known versions.

Value Description

2.0 OCPI version 2.0

2.1 OCPI version 2.1 (DEPRECATED, do not use, use 2.1.1 instead)

OCPI 2.2-d2

Value Description

2.1.1 OCPI version 2.1.1

2.2 OCPI version 2.2 (this version)

6.2.5.1. Custom Modules

Parties are allowed to create custom modules or customized versions of the existing modules. To do so, the ModuleID enum can be

extended with additional custom moduleIDs. These custom moduleIDs MAY only be sent to parties with which there is an

agreement to use a custom module. Do NOT send custom moduleIDs to parties you are not 100% sure will understand the custom

moduleIDs. It is advised to use a prefix (e.g. country-code + party-id) for any custom moduleID, this ensures that the moduleID will

not be used for any future module of OCPI.

For example: nltnm-tokens

6.2.6. GET

Fetch information about the supported endpoints and their URLs for this OCPI version.

6.2.6.1. Examples

Simple version details example: CPO with only 2 modules.

{

"version": "2.2",

"endpoints": [

{

"identifier": "credentials",

"role": "SENDER",

"url": "https://example.com/ocpi/2.2/credentials/"

{

"identifier": "locations",

"role": "SENDER",

"url": "https://example.com/ocpi/cpo/2.2/locations/"

}

]

}

Simple version details example: party with both CPO and eMSP with only 2 modules.

In this case the credentials module is not defined twice as this module is the same for all roles.

OCPI 2.2-d2

{

"version": "2.2",

"endpoints": [

{

"identifier": "credentials",

"role": "RECEIVER",

"url": "https://example.com/ocpi/2.2/credentials/"

{

"identifier": "locations",

"role": "SENDER",

"url": "https://example.com/ocpi/cpo/2.2/locations/"

{

"identifier": "tokens",

"role": "RECEIVER",

"url": "https://example.com/ocpi/cpo/2.2/tokens/"

{

"identifier": "locations",

"role": "RECEIVER",

"url": "https://example.com/ocpi/msp/2.2/locations/"

{

"identifier": "tokens",

"role": "SENDER",

"url": "https://example.com/ocpi/msp/2.2/tokens/"

}

]

}

OCPI 2.2-d2

7. Credentials module

Module Identifier: credentials

Type: Configuration Module

The credentials module is used to exchange the credentials token that has to be used by parties for authorization of requests.

Every OCPI request is required to contain a credentials token in the HTTP Authorization header.

7.1. Use cases

7.1.1. Registration

To start using OCPI, the Platforms will need to exchange credentials tokens.

To start the exchange of credentials tokens, one platform has to be selected as Sender for the Credentials module. This has to be

decided between the Platforms (outside of OCPI) before they first connect.

To start the credentials exchange, the Receiver Platform must create a unique credentials token: CREDENTIALS_TOKEN_A that has

to be used to authorize the Sender until the credentials exchange is finished. This credentials token along with the versions

endpoint SHOULD be sent to the Sender in a secure way that is outside the scope of this protocol.

The Sender starts the registration process, retrieves the version information and details (using CREDENTIALS_TOKEN_A in the

HTTP Authorization header). The Sender generates a unique credentials token: CREDENTIALS_TOKEN_B, sends it to the Receiver

in a POST request to the credentials module of the Receiver. The Receiver stores CREDENTIALS_TOKEN_B and uses it for any

requests to the Sender Platform, including the version information and details.

The Receiver generates a unique credentials token: CREDENTIALS_TOKEN_C and returns it to the Sender in the response to the

POST request from the Sender.

After the credentials exchange has finished, the Sender SHALL use CREDENTIALS_TOKEN_C in future OCPI request to the

Receiver Platform. The CREDENTIALS_TOKEN_A can then be thrown away, it MAY no longer be used.

(In the sequence diagrams below we use relative paths as short resource identifiers to illustrate API endpoints; please note that

they should be absolute URLs in any working implementation of OCPI.)

OCPI 2.2-d2

OCPI Registration process

Sender

Receiver

Offline

Generate token: CREDENTIALS_TOKEN_A

send information via e-mail

(CREDENTIALS_TOKEN_A,

"https://company.com/ocpi/cpo/versions", ...)

OCPI

GET /ocpi/cpo/versions

The Sender uses CREDENTIALS_TOKEN_A

as authentication to fetch information

from the Receiver.

Available versions

Pick latest mutual version (e.g. 2.2).

GET /ocpi/cpo/2.2/

Available endpoints for v2.2

Store version and endpoints

Generate token: CREDENTIALS_TOKEN_B

POST /ocpi/cpo/2.2/credentials

("/ocpi/emsp/versions", CREDENTIALS_TOKEN_B, ...)

The Receiver does not directly respond to the POST request

The Receiver first needs to retrieve the versions and endpoints

from the Sender before responding with CREDENTIALS_TOKEN_C

Store CREDENTIALS_TOKEN_B

GET /ocpi/emsp/versions

Available versions

GET /ocpi/emsp/2.2/

Available endpoints for v2.2

The Receiver knows it's version 2.2 because

of the endpoint the Sender has used. The URL

is retrieved from the available versions.

Store version and endpoints

The Sender generates CREDENTIALS_TOKEN_C and returns

it in the response to the HTTP POST credentials request

from the Receiver above.

Generate CREDENTIALS_TOKEN_C

Credentials with CREDENTIALS_TOKEN_C for eMSP

By returning new credentials for the Receiver,

the initial setup token (CREDENTIALS_TOKEN_A)

has now become invalid.

Store updated credentials with

CREDENTIALS_TOKEN_C

Figure 22. The OCPI registration process

OCPI 2.2-d2

Due to its symmetric nature of the credentials module, any platform can be Sender and or the Receiver for this module.

7.1.2. Updating to a newer version

At some point, both platforms will have implemented a newer OCPI version. To start using the newer version, one platform has to

send a PUT request to the credentials endpoint of the other platform.

OCPI Update process

Sender

Receiver

GET /ocpi/cpo/versions

Available versions

Pick latest mutual version (e.g. 2.0).

GET /ocpi/cpo/2.0/

Available endpoints for v2.0

Store version and endpoints

PUT /ocpi/cpo/2.0/credentials

GET /ocpi/emsp/versions

Available versions

GET /ocpi/emsp/2.0/

Available endpoints for v2.0

The Receiver knows it's version 2.0 because

of the endpoint the Sender has used. The URL

is retrieved from the available versions.

Store version and endpoints

Return updated credentials for Sender

Store updated credentials

Figure 23. The OCPI update process

7.1.3. Changing endpoints for the current version

This can be done by following the update procedure for the same version.

By sending a PUT request to the credentials endpoint of this version, the other platform will fetch and store the corresponding set of

endpoints.

7.1.4. Updating the credentials and resetting the credentials token

The credentials (or parts thereof, such as the credentials token) can be updated by sending the new credentials via a PUT request

to the credentials endpoint of the current version, similar to the update procedure described above.

Security advices: When one of the connecting platforms suspects that a credentials token is compromised, that platform SHALL

OCPI 2.2-d2

initiate a credentials token update as soon as possible. It is advisable to renew the credentials tokens at least once a month, in case

it was not detected that the credentials where compromised.

7.1.5. Errors during registration

When the server connects back to the client during the credentials registration, it might encounter problems. When this happens,

the server should add the status code 3001 in the response to the POST from the client.

7.1.6. Required endpoints not available

When two platforms connect, it might happen that one of the platforms expects a certain endpoint to be available at the other

platform.

For example: a Platform with a CPO role could only want to connect when the CDRs endpoint is available in an platform with an

eMSP role.

In case the Sender (starting the credentials exchange process) cannot find the endpoints it expects, it is expected NOT to send the

POST request with credentials to the Receiver. Log a message/notify the administrator to contact the administrator of the Receiver

platform.

In case the Receiver platform that cannot find the endpoints it expects, then it is expected to respond to the request with the status

code 3003.

7.2. Interfaces and endpoints

The Credentials module is different from all other OCPI modules. This module is symmetric, it has to be implemented by all OCPI

implementations, and all implementations need to be able call this module on any other platform, and have to be able the handle

receiving the request from another party.

Example: /ocpi/2.2/credentials and /ocpi/emsp/2.2/credentials

Method Description

GET Retrieves the credentials object to access the server’s platform.

POST Provides the server with a credentials object to access the client’s system (i.e. register).

PUT Provides the server with an updated credentials object to access the client’s system.

PATCH n/a

DELETE Informs the server that its credentials to the client’s system are now invalid (i.e. unregister).

7.2.1. GET Method

Retrieves the credentials object to access the server’s platform. The request body is empty, the response contains the credentials

object to access the server’s platform. This credentials object also contains extra information about the server such as its business

details.

7.2.2. POST Method

Provides the server with credentials to access the client’s system. This credentials object also contains extra information about the

client such as its business details.

A POST initiates the registration process for this endpoint’s version. The server must also fetch the client’s endpoints for this version.

OCPI 2.2-d2

If successful, the server must generate a new credentials token and respond with the client’s new credentials to access the server’s

system. The credentials object in the response also contains extra information about the server such as its business details.

This method MUST return a HTTP status code 405: method not allowed if the client has already been registered before.

7.2.3. PUT Method

Provides the server with updated credentials to access the client’s system. This credentials object also contains extra information

about the client such as its business details.

A PUT will switch to the version that contains this credentials endpoint if it’s different from the current version. The server must fetch

the client’s endpoints again, even if the version has not changed.

If successful, the server must generate a new credentials token for the client and respond with the client’s updated credentials to

access the server’s system. The credentials object in the response also contains extra information about the server such as its

business details.

This method MUST return a HTTP status code 405: method not allowed if the client has not been registered yet.

7.2.4. DELETE Method

Informs the server that its credentials to access the client’s system are now invalid and can no longer be used. Both parties must

end any automated communication. This is the unregistration process.

This method MUST return a HTTP status code 405: method not allowed if the client has not been registered before.

7.3. Object description

7.3.1. Credentials object

Property Type Card. Description

token string(64) 1 Case Sensitive, ASCII only. The credentials token for the other party to

authenticate in your system. Not encoded in Base64 or any other

encoding.

url URL 1 The URL to your API versions endpoint.

roles CredentialsRole + List of the roles this party provides.

Every role needs a unique combination of: role, party_id and country_code.

A party can have the same role more than once, for example when a CPO provides 'white-label' services for 'virtual' CPOs.

One or more roles and thus party_id and country_code sets are provided here to inform a server about the party_id and

country_code sets a client will use when pushing Client Owned Objects. This helps a server to determine the URLs a client will

use when pushing a Client Owned Object. The country_code is added the make certain the URL used when pushing a Client

Owned Object is unique as there might be multiple parties in the world with the same party_id. The combination of country_id

and party_id should always be unique though. A party operating in multiple countries can always use the home country of the

company for all connections.

For example: EVSE IDs can be pushed under the country and provider identification of a company, even if the EVSEs are actually

located in a different country. This way it is not necessary to establish one OCPI connection per country a company operates in.

The party_id and country_code given here have no direct link with the eMI3 EVSE IDs and Contract IDs that might be used in

the different OCPI modules. A party implementing OCPI MAY push EVSE IDs with an eMI3 spot operator different from the

OCPI party_id and/or the country_code.

OCPI 2.2-d2

7.3.2. Examples

Example of a minimal CPO credentials object:

{

"token": "ebf3b399-779f-4497-9b9d-ac6ad3cc44d2",

"url": "https://example.com/ocpi/versions/",

"roles": [{

"role": "CPO",

"party_id": "EXA",

"country_code": "NL",

"business_details": {

"name": "Example Operator"

}

}]

}

Example of a combined CPO/eMSP credentials object:

{

"token": "9e80a9c4-28be-11e9-b210-d663bd873d93",

"url": "https://ocpi.example.com/versions/",

"roles": [{

"role": "CPO",

"party_id": "EXA",

"country_code": "NL",

"business_details": {

"name": "Example Operator"

}

}, {

"role": "EMSP",

"party_id": "EXA",

"country_code": "NL",

"business_details": {

"name": "Example Provider"

}

}]

}

Example of a CPO credentials object with full business details:

{

"token": "9e80ae10-28be-11e9-b210-d663bd873d93",

"url": "https://example.com/ocpi/versions/",

"roles": [{

"role": "CPO",

"party_id": "EXA",

"country_code": "NL",

"business_details": {

"name": "Example Operator",

"logo": {

"url": "https://example.com/img/logo.jpg",

"thumbnail": "https://example.com/img/logo_thumb.jpg",

"category": "OPERATOR",

"type": "jpeg",

"width": 512,

"height": 512

"website": "http://example.com"

}

}]

}

Example of a CPO credentials object for a platform that provides services for 3 CPOs:

OCPI 2.2-d2

{

"token": "9e80aca8-28be-11e9-b210-d663bd873d93",

"url": "https://ocpi.example.com/versions/",

"roles": [{

"role": "CPO",

"party_id": "EXO",

"country_code": "NL",

"business_details": {

"name": "Excellent Operator"

}

}, {

"role": "CPO",

"party_id": "PFC",

"country_code": "NL",

"business_details": {

"name": "Plug Flex Charging"

}

}, {

"role": "CPO",

"party_id": "CGP",

"country_code": "NL",

"business_details": {

"name": "Charging Green Power"

}

}]

}

7.4. Data types

7.4.1. CredentialsRole class

Property Type Card. Description

role Role 1 Type of role.

business_details BusinessDetails 1 Details of this party.

party_id CiString(3) 1 CPO, eMSP (or other role) ID of this party (following the ISO-15118

standard).

country_code CiString(2) 1 ISO-3166 alpha-2 country code of the country this party is operating in.

OCPI 2.2-d2

8. Locations module

Module Identifier: locations

Data owner: CPO

Type: Functional Module

The Location objects live in the CPO back-end system. They describe the charging locations of an operator.

Module dependency: the Receiver endpoint is dependent on the Tariffs module

8.1. Flow and Lifecycle

The Locations module has the Location as base object. Each Location can have multiple EVSEs (1:n) and each EVSE can have

multiple Connectors (1:n). With the methods in the Receiver interface, Location data and status information can be shared with for

example an eMSP and NSP. Updates can be made to a whole Location, but also only to an EVSE or a single Connector.

When a CPO creates Location objects, it pushes them to connected eMSP by calling PUT on the Receivers Locations endpoint.

eMSPs who do not support Push mode need to call GET on the CPOs Locations endpoint to receive the new object. This should be

done regularly to stay up to date with the CPOs data, but not too often in order to keep the load low.

If the CPO wants to replace a Location related object, they again push it to the eMSP systems by calling PUT on their Locations

endpoint.

Any changes to a Location related object can also be pushed to connected eMSPs by calling the PATCH method on the eMSPs

Locations endpoint, but using PATCH mode, only actual changes should be pushed. Providers who do not support Push mode

need to call GET on the CPOs Locations endpoint to receive the updates.

When the CPO wants to delete an EVSE from the list of active EVSEs, they MUST update the EVSE’s status field to REMOVED

and call the PUT or PATCH on the eMSP system. A Location without any valid EVSE object can be considered expired and should

no longer be displayed. There is no way to entirely delete Locations, EVSEs and Connectors as there are other modules like

sessions that depend on them. If it was possible to remove these objects, those links would no longer work.

When the CPO is not sure about the state or existence of a Location, EVSE or Connector object in the eMSP’s system, the CPO

can perform a GET request to validate the object in the eMSP’s system.

Private charging Locations, that are not to be used for public charging, SHALL NOT be published via OCPI.

8.1.1. No public charging or roaming

When a Location is not available for either Public Charging or Roaming, it is RECOMMENDED to NOT send that Location via OCPI

to receiving parties.

8.1.2. Group of Charge Points

OCPP 2.0 supports a 3-tier model:

• Highest level is a Charge Point

• A Charge Point can have one or more EVSEs.

• Every EVSE can have one or more Connectors.

OCPI does not have this model:

• OCPI has Location at the highest level.

OCPI 2.2-d2

• Each location can have multiple EVSE

• Every EVSE can have one or more Connectors.

When mapping OCPP Charge Points to OCPI, there are 2 options:

• One Location for a group of Charge Points at the same location. (preferred)

• One Location per Charge Point at the same location.

OCPI prefers the first method. An EV driver does not care if a Location consists of one Charge Point with a very large amount of

EVSEs, or a large amount of Charge Points with only one EVSE. The EV driver wants to know how many EVSEs are available.

Grouping Charge Points in the same location into one OCPI Location will show better on a map that shows Charging Locations.

NOTE

The definition, an EVSE can only charge one EV at a time.

8.1.3. OCPP 1.x Charge Points with multiple connectors per EVSE

OCPP 1.x was not designed to support the 3-tier model. It had no notion of EVSEs. The Open Charge Alliance has written an

Application Note: "Multiple Connectors per EVSE in a OCPP 1.x implementation"

The workaround:

• Define one 'virtual' EVSE per Connector.

• When a connector of an hardware EVSE becomes unavailable, set all 'virtual' EVSEs for all the connectors of the hardware

EVSE to unavailable. etc.

8.2. Interfaces and endpoints

There are both, a Sender and a Receiver interface for Locations. It is advised to use the Push direction from Sender to Receiver

during normal operation in order to keep the latency of updates low. The Sender interface is meant to be used when the connection

between two parties is established for the first time, to retrieve the current list of Location objects with the current status, and when

the Receiver is not 100% sure the Location cache is entirely up-to-date (i.e. to perform a full sync). The Receiver can also use the

Sender GET Object interface to retrieve a specific Location, EVSE or Connector. This feature might be used by an Receiver that

wants information about a specific Location, but has not implemented the Receiver Locations interface (i.e. cannot receive Push).

8.2.1. Sender Interface

Typically implemented by market roles like: CPO.

Method Description

GET Fetch a list of Locations, last updated between the {date_from} and {date_to} (paginated), or get a specific

Location, EVSE or Connector.

POST n/a

PUT n/a

PATCH n/a

DELETE n/a

8.2.1.1. GET Method

Depending on the URL Segments provided, the GET request can either be used to retrieve information about a list of available

Locations (with EVSEs and Connectors) at a CPO (GET List) or it can be used to retrieve information about one specific Location,

OCPI 2.2-d2

EVSE or Connector (GET Object).

GET List: Request Parameters

Endpoint structure definition:

{locations_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={l

imit}]

Examples:

https://www.server.com/ocpi/cpo/2.2/locations/?date_from=2019-01-28T12:00:00&date_to=2019-01-

29T12:00:00

https://ocpi.server.com/2.2/locations/?offset=50

https://www.server.com/ocpi/2.2/locations/?date_from=2019-01-29T12:00:00&limit=100

https://www.server.com/ocpi/cpo/2.2/locations/?offset=50&limit=100

If the optional parameters {date_from} and/or {date_to} are provided, only Locations with (last_updated) between the

given {date_from} (including) and {date_to} (excluding) will be returned. In order for this to work properly, the following logic

MUST be implemented accordingly: If an EVSE is updated, also the 'parent' Location’s last_updated field needs to be updated.

Similarly, if a Connector is updated, the EVSE’s last_updated and the Location’s last_updated fields need to be updated.

This request is paginated, it supports the pagination related URL parameters.

Parameter Datatype Requi

red

Description

date_from DateTime no Only return Locations that have last_updated after or equal to this Date/Time

(inclusive).

date_to DateTime no Only return Locations that have last_updated up to this Date/Time, but not

including (exclusive).

offset int no The offset of the first object returned. Default is 0.

limit int no Maximum number of objects to GET.

GET List: Response Data

This endpoint returns a list of Location objects. The header will contain the pagination related headers.

Each object must contain all required fields. Fields that are not specified may be considered as null values. Any old information that

is not specified in the response is considered no longer valid. For requests that use pagination, the response data provided by all

the pages together is the new truth. Any old information not contained in any of the pages needs to be considered no longer valid.

Type Card. Description

Location * List of all Locations with valid EVSEs.

GET Object: Request Parameters

Endpoint structure definition for retrieving a Location, EVSE or Connector:

{locations_endpoint_url}/{location_id}[/{evse_uid}][/{connector_id}]

Examples:

OCPI 2.2-d2

https://www.server.com/ocpi/cpo/2.2/locations/LOC1

https://www.server.com/ocpi/cpo/2.2/locations/LOC1/3256

https://www.server.com/ocpi/cpo/2.2/locations/LOC1/3256/1

The following parameters can be provided as URL segments in the same order.

Parameter Datatype Requi

red

Description

location_id CiString(36) yes Location.id of the Location object to retrieve.

evse_uid CiString(36) no Evse.uid, required when requesting an EVSE or Connector object.

connector_id CiString(36) no Connector.id, required when requesting a Connector object.

GET Object: Response Data

The response contains the requested object.

Type Card. Description

Choice: one of three

> Location 1 If a Location object was requested: the Location object.

> EVSE 1 If an EVSE object was requested: the EVSE object.

> Connector 1 If a Connector object was requested: the Connector object.

8.2.2. Receiver Interface

Typically implemented by market roles like: eMSP and NSP.

Locations are Client Owned Objects, so the end-points need to contain the required extra fields: {party_id} and {country_code}.

Endpoint structure definition:

{locations_endpoint_url}/{country_code}/{party_id}/{location_id}[/{evse_uid}][/{connector_id}]

Examples:

https://www.server.com/ocpi/emsp/2.2/locations/BE/BEC/LOC1

https://server.com/ocpi/2.2/locations/BE/BEC/LOC1/3256

https://ocpi.server.com/2.2/locations/BE/BEC/LOC1/3256/1

Method Description

GET Retrieve a Location as it is stored in the eMSP system.

POST n/a (use PUT)

PUT Push new/updated Location, EVSE and/or Connector to the eMSP.

PATCH Notify the eMSP of partial updates to a Location, EVSE or Connector (such as the status).

DELETE n/a (use PATCH to update the status to REMOVED as described in Flow and Lifecycle)

OCPI 2.2-d2

8.2.2.1. GET Method

If the CPO wants to check the status of a Location, EVSE or Connector object in the eMSP system, it might GET the object from

the eMSP system for validation purposes. The CPO is the owner of the objects, so it would be illogical if the eMSP system had a

different status or was missing an object. If a discrepancy is found, the CPO might push an update to the eMSP via a PUT or

PATCH call.

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the CPO requesting data from the eMSP system.

party_id CiString(3) yes Party ID (Provider ID) of the CPO requesting data from the eMSP system.

location_id CiString(36) yes Location.id of the Location object to retrieve.

evse_uid CiString(36) no Evse.uid, required when requesting an EVSE or Connector object.

connector_id CiString(36) no Connector.id, required when requesting a Connector object.

Response Data

The response contains the requested object.

Type Card. Description

Choice: one of three

> Location 1 If a Location object was requested: the Location object.

> EVSE 1 If an EVSE object was requested: the EVSE object.

> Connector 1 If a Connector object was requested: the Connector object.

8.2.2.2. PUT Method

The CPO pushes available Location, EVSE or Connector objects to the eMSP. PUT can be used to send new Location objects to

the eMSP but also to replace existing Locations.

When the PUT only contains a Connector Object, the Receiver SHALL also set the new last_updated value on the parent EVSE

and Location Objects.

When the PUT only contains a EVSE Object, the Receiver SHALL also set the new last_updated value on the parent Location

Object.

Request Parameters

This is an information Push message, the objects pushed will not be owned by the eMSP. To make distinctions between objects

being pushed to an eMSP from different CPOs, the {party_id} and {country_code} have to be included in the URL (as URL

segments, as described in the Receiver Interface).

OCPI 2.2-d2

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the CPO requesting this PUT to the eMSP system. This SHALL

be the same value as the country_code in the Location object being pushed.

party_id CiString(3) yes Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system. This

SHALL be the same value as the party_id in the Location object being

pushed.

location_id CiString(36) yes Location.id of the new Location object, or the Location of which an EVSE or

Connector object is pushed.

evse_uid CiString(36) no Evse.uid, required when an EVSE or Connector object is pushed.

connector_id CiString(36) no Connector.id, required when a Connector object is pushed.

Request Body

The request body contains the new/updated object.

When the PUT contains a Connector Object, the Receiver SHALL also set the new last_updated value on the parent EVSE and

Location Objects.

When the PUT contains a EVSE Object, the Receiver SHALL also set the new last_updated value on the parent Location

Object.

Type Card. Description

Choice: one of three

> Location 1 New Location object, or Location object to replace.

> EVSE 1 New EVSE object, or EVSE object to replace.

> Connector 1 New Connector object, or Connector object to replace.

Example: add an EVSE

To add an EVSE, simply put the full object in an update message, including all its required fields. Since the id will be new to the

eMSP’s system, the receiving party will know that it is a new object. When not all required fields are specified, the object may be

discarded.

PUT To URL: https://www.server.com/ocpi/emsp/2.2/locations/NL/TNM/1012/3256

{

"uid": "3256",

"evse_id": "BE*BEC*E041503003",

"status": "AVAILABLE",

"capabilities": ["RESERVABLE"],

"connectors": [

{

"id": "1",

"standard": "IEC_62196_T2",

"format": "SOCKET",

"tariff_ids": ["14"]

}

"floor": -1,

"physical_reference": 3,

"last_updated": "2019-06-24T12:39:09Z"

}

OCPI 2.2-d2

8.2.2.3. PATCH Method

Same as the PUT method, but only the fields/objects that have to be updated have to be present. Other fields/objects that are not

specified as part of the request are considered unchanged. Therefore, this method is not suitable to remove information shared

earlier.

Any request to the PATCH method SHALL contain the last_updated field.

When the PATCH is on a Connector Object, the Receiver SHALL also set the new last_updated value on the parent EVSE and

Location Objects.

When the PATCH is on a EVSE Object, the Receiver SHALL also set the new last_updated value on the parent Location Object.

Example: a simple status update

This is the most common type of update message. It is used to notify eMSPs that the status of an EVSE changed. In this case it is

the EVSE with uid 3255 of the Location with id 1012.

PATCH To URL: https://www.server.com/ocpi/emsp/2.2/locations/NL/TNM/1012/3255

{

"status": "CHARGING",

"last_updated": "2019-06-24T12:39:09Z"

}

Example: change the location name

In this example the name of the Location with id 1012 is being updated.

PATCH To URL: https://www.server.com/ocpi/emsp/2.2/locations/NL/TNM/1012

{

"name": "Interparking Gent Zuid",

"last_updated": "2019-06-24T12:39:09Z"

}

Example: set tariff update

In this example Connector 2 of EVSE 1 of Location 1012 receives a new pricing scheme.

PATCH To URL: https://www.server.com/ocpi/emsp/2.2/locations/NL/TNM/1012/3255/2

{

"tariff_ids": ["15"],

"last_updated": "2019-06-24T12:39:09Z"

}

Example: delete an EVSE

An EVSE can be deleted by updating its status property.

PATCH To URL: https://www.server.com/ocpi/emsp/2.2/locations/NL/TNM/1012/3256

{

"status": "REMOVED",

"last_updated": "2019-06-24T12:39:09Z"

}

OCPI 2.2-d2

NOTE

To inform eMSPs that an EVSE is scheduled for removal, the status_schedule field can be used._

8.3. Object description

Location, EVSE and Connector have the following relation.

Locations class diagram

Location

EVSE

Connector

0..n

1..n

Figure 24. Location class diagram

8.3.1. Location Object

The Location object describes the location and its properties where a group of EVSEs that belong together are installed. Typically,

the Location object is the exact location of the group of EVSEs, but it can also be the entrance of a parking garage which contains

these EVSEs. The exact way to reach each EVSE can be further specified by its own properties.

Locations may be shown in apps or on websites etc. when the flag: publish is set to true. Locations that have this flag set to

false SHALL not be shown in an app or on a website etc. unless it is to the owner of a Token in the publish_allowed_to list.

Even parties like NSP or eMSP that do not 'own' this Token MAY show this location on an app or website, but only to the owner of

that Token. If the user of their app/website has provided information about his/her Token, And that information matches all the fields

of one of the PublishToken tokens in the list, then they are allowed to show this location to their user. It is not allowed in OCPI to

use a Token that is not 'owned' by the eMSP itself to start a charging session.

Property Type Card. Description

country_code CiString(2) 1 ISO-3166 alpha-2 country code of the CPO that 'owns' this

Location.

party_id CiString(3) 1 CPO ID of the CPO that 'owns' this Location (following the ISO-

15118 standard).

id CiString(36) 1 Uniquely identifies the location within the CPOs platform (and

suboperator platforms). This field can never be changed,

modified or renamed.

publish boolean 1 Defines if a Location may be published on an website or app

etc.

When this is set to false, only tokens identified in the field:

publish_allowed_to are allowed to be shown this Location.

When the same location has EVSEs that may be published and

may not be published, two 'Locations' should be created.

OCPI 2.2-d2

Property Type Card. Description

publish_allowed_to PublishTokenType * This field may only be used when the publish field is set to

false

Only owners of Tokens that match all the set fields of one

PublishToken in the list are allowed to be shown this location.

name string(255) ? Display name of the location.

address string(45) 1 Street/block name and house number if available.

city string(45) 1 City or town.

postal_code string(10) ? Postal code of the location, may only be omitted when the

location has no postal code: in some countries charging

locations at highways don’t have postal codes.

state string(20) ? State or province of the location, only to be used when relevant.

country string(3) 1 ISO 3166-1 alpha-3 code for the country of this location.

coordinates GeoLocation 1 Coordinates of the location.

related_locations AdditionalGeoLocation * Geographical location of related points relevant to the user.

parking_type ParkingType ? The general type of parking at the charge point location.

evses EVSE * List of EVSEs that belong to this Location.

directions DisplayText * Human-readable directions on how to reach the location.

operator BusinessDetails ? Information of the operator. When not specified, the information

retrieved from the Credentials module should be used instead.

suboperator BusinessDetails ? Information of the suboperator if available.

owner BusinessDetails ? Information of the owner if available.

facilities Facility * Optional list of facilities this charging location directly belongs

to.

time_zone string(255) 1 One of IANA tzdata’s TZ-values representing the time zone of

the location. Examples: "Europe/Oslo", "Europe/Zurich".

(http://www.iana.org/time-zones)

opening_times Hours ? The times when the EVSEs at the location can be accessed for

charging.

charging_when_closed boolean ? Indicates if the EVSEs are still charging outside the opening

hours of the location. E.g. when the parking garage closes its

barriers over night, is it allowed to charge till the next morning?

Default: true

images Image * Links to images related to the location such as photos or logos.

energy_mix EnergyMix ? Details on the energy supplied at this location.

last_updated DateTime 1 Timestamp when this Location or one of its EVSEs or

Connectors were last updated (or created).

Private Charge Points, home or business that do not need to be published on apps, and do not require remote control via OCPI,

SHOULD not be PUT via the OCPI Locations module. Reimbursement via eMSP is still possible by sending CDRs to eMSP, the

Locations module is not needed for this..

OCPI 2.2-d2

8.3.1.1. Example public charging location

This is an example of a public charging location. Can be used by any EV Driver as long as his eMSP has a roaming agreement with

the CPO. Or the Charge Point has an ad-hoc payment possibility

• publish = true

• parking_type = ON_STREET but could also be another value.

• EVSE.parking_restrictions not used.

OCPI 2.2-d2

{

"country_code": "BE",

"party_id": "BEC",

"id": "LOC1",

"publish": true,

"name": "Gent Zuid",

"address": "F.Rooseveltlaan 3A",

"city": "Gent",

"postal_code": "9000",

"country": "BEL",

"coordinates": {

"latitude": "51.047599",

"longitude": "3.729944"

"parking_type": "ON_STREET",

"evses": [{

"uid": "3256",

"evse_id": "BE*BEC*E041503001",

"status": "AVAILABLE",

"status_schedule": [],

"capabilities": [

"RESERVABLE"

"connectors": [{

"id": "1",

"standard": "IEC_62196_T2",

"format": "CABLE",

"power_type": "AC_3_PHASE",

"voltage": 220,

"amperage": 16,

"tariff_ids": ["11"],

"last_updated": "2015-03-16T10:10:02Z"

}, {

"id": "2",

"standard": "IEC_62196_T2",

"format": "SOCKET",

"power_type": "AC_3_PHASE",

"voltage": 220,

"amperage": 16,

"tariff_ids": ["13"],

"last_updated": "2015-03-18T08:12:01Z"

}],

"physical_reference": "1",

"floor_level": "-1",

"last_updated": "2015-06-28T08:12:01Z"

}, {

"uid": "3257",

"evse_id": "BE*BEC*E041503002",

"status": "RESERVED",

"capabilities": [

"RESERVABLE"

"connectors": [{

"id": "1",

"standard": "IEC_62196_T2",

"format": "SOCKET",

"power_type": "AC_3_PHASE",

"voltage": 220,

"amperage": 16,

"tariff_ids": ["12"],

"last_updated": "2015-06-29T20:39:09Z"

}],

"physical_reference": "2",

"floor_level": "-2",

"last_updated": "2015-06-29T20:39:09Z"

}],

"operator": {

"name": "BeCharged"

"time_zone": "Europe/Brussels",

"last_updated": "2015-06-29T20:39:09Z"

}

OCPI 2.2-d2

8.3.1.2. Example destination charging location

This is an example of a destination charging location. This is a Location where only guests, employees or customers can charge.

For an EV driver, it can be useful to know if he/she can charge at his destination.

For example at a restaurant, only customers of the restaurant can charge their EV. Or at an office building where employees and

guest of the office can charge their EV.

Locations you can think of where this is useful: restaurants, bars, clubs, theme parks, stores, supermarkets, company building,

office buildings, etc.

• publish = true

• parking_type = PARKING_LOT (but could also be PARKING_GARAGE, ON_DRIVEWAY or UNDERGROUND_GARAGE)

• EVSE.parking_restrictions = CUSTOMERS

{

"country_code": "NL",

"party_id": "ALF",

"id": "3e7b39c2-10d0-4138-a8b3-8509a25f9920",

"publish": true,

"name": "ihomer",

"address": "Tamboerijn 7",

"city": "Etten-Leur",

"postal_code": "4876 BS",

"country": "NLD",

"coordinates": {

"latitude": "51.562787",

"longitude": "4.638975"

"parking_type": "PARKING_LOT",

"evses": [{

"uid": "fd855359-bc81-47bb-bb89-849ae3dac89e",

"evse_id": "NL*ALF*E000000001",

"status": "AVAILABLE",

"connectors": [{

"id": "1",

"standard": "IEC_62196_T2",

"format": "SOCKET",

"power_type": "AC_3_PHASE",

"voltage": 220,

"amperage": 16,

"last_updated": "2019-07-01T12:12:11Z"

}],

"parking_restrictions": "CUSTOMERS",

"last_updated": "2019-07-01T12:12:11Z"

}],

"time_zone": "Europe/Amsterdam",

"last_updated": "2019-07-01T12:12:11Z"

}

8.3.1.3. Example destination charging location not published, but paid guest usage

possible

This is an example of a destination charging location. But the owner of the location has requested not to publish the location in

Apps or on websites.

Charging is still possible: EV drivers of an eMSP with a roaming agreement can still charge their EV. The eMSP helpdesk can use

the information from the Location module to help the driver, maybe even start a session for a driver. Starting a session from an App

is not possible, because the driver will not be able to select the Charge Point on a map.

In case the EV driver is not billed for charging, there is, in such a case, no reason to publish the location via OCPI.

• publish = false

OCPI 2.2-d2

• publish_allowed_to not used

• parking_type = not used`

• EVSE.parking_restrictions = CUSTOMERS May still be useful so a support desk can also tell this to a customer.

{

"country_code": "NL",

"party_id": "ALF",

"id": "3e7b39c2-10d0-4138-a8b3-8509a25f9920",

"publish": false,

"name": "ihomer",

"address": "Tamboerijn 7",

"city": "Etten-Leur",

"postal_code": "4876 BS",

"country": "NLD",

"coordinates": {

"latitude": "51.562787",

"longitude": "4.638975"

"evses": [{

"uid": "fd855359-bc81-47bb-bb89-849ae3dac89e",

"evse_id": "NL*ALF*E000000001",

"status": "AVAILABLE",

"connectors": [{

"id": "1",

"standard": "IEC_62196_T2",

"format": "SOCKET",

"power_type": "AC_3_PHASE",

"voltage": 220,

"amperage": 16,

"last_updated": "2019-07-01T12:12:11Z"

}],

"parking_restrictions": "CUSTOMERS",

"last_updated": "2019-07-01T12:12:11Z"

}],

"time_zone": "Europe/Amsterdam",

"last_updated": "2019-07-01T12:12:11Z"

}

8.3.1.4. Example charging location with limited visibility

This is an example of a charging location that only a limited group can see (and use) via an App or website.

Typical examples where this is useful:

• Charge Points in the parking garage of an apartment building. Only owners can see/control the Charge Points.

• Charge Points at an office, for employees only. Only employees can see/control the Charge Points.

• Charge Points at vehicle depot. Any employee can see/control an charge point, even transaction they did not start. Use

group_id for this.

The locations SHALL NOT be published to the general public. Only selected Tokens can see (and control) the Charge Points via

eMSP app.

• publish = false

• publish_allowed_to contains list with information of Tokens that are allowed to be shown the Location.

• parking_type = UNDERGROUND_GARAGE (but could also be PARKING_GARAGE, ON_DRIVEWAY or PARKING_LOT)

OCPI 2.2-d2

{

"country_code": "NL",

"party_id": "ALL",

"id": "f76c2e0c-a6ef-4f67-bf23-6a187e5ca0e0",

"publish": false,

"publish_allowed_to": [{

"visual_number": "12345-67",

"issuer": "NewMotion"

}, {

"visual_number": "0055375624",

"issuer": "ANWB"

}, {

"uid": "12345678905880",

"type": "RFID"

}],

"name": "Water State",

"address": "Taco van der Veenplein 12",

"city": "Leeuwarden",

"postal_code": "8923 EM",

"country": "NLD",

"coordinates": {

"latitude": "53.213763",

"longitude": "5.804638"

"parking_type": "UNDERGROUND_GARAGE",

"evses": [{

"uid": "8c1b3487-61ac-40a7-a367-21eee99dbd90",

"evse_id": "NL*ALL*EGO0000013",

"status": "AVAILABLE",

"connectors": [{

"id": "1",

"standard": "IEC_62196_T2",

"format": "SOCKET",

"power_type": "AC_3_PHASE",

"voltage": 230,

"amperage": 16,

"last_updated": "2019-09-27T00:19:45Z"

}],

"last_updated": "2019-09-27T00:19:45Z"

}],

"time_zone": "Europe/Amsterdam",

"last_updated": "2019-09-27T00:19:45Z"

}

8.3.1.5. Example private charge point with eMSP app control

This is an example of a private/home charge point that needs to be controlled via an eMSP App.

The locations SHALL NOT be published to the general public. Only the owner, identified by his/her Token can see (and control) the

Charge Points via an eMSP app.

• publish = false

• publish_allowed_to contains the information of the Tokens of the owner.

• parking_type = not used, not relevant, owner knows where his Charge Point is.

OCPI 2.2-d2

{

"country_code": "DE",

"party_id": "ALL",

"id": "a5295927-09b9-4a71-b4b9-a5fffdfa0b77",

"publish": false,

"publish_allowed_to": [{

"visual_number": "0123456-99",

"issuer": "MoveMove"

}],

"address": "Krautwigstraße 283A",

"city": "Köln",

"postal_code": "50931",

"country": "DEU",

"coordinates": {

"latitude": "50.931826",

"longitude": "6.964043"

"parking_type": "ON_DRIVEWAY",

"evses": [{

"uid": "4534ad5f-45be-428b-bfd0-fa489dda932d",

"evse_id": "DE*ALL*EGO0000001",

"status": "AVAILABLE",

"connectors": [{

"id": "1",

"standard": "IEC_62196_T2",

"format": "SOCKET",

"power_type": "AC_1_PHASE",

"voltage": 230,

"amperage": 8,

"last_updated": "2019-04-05T17:17:56Z"

}],

"last_updated": "2019-04-05T17:17:56Z"

}],

"time_zone": "Europe/Berlin",

"last_updated": "2019-04-05T17:17:56Z"

}

8.3.1.6. Example charge point in a parking garage with opening hours

This is an example of a charge point, located in a parking garage with limited opening hours: 7:00 - 18:00.

If the EV is left in the parking garage overnight, the car will still be charged.

• publish = true

• parking_type = PARKING_GARAGE but could also be another value.

• EVSE.parking_restrictions not used.

• opening_times is used.

• charging_when_closed = true

OCPI 2.2-d2

{

"country_code": "SE",

"party_id": "EVC",

"id": "cbb0df21-d17d-40ba-a4aa-dc588c8f98cb",

"publish": true,

"name": "P-Huset Leonard",

"address": "Claesgatan 6",

"city": "Malmö",

"postal_code": "214 26",

"country": "SWE",

"coordinates": {

"latitude": "55.590325",

"longitude": "13.008307"

"parking_type": "PARKING_GARAGE",

"evses": [{

"uid": "eccb8dd9-4189-433e-b100-cc0945dd17dc",

"evse_id": "SE*EVC*E000000123",

"status": "AVAILABLE",

"connectors": [{

"id": "1",

"standard": "IEC_62196_T2",

"format": "SOCKET",

"power_type": "AC_3_PHASE",

"voltage": 230,

"amperage": 32,

"last_updated": "2017-03-07T02:21:22Z"

}],

"last_updated": "2017-03-07T02:21:22Z"

}],

"time_zone": "Europe/Stockholm",

"opening_times": {

"twentyfourseven": false,

"regular_hours": [{

"weekday": 1,

"period_begin": "07:00",

"period_end": "18:00"

}, {

"weekday": 2,

"period_begin": "07:00",

"period_end": "18:00"

},{

"weekday": 3,

"period_begin": "07:00",

"period_end": "18:00"

},{

"weekday": 4,

"period_begin": "07:00",

"period_end": "18:00"

},{

"weekday": 5,

"period_begin": "07:00",

"period_end": "18:00"

},{

"weekday": 6,

"period_begin": "07:00",

"period_end": "18:00"

},{

"weekday": 7,

"period_begin": "07:00",

"period_end": "18:00"

}]

"charging_when_closed": true,

"last_updated": "2017-03-07T02:21:22Z"

}

8.3.2. EVSE Object

The EVSE object describes the part that controls the power supply to a single EV in a single session. It always belongs to a

Location object. The object only contains directions to get from the location itself to the EVSE (i.e. floor, physical_reference or

directions).

OCPI 2.2-d2

When the directional properties of an EVSE are insufficient to reach the EVSE from the Location point, then it typically indicates

that the EVSE should be put in a different Location object (sometimes with the same address but with different

coordinates/directions).

An EVSE object has a list of Connectors which can not be used simultaneously: only one connector per EVSE can be used at the

time.

Property Type Card. Description

uid CiString(36) 1 Uniquely identifies the EVSE within the CPOs platform (and

suboperator platforms). For example a database ID or the actual "EVSE

ID". This field can never be changed, modified or renamed. This is the

'technical' identification of the EVSE, not to be used as 'human

readable' identification, use the field evse_id for that.

This field is named uid instead of id, because id could be confused

with evse_id which is an eMI3 defined field.

evse_id CiString(48) ? Compliant with the following specification for EVSE ID from "eMI3

standard version V1.0" (http://emi3group.com/documents-links/) "Part 2:

business objects." Optional because: if an evse_id is to be re-used in

the real world, the evse_id can be removed from an EVSE object if the

status is set to REMOVED.

status Status 1 Indicates the current status of the EVSE.

status_schedule StatusSchedule * Indicates a planned status update of the EVSE.

capabilities Capability * List of functionalities that the EVSE is capable of.

connectors Connector + List of available connectors on the EVSE.

floor_level string(4) ? Level on which the Charge Point is located (in garage buildings) in the

locally displayed numbering scheme.

coordinates GeoLocation ? Coordinates of the EVSE.

physical_reference string(16) ? A number/string printed on the outside of the EVSE for visual

identification.

directions DisplayText * Multi-language human-readable directions when more detailed

information on how to reach the EVSE from the Location is required.

parking_restrictions ParkingRestriction * The restrictions that apply to the parking spot.

images Image * Links to images related to the EVSE such as photos or logos.

last_updated DateTime 1 Timestamp when this EVSE or one of its Connectors was last updated

(or created).

NOTE

OCPP 1.x does not have good support for Charge Points that have multiple connectors per EVSE. To make

StartSession over OCPI work, the CPO SHOULD present the different connectors of an EVSE as separate

EVSE, as is also written by the OCA in the application note: "Multiple Connectors per EVSE in a OCPP 1.x

implementation".

8.3.3. Connector Object

A Connector is the socket or cable and plug available for the EV to use. A single EVSE may provide multiple Connectors but only

one of them can be in use at the same time. A Connector always belongs to an EVSE object.

OCPI 2.2-d2

Property Type Card. Description

id CiString(36) 1 Identifier of the Connector within the EVSE. Two Connectors may have

the same id as long as they do not belong to the same EVSE object.

standard ConnectorType 1 The standard of the installed connector.

format ConnectorFormat 1 The format (socket/cable) of the installed connector.

power_type PowerType 1

max_voltage int 1 Maximum voltage of the connector (line to neutral for AC_3_PHASE), in

volt [V]. For example: DC Chargers might vary the voltage during

charging when battery almost full.

max_amperage int 1 Maximum amperage of the connector, in ampere [A].

max_electric_power int ? Maximum electric power that can be delivered by this connector, in

Watts (W). When the maximum electric power is lower than the

calculated value from voltage and amperage, this value should be

set.

For example: A DC Charge Point which can delivers up to 920V and up

to 400A can be limited to a maximum of 150kW (max_electric_power =

150000). Depending on the car, it may supply max voltage or current,

but not both at the same time.

For AC Charge Points, the amount of phases used can also have

influence on the maximum power.

tariff_ids CiString(36) * Identifiers of the currently valid charging tariffs. Multiple tariffs are

possible, but only one of each Tariff.type can be active at the same time.

Tariffs with the same type are only allowed if they are not active at the

same time: start_date_time and end_date_time period not overlapping.

When preference-based smart charging is supported, one tariff for

every possible ProfileType should be provided. These tell the user about

the options they have at this Connector, and what the tariff is for every

option.

For a "free of charge" tariff, this field should be set and point to a

defined "free of charge" tariff.

terms_and_conditions URL ? URL to the operator’s terms and conditions.

last_updated DateTime 1 Timestamp when this Connector was last updated (or created).

8.4. Data types

8.4.1. AdditionalGeoLocation class

This class defines an additional geo location that is relevant for the Charge Point. The geodetic system to be used is WGS 84.

Property Type Card. Description

latitude string(10) 1 Latitude of the point in decimal degree. Example: 50.770774. Decimal

separator: "." Regex: -?[0-9]{1,2}\.[0-9]{5,7}

longitude string(11) 1 Longitude of the point in decimal degree. Example: -126.104965. Decimal

separator: "." Regex: -?[0-9]{1,3}\.[0-9]{5,7}

OCPI 2.2-d2

Property Type Card. Description

name DisplayText ? Name of the point in local language or as written at the location. For example

the street name of a parking lot entrance or it’s number.

8.4.2. BusinessDetails class

Property Type Card. Description

name string(100) 1 Name of the operator.

website URL ? Link to the operator’s website.

logo Image ? Image link to the operator’s logo.

8.4.3. Capability enum

The capabilities of an EVSE.

Value Description

CHARGING_PROFILE_CAPABLE The EVSE supports charging profiles.

CHARGING_PREFERENCES_CAPABLE The EVSE supports charging preferences.

CHIP_CARD_SUPPORT EVSE has a payment terminal that supports chip cards.

CONTACTLESS_CARD_SUPPORT EVSE has a payment terminal that supports contactless cards.

CREDIT_CARD_PAYABLE EVSE has a payment terminal that makes it possible to pay for charging using

a credit card.

DEBIT_CARD_PAYABLE EVSE has a payment terminal that makes it possible to pay for charging using

a debit card.

PED_TERMINAL EVSE has a payment terminal with a pin-code entry device.

REMOTE_START_STOP_CAPABLE The EVSE can remotely be started/stopped.

RESERVABLE The EVSE can be reserved.

RFID_READER Charging at this EVSE can be authorized with an RFID token.

TOKEN_GROUP_CAPABLE This EVSE supports token groups, two or more tokens work as one, so that a

session can be started with one token and stopped with another (handy when

a card and key-fob are given to the EV-driver).

UNLOCK_CAPABLE Connectors have mechanical lock that can be requested by the eMSP to be

unlocked.

When a Charge Point supports ad-hoc payments with a payment terminal, please use a combination of the following values to

explain the possibilities of the terminal: CHIP_CARD_SUPPORT, CONTACTLESS_CARD_SUPPORT, CREDIT_CARD_PAYABLE,

DEBIT_CARD_PAYABLE, PED_TERMINAL.

8.4.4. ConnectorFormat enum

The format of the connector, whether it is a socket or a plug.

OCPI 2.2-d2

Value Description

SOCKET The connector is a socket; the EV user needs to bring a fitting plug.

CABLE The connector is an attached cable; the EV users car needs to have a fitting inlet.

8.4.5. ConnectorType enum

The socket or plug standard of the charging point.

Value Description

CHADEMO The connector type is CHAdeMO, DC

DOMESTIC_A Standard/Domestic household, type "A", NEMA 1-15, 2 pins

DOMESTIC_B Standard/Domestic household, type "B", NEMA 5-15, 3 pins

DOMESTIC_C Standard/Domestic household, type "C", CEE 7/17, 2 pins

DOMESTIC_D Standard/Domestic household, type "D", 3 pin

DOMESTIC_E Standard/Domestic household, type "E", CEE 7/5 3 pins

DOMESTIC_F Standard/Domestic household, type "F", CEE 7/4, Schuko, 3 pins

DOMESTIC_G Standard/Domestic household, type "G", BS 1363, Commonwealth, 3 pins

DOMESTIC_H Standard/Domestic household, type "H", SI-32, 3 pins

DOMESTIC_I Standard/Domestic household, type "I", AS 3112, 3 pins

DOMESTIC_J Standard/Domestic household, type "J", SEV 1011, 3 pins

DOMESTIC_K Standard/Domestic household, type "K", DS 60884-2-D1, 3 pins

DOMESTIC_L Standard/Domestic household, type "L", CEI 23-16-VII, 3 pins

IEC_60309_2_single_16 IEC 60309-2 Industrial Connector single phase 16 amperes (usually blue)

IEC_60309_2_three_16 IEC 60309-2 Industrial Connector three phase 16 amperes (usually red)

IEC_60309_2_three_32 IEC 60309-2 Industrial Connector three phase 32 amperes (usually red)

IEC_60309_2_three_64 IEC 60309-2 Industrial Connector three phase 64 amperes (usually red)

IEC_62196_T1 IEC 62196 Type 1 "SAE J1772"

IEC_62196_T1_COMBO Combo Type 1 based, DC

IEC_62196_T2 IEC 62196 Type 2 "Mennekes"

IEC_62196_T2_COMBO Combo Type 2 based, DC

IEC_62196_T3A IEC 62196 Type 3A

IEC_62196_T3C IEC 62196 Type 3C "Scame"

PANTOGRAPH_BOTTOM_

On-board Bottom-up-Pantograph typically for bus charging

OCPI 2.2-d2

Value Description

PANTOGRAPH_TOP_DOW

Off-board Top-down-Pantograph typically for bus charging

TESLA_R Tesla Connector "Roadster"-type (round, 4 pin)

TESLA_S Tesla Connector "Model-S"-type (oval, 5 pin)

8.4.6. EnergyMix class

This type is used to specify the energy mix and environmental impact of the supplied energy at a location or in a tariff.

Property Type Card. Description

is_green_energy boolean 1 True if 100% from regenerative sources. (CO2 and nuclear waste is

zero)

energy_sources EnergySource * Key-value pairs (enum + percentage) of energy sources of this

location’s tariff.

environ_impact EnvironmentalImpact * Key-value pairs (enum + percentage) of nuclear waste and CO2

exhaust of this location’s tariff.

supplier_name string(64) ? Name of the energy supplier, delivering the energy for this location or

tariff.*

energy_product_name string(64) ? Name of the energy suppliers product/tariff plan used at this location.*

* These fields can be used to look-up energy qualification or to show it directly to the customer (for well-known brands like

Greenpeace Energy, etc.)

8.4.6.1. Examples

Simple:

"energy_mix": {

"is_green_energy": true

}

Tariff energy provider name:

"energy_mix": {

"is_green_energy": true,

"supplier_name": "Greenpeace Energy eG",

"energy_product_name": "eco-power"

}

Complete:

OCPI 2.2-d2

"energy_mix": {

"is_green_energy": false,

"energy_sources": [

{ "source": "GENERAL_GREEN", "percentage": 35.9 },

{ "source": "GAS", "percentage": 6.3 },

{ "source": "COAL", "percentage": 33.2 },

{ "source": "GENERAL_FOSSIL", "percentage": 2.9 },

{ "source": "NUCLEAR", "percentage": 21.7 }

"environ_impact": [

{ "source": "NUCLEAR_WASTE", "amount": 0.0006 },

{ "source": "CARBON_DIOXIDE", "amount": 372 }

"supplier_name": "E.ON Energy Deutschland",

"energy_product_name": "E.ON DirektStrom eco"

}

8.4.7. EnergySource class

Key-value pairs (enum + percentage) of energy sources. All given values of all categories should add up to 100 percent.

Property Type Card. Description

source EnergySourceCategory 1 The type of energy source.

percentage number 1 Percentage of this source (0-100) in the mix.

8.4.8. EnergySourceCategory enum

Categories of energy sources.

Value Description

NUCLEAR Nuclear power sources.

GENERAL_FOSSIL All kinds of fossil power sources.

COAL Fossil power from coal.

GAS Fossil power from gas.

GENERAL_GREEN All kinds of regenerative power sources.

SOLAR Regenerative power from PV.

WIND Regenerative power from wind turbines.

WATER Regenerative power from water turbines.

8.4.9. EnvironmentalImpact class

Amount of waste produced/emitted per kWh.

Property Type Card. Description

category EnvironmentalImpactCategory 1 The environmental impact category of this value.

amount number 1 Amount of this portion in g/kWh.

OCPI 2.2-d2

8.4.10. EnvironmentalImpactCategory enum

Categories of environmental impact values.

Value Description

NUCLEAR_WASTE Produced nuclear waste in grams per kilowatthour.

CARBON_DIOXIDE Exhausted carbon dioxide in grams per kilowatthour.

8.4.11. ExceptionalPeriod class

Specifies one exceptional period for opening or access hours.

Property Type Card. Description

period_begin DateTime 1 Begin of the exception. In UTC, time_zone field can be used to convert to local

time.

period_end DateTime 1 End of the exception. In UTC, time_zone field can be used to convert to local

time.

8.4.12. Facility enum

Value Description

HOTEL A hotel.

RESTAURANT A restaurant.

CAFE A cafe.

MALL A mall or shopping center.

SUPERMARKET A supermarket.

SPORT Sport facilities: gym, field etc.

RECREATION_AREA A recreation area.

NATURE Located in, or close to, a park, nature reserve etc.

MUSEUM A museum.

BIKE_SHARING A bike/e-bike/e-scooter sharing location.

BUS_STOP A bus stop.

TAXI_STAND A taxi stand.

TRAM_STOP A tram stop/station.

METRO_STATION A metro station.

TRAIN_STATION A train station.

AIRPORT An airport.

PARKING_LOT A parking lot.

OCPI 2.2-d2

Value Description

CARPOOL_PARKING A carpool parking.

FUEL_STATION A Fuel station.

WIFI Wifi or other type of internet available.

8.4.13. GeoLocation class

This class defines the geo location of the Charge Point. The geodetic system to be used is WGS 84.

Property Type Card. Description

latitude string(10) 1 Latitude of the point in decimal degree. Example: 50.770774. Decimal

separator: "." Regex: -?[0-9]{1,2}\.[0-9]{5,7}

longitude string(11) 1 Longitude of the point in decimal degree. Example: -126.104965. Decimal

separator: "." Regex: -?[0-9]{1,3}\.[0-9]{5,7}

NOTE

Five decimal places is seen as a minimum for GPS coordinates of the Charge Point as this gives approximately 1

meter precision. More is always better. Seven decimal places gives approximately 1cm precision.

8.4.14. Hours class

Opening and access hours of the location.

Property Type Card. Description

twentyfourseven boolean 1 True to represent 24 hours a day and 7 days a week, except the given

exceptions.

regular_hours RegularHours * Regular hours, weekday-based. Only to be used if

twentyfourseven=false, then this field needs to contain at least

one RegularHours object.

exceptional_openings ExceptionalPeriod * Exceptions for specified calendar dates, time-range based. Periods the

station is operating/accessible. Additional to regular_hours. May

overlap regular rules.

exceptional_closings ExceptionalPeriod * Exceptions for specified calendar dates, time-range based. Periods the

station is not operating/accessible. Overwriting regular_hours and

exceptional_openings. Should not overlap

exceptional_openings.

8.4.14.1. Example: 24/7 open with exceptional closing.

Open 24 hours per day, 7 days a week, except for 25th of December 2018 between 03:00 and 05:00.

{

"twentyfourseven": true,

"exceptional_closings": [{

"period_begin": "2018-12-25T03:00:00Z",

"period_end": "2018-12-25T05:00:00Z"

}]

}

OCPI 2.2-d2

twentyfourseven

Open

exceptional_closing

Closed

result opening hours

Open Open

0 1 2 3 4 5 6

Figure 25. Diagram showing a representation of the example 24/7 open with exception closing.

8.4.14.2. Example: Opening Hours with exceptional closing.

Regular opening hours between 01:00 and 06:00. With exceptional closing on 25th of December 2018 between 03:00 and 05:00.

{

"twentyfourseven": false,

"regular_hours": [{

"weekday": 1,

"period_begin": "01:00",

"period_end": "06:00"

}, {

"weekday": 2,

"period_begin": "01:00",

"period_end": "06:00"

}],

"exceptional_closings": [{

"period_begin": "2018-12-25T03:00:00Z",

"period_end": "2018-12-25T05:00:00Z"

}]

}

regular_hours

Open

exceptional_closing

Closed

result opening hours

Open Open

0 1 2 3 4 5 6

Figure 26. Diagram showing a representation of the example Opening Hours with exceptional closing

8.4.14.3. Example: Opening Hours with exceptional opening.

Regular opening hours between 00:00 and 04:00. With exceptional opening on 25th of December 2018 between 05:00 and 07:00.

OCPI 2.2-d2

{

"twentyfourseven": false,

"regular_hours": [{

"weekday": 1,

"period_begin": "00:00",

"period_end": "04:00"

}, {

"weekday": 2,

"period_begin": "00:00",

"period_end": "04:00"

}],

"exceptional_openings": [{

"period_begin": "2018-12-25T05:00:00Z",

"period_end": "2018-12-25T06:00:00Z"

}]

}

regular_hours

Open

exceptional_openings

Open

result opening hours

Open Open

0 1 2 3 4 5 6

Figure 27. Diagram showing a representation of the example Opening Hours with exceptional opening.

8.4.15. Image class

This class references an image related to an EVSE in terms of a file name or url. According to the roaming connection between one

EVSE Operator and one or more Navigation Service Providers, the hosting or file exchange of image payload data has to be

defined. The exchange of this content data is out of scope of OCPI. However, the recommended setup is a public available web

server hosted and updated by the EVSE Operator. Per charge point an unlimited number of images of each type is allowed.

Recommended are at least two images where one is a network or provider logo and the second is a station photo. If two images of

the same type are defined, not only one should be selected but both should be displayed together.

Photo Dimensions: The recommended dimensions for all photos is a minimum width of 800 pixels and a minimum height of 600

pixels. Thumbnail should always have the same orientation as the original photo with a size of 200 by 200 pixels.

Logo Dimensions: The recommended dimensions for logos are exactly 512 pixels in width height. Thumbnail representations of

logos should be exactly 128 pixels in width and height. If not squared, thumbnails should have the same orientation as the original.

Property Type Card. Description

url URL 1 URL from where the image data can be fetched through a web browser.

thumbnail URL ? URL from where a thumbnail of the image can be fetched through a

webbrowser.

category ImageCategory 1 Describes what the image is used for.

type CiString(4) 1 Image type like: gif, jpeg, png, svg.

width int(5) ? Width of the full scale image.

OCPI 2.2-d2

Property Type Card. Description

height int(5) ? Height of the full scale image.

8.4.16. ImageCategory enum

The category of an image to obtain the correct usage in a user presentation. The category has to be set accordingly to the image

content in order to guarantee the right usage.

Value Description

CHARGER Photo of the physical device that contains one or more EVSEs.

ENTRANCE Location entrance photo. Should show the car entrance to the location from street side.

LOCATION Location overview photo.

NETWORK Logo of an associated roaming network to be displayed with the EVSE for example in lists, maps

and detailed information views.

OPERATOR Logo of the charge point operator, for example a municipality, to be displayed in the EVSEs detailed

information view or in lists and maps, if no network logo is present.

OTHER Other

OWNER Logo of the charge point owner, for example a local store, to be displayed in the EVSEs detailed

information view.

8.4.17. ParkingRestriction enum

This value, if provided, represents the restriction to the parking spot for different purposes.

Value Description

EV_ONLY Reserved parking spot for electric vehicles.

PLUGGED Parking is only allowed while plugged in (charging).

DISABLED Reserved parking spot for disabled people with valid ID.

CUSTOMERS Parking spot for customers/guests only, for example in case of a hotel or shop.

MOTORCYCLES Parking spot only suitable for (electric) motorcycles or scooters.

8.4.18. ParkingType enum

Reflects the general type of the charge point’s location. May be used for user information.

Value Description

ALONG_MOTORWAY Location on a parking facility/rest area along a motorway, freeway, interstate, highway etc.

PARKING_GARAGE Multistorey car park.

PARKING_LOT A cleared area that is intended for parking vehicles, i.e. at super markets, bars, etc.

ON_DRIVEWAY Location is on the driveway of a house/building.

OCPI 2.2-d2

Value Description

ON_STREET Parking in public space along a street.

UNDERGROUND_GARAGE Multistorey car park, mainly underground.

8.4.19. PowerType enum

Value Description

AC_1_PHASE AC single phase.

AC_3_PHASE AC three phase.

DC Direct Current.

8.4.20. PublishTokenType class

Defines the set of values that identify a token to which a Location might be published.

At least one of the following fields SHALL be set: uid, visual_number, or group_id.

When uid is set, type SHALL also be set.

When visual_number is set, issuer SHALL also be set.

Property Type Card. Description

uid CiString(36) ? Unique ID by which this Token can be identified.

type TokenType ? Type of the token.

visual_number string(64) ? Visual readable number/identification as printed on the Token (RFID card).

issuer string(64) ? Issuing company, most of the times the name of the company printed on the

token (RFID card), not necessarily the eMSP.

group_id CiString(36) ? This ID groups a couple of tokens. This can be used to make two or more

tokens work as one.

8.4.21. RegularHours class

Regular recurring operation or access hours.

Property Type Card. Description

weekday int(1) 1 Number of day in the week, from Monday (1) till Sunday (7)

period_begin string(5) 1 Begin of the regular period, in local time, given in hours and minutes. Must be in

24h format with leading zeros. Example: "18:15". Hour/Minute separator: ":"

Regex: ([0-1][0-9]|2[0-3]):[0-5][0-9].

period_end string(5) 1 End of the regular period, in local time, syntax as for period_begin. Must be

later than period_begin.

OCPI 2.2-d2

8.4.21.1. Example

Operating on weekdays from 8am till 8pm with one exceptional opening on 22/6/2014 and one exceptional closing the Monday

after:

"opening_times": {

"regular_hours": [

{

"weekday": 1,

"period_begin": "08:00",

"period_end": "20:00"

{

"weekday": 2,

"period_begin": "08:00",

"period_end": "20:00"

{

"weekday": 3,

"period_begin": "08:00",

"period_end": "20:00"

{

"weekday": 4,

"period_begin": "08:00",

"period_end": "20:00"

{

"weekday": 5,

"period_begin": "08:00",

"period_end": "20:00"

}

"twentyfourseven": false,

"exceptional_openings": [

{

"period_begin": "2014-06-21T09:00:00Z",

"period_end": "2014-06-21T12:00:00Z"

}

"exceptional_closings": [

{

"period_begin": "2014-06-24T00:00:00Z",

"period_end": "2014-06-25T00:00:00Z"

}

]

}

This represents the following schedule, where stroked out days are without operation hours, bold days are where exceptions apply

and regular displayed days are where the regular schedule applies.

Week

day

Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su

Date 16 17 18 19 20 21 22 23 24 25 26 27 28 29

Open

from

08 08 08 08 08 09

08 08 08

- -

Open

till

20 20 20 20 20 12

20 20 20

- -

8.4.22. Status enum

The status of an EVSE.

OCPI 2.2-d2

Value Description

AVAILABLE The EVSE/Connector is able to start a new charging session.

BLOCKED The EVSE/Connector is not accessible because of a physical barrier, i.e. a car.

CHARGING The EVSE/Connector is in use.

INOPERATIVE The EVSE/Connector is not yet active or it is no longer available (deleted).

OUTOFORDER The EVSE/Connector is currently out of order.

PLANNED The EVSE/Connector is planned, will be operating soon.

REMOVED The EVSE/Connector was discontinued/removed.

RESERVED The EVSE/Connector is reserved for a particular EV driver and is unavailable for other drivers.

UNKNOWN No status information available (also used when offline).

8.4.23. StatusSchedule class

This type is used to schedule status periods in the future. The eMSP can provide this information to the EV user for trip planning

purposes. A period MAY have no end. Example: "This station will be running as of tomorrow. Today it is still planned and under

construction."

Property Type Card. Description

period_begin DateTime 1 Begin of the scheduled period.

period_end DateTime ? End of the scheduled period, if known.

status Status 1 Status value during the scheduled period.

NOTE

The scheduled status is purely informational. When the status actually changes, the CPO must push an update

to the EVSEs status field itself.

OCPI 2.2-d2

9. Sessions module

Module Identifier: sessions

Data owner: CPO

Type: Functional Module

The Session object describes one charging session. The Session object is owned by the CPO back-end system, and can be GET

from the CPO system, or pushed by the CPO to another system.

9.1. Flow and Lifecycle

9.1.1. Push model

When the CPO creates a Session object they push it to the corresponding eMSP by calling PUT on the eMSP’s Sessions endpoint

with the newly created Session object.

Any changes to a Session in the CPO system are sent to the eMSP system by calling PATCH on the eMSP’s Sessions endpoint

with the updated Session object.

Sessions cannot be deleted, final status of a session is: COMPLETED.

When the CPO is not sure about the state or existence of a Session object in the eMSP’s system, the CPO can call GET on the

eMSP’s Sessions endpoint to validate the Session object in the eMSP’s system.

9.1.2. Pull model

eMSPs who do not support the Push model need to call GET on the CPO’s Sessions endpoint to receive a list of Sessions.

This GET method can also be used in combination with the Push model to retrieve Sessions after the system (re-)connects to a

CPO, to get a list Sessions missed during a downtime of the eMSP’s system.

9.1.3. Set: Charging Preferences

For a lot of smart charging use cases, input from the driver is needed. The smart charging algorithms need to be able to give

certain session priority over others. In other words they need to know how much energy an EV needs before what time. Via a PUT

request on the Sender Interface, during an ongoing session, the eMSP can send Charging Preferences on behalf of the driver.

The eMSP can determine if an EVSE supports Charging Preferences by checking if the EVSE capabilities contains:

CHARGING_PREFERENCES_CAPABLE.

Via Tariffs the CPO can give different Charging Preferences different prices. A Connector can have multiple Tariffs, one for each

ProfileType.

9.1.4. Reservation

When a EV driver makes a Reservation for a Charge Point/EVSE, the Sender SHALL create a new Session object with status =

RESERVED When the Push model is used, the CPO SHALL push the new Session object to the Receiver.

When a reservation results in a charging session for the same Token, the Session object status to: ACTIVE

When a reservation does not result in a charging session, the Session object status SHALL be set to: COMPLETED.

A CDR might be created even if no energy was transferred to the EV, just for the costs of the reservation.

OCPI 2.2-d2

9.2. Interfaces and Endpoints

9.2.1. Sender Interface

Typically implemented by market roles like: CPO.

Method Description

GET Fetch Session objects of charging sessions last updated between the {date_from} and {date_to}

(paginated).

POST n/a

PUT Setting Charging Preferences of an ongoing session.

PATCH n/a

DELETE n/a

9.2.1.1. GET Method

Fetch Sessions from a CPO system.

Endpoint structure definition:

{sessions_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={li

mit}]

Examples:

https://www.server.com/ocpi/cpo/2.2/sessions/?date_from=2019-01-28T12:00:00&date_to=2019-01-

29T12:00:00

https://ocpi.server.com/2.2/sessions/?offset=50

https://www.server.com/ocpi/2.2/sessions/?date_from=2019-01-29T12:00:00&limit=100

https://www.server.com/ocpi/cpo/2.2/sessions/?offset=50&limit=100

Request Parameters

Only Sessions with last_update between the given {date_from} (including) and {date_to} (excluding) will be returned.

This request is paginated, it supports the pagination related URL parameters.

Parameter Datatype Requi

red

Description

date_from DateTime yes Only return Sessions that have last_updated after or equal to this Date/Time

(inclusive).

date_to DateTime no Only return Sessions that have last_updated up to this Date/Time, but not

including (exclusive).

offset int no The offset of the first object returned. Default is 0.

limit int no Maximum number of objects to GET.

OCPI 2.2-d2

Response Data

The response contains a list of Session objects that match the given parameters in the request, the header will contain the

pagination related headers.

Any older information that is not specified in the response is considered no longer valid. Each object must contain all required fields.

Fields that are not specified may be considered as null values.

Datatype Card. Description

Session * List of Session objects that match the

request parameters.

9.2.1.2. PUT Method

Set/update the driver’s Charging Preferences for this charging session.

Endpoint structure definition:

{sessions_endpoint_url}/{session_id}/charging_preferences

Examples:

https://www.server.com/ocpi/cpo/2.2/sessions/1234/charging_preferences

NOTE

The /charging_preferences URL suffix is required when setting Charging Preferences.

Request Parameters

The following parameter has to be provided as URL segments.

Parameter Datatype Requi

red

Description

session_id CiString(36) yes Session.id of the Session for which the Charging Preferences are to be set.

Request Body

In the body, a ChargingPreferences object has to be provided.

Type Card. Description

ChargingPreferences 1 Updated Charging Preferences of the driver for this Session.

Response Data

The response contains a ChargingPreferencesResponse value.

Type Card. Description

ChargingPreferencesRespon

1 Response to the Charging Preferences PUT request.

OCPI 2.2-d2

9.2.1.3. Receiver Interface

Typically implemented by market roles like: eMSP and SCSP.

Sessions are Client Owned Objects, so the endpoints need to contain the required extra fields: {party_id} and {country_code}.

Endpoint structure definition:

{sessions_endpoint_url}/{country_code}/{party_id}/{session_id}

Example:

https://www.server.com/ocpi/cpo/2.2/sessions/BE/BEC/1234

Method Description

GET Retrieve a Session object from the eMSP’s system with Session.id equal to {session_id}.

POST n/a

PUT Send a new/updated Session object to the eMSP.

PATCH Update the Session object with Session.id equal to {session_id}.

DELETE n/a

9.2.1.4. GET Method

The CPO system might request the current version of a Session object from the eMSP’s system to, for example, validate the state,

or because the CPO has received an error during a PATCH operation.

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the CPO performing the GET on the eMSP’s system.

party_id CiString(3) yes Party ID (Provider ID) of the CPO performing the GET on the eMSP’s system.

session_id CiString(36) yes id of the Session object to get from the eMSP’s system.

Response Data

The response contains the requested Session object.

Datatype Card. Description

Session 1 Requested Session object.

9.2.1.5. PUT Method

Inform the eMSP’s system about a new/updated Session object in the CPO’s system.

OCPI 2.2-d2

Request Body

The request contains the new or updated Session object.

Type Card. Description

Session 1 New or updated Session object.

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the CPO performing this PUT on the eMSP’s system. This

SHALL be the same value as the country_code in the Session object being

pushed.

party_id CiString(3) yes Party ID (Provider ID) of the CPO performing this PUT on the eMSP’s system.

This SHALL be the same value as the party_id in the Session object being

pushed.

session_id CiString(36) yes id of the new or updated Session object.

9.2.1.6. PATCH Method

Same as the PUT method, but only the fields/objects that need to be updated have to be present. Fields/objects which are not

specified are considered unchanged.

Any request to the PATCH method SHALL contain the last_updated field.

The PATCH method of the Session Receiver interface works on the Session Object, it SHALL NOT be used with a URL that would

try to PATCH an Object within the Session Object.

When a PATCH request contains the charging_periods field, this SHALL be processed as a request to add all the

ChargingPeriod Objects to the existing Session Object.

If existing ChargingPeriod Objects in a Session need to be replaced or removed, the Sender SHALL use the PUT method to

replace the entire Session Object.

all the exiting charging_periods SHALL be replaced by the once in the PATCH request.

Example: update the total cost

Patching the total_cost needs to be done on the Session Object.

PATCH https://www.server.com/ocpi/cpo/2.2/sessions/NL/TNM/101

{

"total_cost": {

"excl_vat": 0.60,

"incl_vat": 0.66

"last_updated": "2019-06-23T08:11:00Z"

}

OCPI 2.2-d2

Example: adding a new ChargingPeriod

PATCH used to add a new ChargingPeriod to the Session and updating all related fields.

PATCH https://www.server.com/ocpi/cpo/2.2/sessions/NL/TNM/101

{

"kwh": 15.00,

"charging_periods": [{

"start_date_time": "2019-06-23T08:16:02Z",

"dimensions": [{

"type": "ENERGY",

"volume": 2200

}]

}],

"total_cost": {

"excl_vat": 0.80,

"incl_vat": 0.88

"last_updated": "2019-06-23T08:16:02Z"

}

9.3. Object description

9.3.1. Session Object

The Session object describes one charging session. That doesn’t mean it is required that energy has been transferred between EV

and the Charge Point. It is possible that the EV never took energy from the Charge Point because it was instructed not to take

energy by the driver. But as the EV was connected to the Charge Point, some form of start tariff, park tariff or reservation cost might

be relevant.

NOTE

Although OCPI supports such pricing mechanisms, local laws might not allow this.

It is recommended to add enough ChargingPeriods to a Session so that the eMSP is able to provide feedback to the EV driver

about the progress of the charging session. The ideal amount of transmitted Charging Periods depends on the charging speed. The

Charging Periods should be sufficient for useful feedback but they should not generate too much unneeded traffic either. How many

Charging Periods are transmitted is left to the CPO to decide. The following are just some points to consider:

• Adding a new Charging Period every minute for an AC charging session can be too much as it will yield 180 Charging

Periods for an (assumed to be) average 3h session.

• A new Charging Period every 30 minutes for a DC fast charging session is not enough as it will yield only one Charging

Period for an (assumed to be) average 30min session.

It is also recommended to add Charging Periods for all moments that are relevant for the Tariff changes, see CDR object

description for more information.

For more information about how step_size impacts the calculation of the cost of charging also see the CDR object description.

Property Type Card. Description

country_code CiString(2) 1 ISO-3166 alpha-2 country code of the CPO that 'owns' this

Session.

party_id CiString(3) 1 CPO ID of the CPO that 'owns' this Session (following the ISO-

15118 standard).

id CiString(36) 1 The unique id that identifies the charging session in the CPO

platform.

OCPI 2.2-d2

Property Type Card. Description

start_date_time DateTime 1 The timestamp when the session became ACTIVE in the Charge

Point.

When the session is still PENDING, this field SHALL be set to the

time the Session was created at the Charge Point. When a Session

goes from PENDING to ACTIVE, this field SHALL be update to the

moment the Session went to ACTIVE in the Charge Point.

end_date_time DateTime ? The timestamp when the session was completed/finished, charging

might have finished before the session ends, for example: EV is full,

but parking cost also has to be paid.

kwh number 1 How many kWh were charged.

cdr_token CdrToken 1 Token used to start this charging session, including all the relevant

information to identify the unique token.

auth_method AuthMethod 1 Method used for authentication.

authorization_reference CiString(36) ? Reference to the authorization given by the eMSP. When the eMSP

provided an authorization_reference in either: real-time

authorization or StartSession, this field SHALL contain the same

value. When different authorization_reference values have

been given by the eMSP that are relevant to this Session, the last

given value SHALL be used here.

location_id CiString(36) 1 Location.id of the Location object of this CPO, on which the

charging session is/was happening.

evse_uid CiString(36) 1 EVSE.uid of the EVSE of this Location on which the charging

session is/was happening.

connector_id CiString(36) 1 Connector.id of the Connector of this Location the charging session

is/was happening.

meter_id string(255) ? Optional identification of the kWh meter.

currency string(3) 1 ISO 4217 code of the currency used for this session.

charging_periods ChargingPeriod * An optional list of Charging Periods that can be used to calculate

and verify the total cost.

total_cost Price ? The total cost of the session in the specified currency. This is the

price that the eMSP will have to pay to the CPO. A total_cost of

0.00 means free of charge. When omitted, i.e. no price information

is given in the Session object, it does not imply the session is/was

free of charge.

status SessionStatus 1 The status of the session.

last_updated DateTime 1 Timestamp when this Session was last updated (or created).

NOTE

Different authorization_reference values might happen when for example a ReserveNow had a different

authorization_reference then the value returned by a real-time authorization.

9.3.1.1. Examples

OCPI 2.2-d2

Simple Session example of just starting a session

{

"country_code": "NL",

"party_id": "STK",

"id": "101",

"start_date_time": "2020-03-09T10:17:09Z",

"kwh": 0.0,

"cdr_token": {

"uid": "123abc",

"type": "RFID",

"contract_id": "NL-TST-C12345678-S"

"auth_method": "WHITELIST",

"location_id": "LOC1",

"evse_uid": "3256",

"connector_id": "1",

"currency": "EUR",

"total_cost": {

"excl_vat": 2.5

"status": "PENDING",

"last_updated": "2020-03-09T10:17:09Z"

}

Simple Session example of a short finished session

OCPI 2.2-d2

{

"country_code": "BE",

"party_id": "BEC",

"id": "101",

"start_date_time": "2015-06-29T22:39:09Z",

"end_date_time": "2015-06-29T23:50:16Z",

"kwh": 41.00,

"cdr_token": {

"uid": "123abc",

"type": "RFID",

"contract_id": "NL-TST-C12345678-S"

"auth_method": "WHITELIST",

"location_id": "LOC1",

"evse_uid": "3256",

"connector_id": "1",

"currency": "EUR",

"charging_periods": [{

"start_date_time": "2015-06-29T22:39:09Z",

"dimensions": [{

"type": "ENERGY",

"volume": 120

}, {

"type": "MAX_CURRENT",

"volume": 30

}]

}, {

"start_date_time": "2015-06-29T22:40:54Z",

"dimensions": [{

"type": "ENERGY",

"volume": 41000

}, {

"type": "MIN_CURRENT",

"volume": 34

}]

}, {

"start_date_time": "2015-06-29T23:07:09Z",

"dimensions": [{

"type": "PARKING_TIME",

"volume": 0.718

}],

"tariff_id": "12"

}],

"total_cost": {

"excl_vat": 8.50,

"incl_vat": 9.35

"status": "COMPLETED",

"last_updated": "2015-06-29T23:50:17Z"

}

9.3.2. ChargingPreferences Object

Contains the charging preferences of an EV driver.

Property Type Card. Description

profile_type ProfileType 1 Type of Smart Charging Profile selected by the driver. The ProfileType has to be

supported at the Connector and for every supported ProfileType, a Tariff MUST

be provided. This gives the EV driver the option between different pricing

options.

departure_time DateTime ? Expected departure. The driver has given this Date/Time as expected departure

moment. It is only an estimation and not necessarily the Date/Time of the actual

departure.

energy_need number ? Requested amount of energy in kWh. The EV driver wants to have this amount

of energy charged.

OCPI 2.2-d2

Property Type Card. Description

discharge_allowed boolean ? The driver allows their EV to be discharged when needed, as long as the other

preferences are met: EV is charged with the preferred energy (energy_need)

until the preferred departure moment (departure_time). Default if omitted:

false

9.4. Data types

9.4.1. ChargingPreferencesResponse enum

Different smart charging profile types.

No value should be returned instead of NOT_SUPPORTED when a PUT with ChargingPreferences is received for an EVSE that

does not have the capability CHARGING_PROFILE_CAPABLE. Use HTTP 404 instead.

Value Description

ACCEPTED Charging Preferences accepted, EVSE will try to accomplish them, although

this is no guarantee that they will be fulfilled.

DEPARTURE_REQUIRED CPO requires departure_time to be able to perform Charging Preference

based Smart Charging.

ENERGY_NEED_REQUIRED CPO requires energy_need to be able to perform Charging Preference based

Smart Charging.

NOT_POSSIBLE Charging Preferences contain a demand that the EVSE knows it cannot fulfill.

PROFILE_TYPE_NOT_SUPPORTED profile_type contains a value that is not supported by the EVSE.

9.4.2. ProfileType enum

Different smart charging profile types.

Value Description

CHEAP Driver wants to use the cheapest charging profile possible.

FAST Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if

needed.

GREEN Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR Driver does not have special preferences.

9.4.3. SessionStatus enum

Defines the state of a session.

Value Description

ACTIVE The session has been accepted and is active. All pre-conditions were met: Communication

between EV and EVSE (for example: cable plugged in correctly), EV or driver is authorized. EV is

being charged, or can be charged. Energy is, or is not, being transfered.

OCPI 2.2-d2

Value Description

COMPLETED The session has been finished successfully. No more modifications will be made to the Session

object using this state.

INVALID The Session object using this state is declared invalid and will not be billed.

PENDING The session is pending, it has not yet started. Not all pre-conditions are met. This is the initial state.

The session might never become an active session.

RESERVATION The session is started due to a reservation, charging has not yet started. The session might never

become an active session.

OCPI 2.2-d2

10. CDRs module

Module Identifier: cdrs

Data owner: CPO

Type: Functional Module

A Charge Detail Record is the description of a concluded charging session. The CDR is the only billing-relevant object. CDRs are

sent from the CPO to the eMSP after the charging session has ended. Although there is no requirement to send CDRs in (semi-)

realtime, it is seen as good practice to send them as soon as possible. But if there is an agreement between parties to send them,

for example, once a month, that is also allowed by OCPI.

10.1. Flow and Lifecycle

CDRs are created by the CPO. They most likely will be sent only to the eMSP that needs to pay the bill of the underlying charging

session. Because a CDR is for billing purposes, it cannot be changed or replaced once sent to the eMSP. Changes are simply not

allowed. Instead, a Credit CDR can be sent.

CDRs may be send for charging locations that have not been published via the Location module. This is typically for home

chargers.

10.1.1. Credit CDRs

As CDRs are used for billing and can be seen as a kind of invoice, they cannot be deleted. Instead, they have to be credited.

When a CPO wants to make changes to a CDR that was already sent to the eMSP, the CPO has to send a Credit CDR for the first

CDR. This credit CDR SHALL have a different CDR.id which can be a completely different number, or it can be the id of the original

CDR with something appended like for example: -C to make it unique again. To indicate that a CDR is a Credit CDR, the credit

field has to be set to true. The Credit CDR references the old CDR via the credit_reference_id field, which SHALL contain

the id of the original CDR. The Credit CDR will contain all the data of the original CDR. Only the values in the total_cost field

SHALL contain the negative amounts of the original CDR.

After having sent the Credit CDR, the CPO can send a new CDR with a new unique ID and the fields: credit and

credit_reference_id omitted.

NOTE

How far back in time a CPO can send a Credit CDR is not defined by OCPI. It is up the business contracts

between the different parties involved, as there might be local laws involved etc.

10.1.2. Push model

When the CPO creates CDR(s) they push them to the relevant eMSP by calling POST on the eMSPs CDRs endpoint with the newly

created CDR(s). A CPO is not required to send all CDRs to all eMSPs, it is allowed to only send CDRs to the eMSP that a CDR is

relevant to.

CDRs should contain enough information (dimensions) to allow the eMSP to validate the total cost. It is advised to send enough

information to the eMSP so that they can calculate their own costs for billing their customers. An eMSP might have a very different

contract/pricing model with their EV drivers than the tariff structure of the CPO.

If the CPO, for any reason, wants to view a CDR it has posted to an eMSP’s system, the CPO can retrieve the CDR by performing a

GET request on the eMSP’s CDRs endpoint at the URL returned in the response to the POST.

10.1.3. Pull model

eMSPs who do not support the Push model need to call GET on the CPO’s CDRs endpoint to receive a list of CDRs.

OCPI 2.2-d2

This GET can also be used in combination with the Push model to retrieve CDRs after the system (re-)connects to a CPO, to get a

list of CDRs missed during a downtime of the eMSP’s system.

A CPO is not required to return all known CDRs, the CPO is allowed to return only the CDRs that are relevant for the requesting

eMSP.

10.2. Interfaces and Endpoints

There are both, a Sender and a Receiver interface for CDRs. Depending on business requirements, parties can decide to use the

Sender Interface (Pull model), or the Receiver Interface (Push model), or both. Push is the preferred model to use, because the

Receiver will receive CDRs in semi-realtime when they are created by the CPO.

10.2.1. Sender Interface

Typically implemented by market roles like: CPO.

The CDRs endpoint can be used retrieve CDRs.

Endpoint structure definition:

{cdr_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={limit}]

Examples:

https://www.server.com/ocpi/cpo/2.2/cdrs/?date_from=2019-01-28T12:00:00&date_to=2019-01-

29T12:00:00

https://ocpi.server.com/2.2/cdrs/?offset=50

https://www.server.com/ocpi/2.2/cdrs/?date_from=2019-01-29T12:00:00&limit=100

https://www.server.com/ocpi/cpo/2.2/cdrs/?offset=50&limit=100

Method Description

GET Fetch CDRs last updated (which in the current version of OCPI can only be the creation Date/Time) between

the {date_from} and {date_to} (paginated).

POST n/a

PUT n/a

PATCH n/a

DELETE n/a

10.2.1.1. GET Method

Fetch CDRs from the CPO’s system.

Request Parameters

If additional parameters: {date_from} and/or {date_to} are provided, only CDRs with last_updated between the given

{date_from} (including) and {date_to} (excluding) will be returned.

This request is paginated, it supports the pagination related URL parameters.

OCPI 2.2-d2

Parameter Datatype Requi

red

Description

date_from DateTime no Only return CDRs that have last_updated after or equal to this Date/Time

(inclusive).

date_to DateTime no Only return CDRs that have last_updated up to this Date/Time, but not

including (exclusive).

offset int no The offset of the first object returned. Default is 0.

limit int no Maximum number of objects to GET.

Response Data

The endpoint returns a list of CDRs matching the given parameters in the GET request, the header will contain the pagination

related headers.

Any older information that is not specified in the response is considered no longer valid. Each object must contain all required fields.

Fields that are not specified may be considered as null values.

Datatype Card. Description

CDR * List of CDRs.

10.2.2. Receiver Interface

Typically implemented by market roles like: eMSP.

The CDRs endpoint can be used to create and retrieve CDRs.

Method Description

GET Retrieve an existing CDR.

POST Send a new CDR.

PUT n/a (CDRs cannot be replaced)

PATCH n/a (CDRs cannot be updated)

DELETE n/a (CDRs cannot be removed)

10.2.2.1. GET Method

Fetch CDRs from the receivers system.

Endpoint structure definition:

No structure defined. This is open to the eMSP to define, the URL is provided to the CPO by the eMSP in the result of the POST

request. Therefore, OCPI does not define variables.

Example:

https://www.server.com/ocpi/2.2/cdrs/1234

OCPI 2.2-d2

Response URL

To retrieve an existing URL from the eMSP’s system, the URL, returned in the response to a POST of a new CDR, has to be used.

Response Data

The endpoint returns the requested CDR, if it exists.

Datatype Card. Description

CDR 1 Requested CDR object.

10.2.2.2. POST Method

Creates a new CDR.

The POST method should contain the full and final CDR object.

Endpoint structure definition:

{cdr_endpoint_url}

Example:

https://www.server.com/ocpi/2.2/cdrs/

Request Body

In the POST request the new CDR object is sent.

Type Card. Description

CDR 1 New CDR object.

Response Headers

The response should contain the URL to the just created CDR object in the eMSP’s system.

Parameter Datatype Requi

red

Description

Location URL yes URL to the newly created CDR in the eMSP’s system, can be used by the CPO

system to perform a GET on the same CDR.

The eMSP returns the URL where the newly created CDR can be found. OCPI does not define a specific structure for this URL.

Example:

https://www.server.com/ocpi/emsp/2.2/cdrs/123456

10.3. Object description

10.3.1. CDR Object

The CDR object describes the charging session and its costs, how these costs are composed, etc.

OCPI 2.2-d2

The CDR object is different from the Session object. The Session object is dynamic as it reflects the current state of the charging

session. The information is meant to be viewed by the driver while the charging session is ongoing.

The CDR on the other hand can be thought of as sealed, preserving the information valid at the moment in time the underlying

session was started. This is a requirement of the main use case for CDRs, namely invoicing. If e.g. a street is renamed the day after

a session took place, the driver should be presented with the name valid at the time the session was started. This guarantees that

the CDR will be recognized as correct by the driver and is not going to be contested.

The CDR object shall always contain information like Location, EVSE, Tariffs and Token as they were at the start of the charging

session.

ChargingPeriod: A CPO SHALL at least start (and add) a ChargingPeriod every moment/event that has relevance for the total

costs of a CDR. During a charging session, different parameters change all the time, like the amount of energy used, or the time of

day. These changes can result in another Tariff Element of the Tariff becoming active. When another Tariff Element becomes active,

the CPO SHALL add a new Charging Period with at least all the relevant information for the change to the other Tariff Element. The

CPO is allowed to add more in-between Charging Periods to a CDR though. Examples of additional Charging Periods:

• When an energy based Tariff changes in price after 17:00. The CPO SHALL start a new Charging Period at 17:00, which

contains at least the energy in kWh consumed until 17:00.

• When the price of a Tariff is higher when the EV is charging faster than 32A, a new Charging Period SHALL be added the

moment the charging power goes over 32A. This may be a moment that is calculated by the CPO, as the Charge Point

might not send the information to the CPO, but it can be interpolated by the CPO using the metering information before and

after that moment.

step_size: When calculating the cost of a charging session, step_size SHALL only be taken into account once per session for

the TariffDimensionType ENERGY and once for PARKING_TIME and TIME combined. Only the last ChargingPeriod that is relevant

for calculating ENERGY based cost shall take into account the step_size. Only the last ChargingPeriod that is relevant for

calculating TIME or PARKING_TIME based cost shall take into account the step_size.

This means that step_size is not taken into account when switching from paying for charging to paying for parking (charging has

stopped but EV still connected). Example: step_size for both charging (TIME) and parking is 5 minutes. After 21 minutes of

charging, the EV is full but remains connected for 7 more minutes. The cost of charging will be calculated based on 21 minutes (not

25). The cost of parking will be calculated based on 10 minutes (step_size is 5).

step_size is not taken into account when switching from (for example) one ENERGY based tariff to another. Example: when

charging is more expensive after 17:00. The step_size of the tariff before 17:00 will not be used when charging starts before

17:00 and ends after 17:00. Only the step_size of the tariff (PriceComponent) after 17:00 is taken into account.

The step_size for the PriceComponent that is used to calculate the cost of such a 'last' ChargingPeriod SHALL be used. If the

step_size differs for the different TariffElements, the step_size of the last relevant PriceComponent is used.

The step_size is not taken into account when switching between two Tariffs Example: A driver selects a different Charging

Preference profile_type) during an ongoing charging session, the different profile might have a different tariff.

The step_size uses the total amount of a certain unit used during a session, not only the last ChargingPeriod. In other words,

when charging tariff per kWh of time differs during a session, the total amount of kWh of time is used in calculations with

step_size. Example: Charging cost 0.20 euro before 17:00 and 0.27 after 17:00 both have a step_size of 500 Wh. If a driver

charges 4.3 kWh before 17:00 and 1.1 kWh after 17:00, a total of 5.4 kWh is charged. The step_size rounds this up to 5.5 kWh

total. It does NOT round the energy used after 17:00 to 1.5 kWh.

In the cases that TIME and PARKING_TIME Tariff Elements are both used, the total duration is used for the step_size Example:

Charging cost 1.00 euro/hour, parking 2.00 euro/hour both have a step_size of 10 minutes. If a driver charges 20 minutes, and

keeps his EV connected while it is full for another 20 minutes, a total of 40 minutes is charged. The step_size rounds this up to

45 minutes total. It does NOT round the parking duration to 30 minutes, making it a total of 50 minutes.

Property Type Card. Description

country_code CiString(2) 1 ISO-3166 alpha-2 country code of the CPO that 'owns' this CDR.

OCPI 2.2-d2

Property Type Card. Description

party_id CiString(3) 1 CPO ID of the CPO that 'owns' this CDR (following the ISO-15118

standard).

id CiString(39) 1 Uniquely identifies the CDR within the CPO’s platform (and

suboperator platforms). This field is longer than the usual 36

characters to allow for credit CDRs to have something appended to

the original ID. Normal (non-credit) CDRs SHALL only have an ID

with a maximum length of 36.

start_date_time DateTime 1 Start timestamp of the charging session, or in-case of a reservation

(before the start of a session) the start of the reservation.

end_date_time DateTime 1 The timestamp when the session was completed/finished, charging

might have finished before the session ends, for example: EV is full,

but parking cost also has to be paid.

session_id CiString(36) ? Unique ID of the Session for which this CDR is sent. Is only allowed

to be omitted when the CPO has not implemented the Sessions

module or this CDR is the result of a reservation that never became

a charging session, thus no OCPI Session.

cdr_token CdrToken 1 Token used to start this charging session, includes all the relevant

information to identify the unique token.

auth_method AuthMethod 1 Method used for authentication.

authorization_reference CiString(36) ? Reference to the authorization given by the eMSP. When the eMSP

provided an authorization_reference in either: real-time

authorization or StartSession, this field SHALL contain the same

value. When different authorization_reference values have

been given by the eMSP that are relevant to this Session, the last

given value SHALL be used here.

cdr_location CdrLocation 1 Location where the charging session took place, including only the

relevant EVSE and Connector.

meter_id string(255) ? Identification of the Meter inside the Charge Point.

currency string(3) 1 Currency of the CDR in ISO 4217 Code.

tariffs Tariff * List of relevant Tariff Elements, see: Tariff. When relevant, a Free of

Charge tariff should also be in this list, and point to a defined Free

of Charge Tariff.

charging_periods ChargingPeriod + List of Charging Periods that make up this charging session. A

session consists of 1 or more periods, where each period has a

different relevant Tariff.

signed_data SignedData ? Signed data that belongs to this charging Session.

total_cost Price 1 Total sum of all the costs of this transaction in the specified

currency.

total_fixed_cost Price ? Total sum of all the fixed costs in the specified currency, except

fixed price components of parking and reservation. The cost not

depending on amount of time/energy used etc. Can contain costs

like a start tariff.

total_energy number 1 Total energy charged, in kWh.

OCPI 2.2-d2

Property Type Card. Description

total_energy_cost Price ? Total sum of all the cost of all the energy used, in the specified

currency.

total_time number 1 Total duration of the charging session (including the duration of

charging and not charging), in hours.

total_time_cost Price ? Total sum of all the cost related to duration of charging during this

transaction, in the specified currency.

total_parking_time number ? Total duration of the charging session where the EV was not

charging (no energy was transferred between EVSE and EV), in

hours.

total_parking_cost Price ? Total sum of all the cost related to parking of this transaction,

including fixed price components, in the specified currency.

total_reservation_cost Price ? Total sum of all the cost related to a reservation of a Charge Point,

including fixed price components, in the specified currency.

remark string(255) ? Optional remark, can be used to provide additional human readable

information to the CDR, for example: reason why a transaction was

stopped.

invoice_reference_id CiString(39) ? This field can be used to reference an invoice, that will later be send

for this CDR. Making it easier to link a CDR to a given invoice.

Maybe even group CDRs that will be on the same invoice.

credit boolean ? When set to true, this is a Credit CDR, and the field

credit_reference_id needs to be set as well.

credit_reference_id CiString(39) ? Is required to be set for a Credit CDR. This SHALL contain the id

of the CDR for which this is a Credit CDR.

last_updated DateTime 1 Timestamp when this CDR was last updated (or created).

NOTE

The actual charging duration (energy being transferred between EVSE and EV) of a charging session can be

calculated: total_charging_time = total_time - total_parking_time.

NOTE

Having both a credit and a credit_reference_id might seem redundant. But it is seen as an advantage as

a boolean flag used in queries is much faster than simple string comparison of references.

NOTE

Different authorization_reference values might happen when for example a ReserveNow had a different

authorization_reference then the value returned by a real-time authorization.

10.3.1.1. Example of a CDR

OCPI 2.2-d2

{

"country_code": "BE",

"party_id": "BEC",

"id": "12345",

"start_date_time": "2015-06-29T21:39:09Z",

"end_date_time": "2015-06-29T23:37:32Z",

"cdr_token": {

"uid": "012345678",

"type": "RFID",

"contract_id": "DE8ACC12E46L89"

"auth_method": "WHITELIST",

"cdr_location": {

"id": "LOC1",

"name": "Gent Zuid",

"address": "F.Rooseveltlaan 3A",

"city": "Gent",

"postal_code": "9000",

"country": "BEL",

"coordinates": {

"latitude": "3.729944",

"longitude": "51.047599"

"evses_uid": "3256",

"evse_id": "BE*BEC*E041503003",

"connectors_id": "1",

"connectors_standard": "IEC_62196_T2",

"connectors_format": "SOCKET",

"connectors_power_type": "AC_1_PHASE"

"currency": "EUR",

"tariffs": [{

"country_code": "BE",

"party_id": "BEC",

"id": "12",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "TIME",

"price": 2.00,

"vat": 10.0,

"step_size": 300

}]

}],

"last_updated": "2015-02-02T14:15:01Z"

}],

"charging_periods": [{

"start_date_time": "2015-06-29T21:39:09Z",

"dimensions": [{

"type": "TIME",

"volume": 1.973

}],

"tariff_id": "12"

}],

"total_cost": {

"excl_vat": 4.00,

"incl_vat": 4.40

"total_energy": 15.342,

"total_time": 1.973,

"total_time_cost": {

"excl_vat": 4.00,

"incl_vat": 4.40

"last_updated": "2015-06-29T22:01:13Z"

}

10.4. Data types

OCPI 2.2-d2

10.4.1. AuthMethod enum

Value Description

AUTH_REQUEST Authentication request has been sent to the eMSP.

COMMAND Command like StartSession or ReserveNow used to start the Session, the Token provided in the

Command was used as authorization.

WHITELIST Whitelist used for authentication, no request to the eMSP has been performed.

10.4.2. CdrDimension class

Property Type Card. Description

type CdrDimension

Type

1 Type of CDR dimension.

volume number 1 Volume of the dimension consumed, measured according to the dimension type.

10.4.3. CdrDimensionType enum

This enumeration contains allowed values for CdrDimensions, which are used to define dimensions of ChargingPeriods in both

CDRs and Sessions. Some of these values are not useful for CDRs, and SHALL therefor only be used in Sessions, these are

marked in the column: Session Only

Value Session

Only

Description

CURRENT Y Average charging current during this ChargingPeriod: defined in A (Ampere). When

negative, the current is flowing from the EV to the grid.

ENERGY Total amount of energy (dis-)charged during this ChargingPeriod: defined in kWh. When

negative, more energy was feed into the grid then charged into the EV. Default step_size is

ENERGY_EXPORT Y Total amount of energy feed back into the grid: defined in kWh.

ENERGY_IMPORT Y Total amount of energy charged, defined in kWh.

MAX_CURRENT Sum of the maximum current over all phases, reached during this ChargingPeriod: defined

in A (Ampere).

MIN_CURRENT Sum of the minimum current over all phases, reached during this ChargingPeriod, when

negative, current has flowed from the EV to the grid. Defined in A (Ampere).

MAX_POWER Maximum power reached during this ChargingPeriod: defined in kW (Kilowatt).

MIN_POWER Minimum power reached during this ChargingPeriod: defined in kW (Kilowatt), when

negative, the power has flowed from the EV to the grid.

PARKING_TIME Time during this ChargingPeriod not charging: defined in hours, default step_size multiplier

is 1 second.

POWER Y Average power during this ChargingPeriod: defined in kW (Kilowatt). When negative, the

power is flowing from the EV to the grid.

OCPI 2.2-d2

Value Session

Only

Description

RESERVATION_TIME Time during this ChargingPeriod Charge Point has been reserved and not yet been in use

for this customer: defined in hours, default step_size multiplier is 1 second.

STATE_OF_CHARGE Y Current state of charge of the EV, in percentage, values allowed: 0 to 100. See note below.

TIME Time charging during this ChargingPeriod: defined in hours, default step_size multiplier is 1

second.

NOTE

OCPI makes it possible to provide SoC in the Session object. This information can be useful to show the current

State of Charge to an EV driver during charging. Implementers should be aware that SoC is only available at

some DC Chargers. Which is currently a small amount of the total amount of Charge Points. Of these DC

Chargers, only a small percentage currently provides SoC via OCPP to the CPO. Then there is also the question

if SoC is allowed to be provided to third-parties as it can be seen as privacy-sensitive information. So if an

implementer wants to show SoC in, for example an App, care should be taken, to make the App work without

SoC, as this will probably not always be available.

10.4.4. CdrLocation class

The CdrLocation class contains only the relevant information from the Location object that is needed in a CDR.

Property Type Card. Description

id CiString(36) 1 Uniquely identifies the location within the CPO’s platform (and suboperator

platforms). This field can never be changed, modified or renamed.

name string(255) ? Display name of the location.

address string(45) 1 Street/block name and house number if available.

city string(45) 1 City or town.

postal_code string(10) 1 Postal code of the location.

country string(3) 1 ISO 3166-1 alpha-3 code for the country of this location.

coordinates GeoLocation 1 Coordinates of the location.

evse_uid CiString(36) 1 Uniquely identifies the EVSE within the CPO’s platform (and suboperator

platforms). For example a database unique ID or the actual EVSE ID. This field

can never be changed, modified or renamed. This is the technical identification

of the EVSE, not to be used as human readable identification, use the field:

evse_id for that.

evse_id CiString(48) 1 Compliant with the following specification for EVSE ID from "eMI3 standard

version V1.0" (http://emi3group.com/documents-links/) "Part 2: business

objects.".

connector_id CiString(36) 1 Identifier of the connector within the EVSE.

connector_standard ConnectorTyp

1 The standard of the installed connector.

connector_format ConnectorFor

mat

1 The format (socket/cable) of the installed connector.

connector_power_type PowerType 1

OCPI 2.2-d2

10.4.5. CdrToken class

Property Type Card. Description

uid CiString(36) 1 Unique ID by which this Token can be identified.

This is the field used by the CPO’s system (RFID reader on the Charge Point) to

identify this token.

Currently, in most cases: type=RFID, this is the RFID hidden ID as read by the

RFID reader, but that is not a requirement.

If this is a type=APP_USER Token, it will be a unique, by the eMSP, generated

ID.

type TokenType 1 Type of the token

contract_id CiString(36) 1 Uniquely identifies the EV driver contract token within the eMSP’s platform (and

suboperator platforms). Recommended to follow the specification for eMA ID

from "eMI3 standard version V1.0" (http://emi3group.com/documents-links/)

"Part 2: business objects."

10.4.6. ChargingPeriod class

A Charging Period consists of a start timestamp and a list of possible values that influence this period, for example: amount of

energy charged this period, maximum current during this period etc.

Property Type Card. Description

start_date_time DateTime 1 Start timestamp of the charging period. A period ends when the next period

starts. The last period ends when the session ends.

dimensions CdrDimension + List of relevant values for this charging period.

tariff_id CiString(36) ? Unique identifier of the Tariff that is relevant for this Charging Period. If not

provided, no Tariff is relevant during this period.

10.4.7. SignedData class

This class contains all the information of the signed data. Which encoding method is used, if needed, the public key and a list of

signed values.

Property Type Card. Description

encoding_method CiString(36) 1 The name of the encoding used in the SignedData field. This is the

name given to the encoding by a company or group of companies. See

note below.

encoding_method_version int ? Version of the EncodingMethod (when applicable)

public_key CiString(512) ? Public key used to sign the data, base64 encoded.

signed_values SignedValue + One or more signed values.

url CiString(512) ? URL that can be shown to an EV driver. This URL gives the EV driver

the possibility to check the signed data from a charging session.

NOTE

For the German Eichrecht, different solutions are used, all have (somewhat) different encodings. Below the table

with known implementations and the contact information for more information.

OCPI 2.2-d2

Name Description Contact

OCMF Proposed by SAFE https://has-to-be.com

Alfen Eichrecht Alfen Eichrecht encoding / implementation. https://alfen.com/de/downloa

EDL40 E-Mobility Extension eBee smart technologies implementation https://www.ebee.berlin

EDL40 Mennekes Mennekes implementation

10.4.8. SignedValue class

This class contains the signed and the plain/unsigned data. By decoding the data, the receiver can check if the content has not

been altered.

Property Type Card. Description

nature CiString(32) 1 Nature of the value, in other words, the event this value belongs to.

Possible values at moment of writing:

- Start (value at the start of the Session)

- End (signed value at the end of the Session)

- Intermediate (signed values take during the Session, after Start, before End)

Others might be added later.

plain_data CiString(512) 1 The unencoded string of data. The format of the content depends on the

EncodingMethod field.

signed_data CiString(512) 1 Blob of signed data, base64 encoded. The format of the content depends on the

EncodingMethod field.

OCPI 2.2-d2

11. Tariffs module

Module Identifier: tariffs

Data owner: CPO

Type: Functional Module

The Tariffs module gives eMSPs information about the tariffs used by the CPO.

11.1. Flow and Lifecycle

11.1.1. Push model

When the CPO creates a new Tariff they push them to the eMSPs by calling the PUT method on the eMSPs Tariffs endpoint with

the newly created Tariff object.

Any changes to the Tariff(s) in the CPO’s system can be sent to the eMSPs systems by calling the PUT method on the eMSPs

Tariffs endpoint with the updated Tariff object.

When the CPO deletes a Tariff, they will update the eMSPs systems by calling DELETE on the eMSPs Tariffs endpoint with the ID

of the Tariff that was deleted.

When the CPO is not sure about the state or existence of a Tariff object in the system of an eMSP, the CPO can use a GET request

to validate the Tariff object in the eMSP’s system.

11.1.2. Pull model

eMSPs who do not support the Push model need to call GET on the CPO’s Tariff endpoint to receive all Tariffs, replacing the

current list of known Tariffs with the newly received list.

11.2. Interfaces and Endpoints

There is both a Sender and a Receiver interface for Tariffs. Advised is to use the push direction from Sender to Receiver during

normal operation. The Sender interface is meant to be used when the connection between two parties is established to retrieve the

current list of Tariffs objects, and when the Receiver is not 100% sure the Tariff cache is still up-to-date.

11.2.1. Sender Interface

Typically implemented by market roles like: CPO.

The Sender’s Tariffs interface gives the Receiver the ability to request Tariffs information.

Method Description

GET Returns Tariff objects from the CPO, last updated between the {date_from} and {date_to} (paginated)

POST n/a

PUT n/a

PATCH n/a

DELETE n/a

OCPI 2.2-d2

100

11.2.1.1. GET Method

Fetch information about all Tariffs.

Endpoint structure definition:

{tariffs_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={lim

it}]

Examples:

https://www.server.com/ocpi/cpo/2.2/tariffs/?date_from=2019-01-28T12:00:00&date_to=2019-01-

29T12:00:00

https://ocpi.server.com/2.2/tariffs/?offset=50

https://www.server.com/ocpi/2.2/tariffs/?date_from=2019-01-29T12:00:00&limit=100

https://www.server.com/ocpi/cpo/2.2/tariffs/?offset=50&limit=100

Request Parameters

If additional parameters: {date_from} and/or {date_to} are provided, only Tariffs with last_updated between the given

{date_from} (including) and {date_to} (excluding) will be returned.

This request is paginated, it supports the pagination related URL parameters.

Parameter Datatype Requi

red

Description

date_from DateTime no Only return Tariffs that have last_updated after or equal to this Date/Time

(inclusive).

date_to DateTime no Only return Tariffs that have last_updated up to this Date/Time, but not

including (exclusive).

offset int no The offset of the first object returned. Default is 0.

limit int no Maximum number of objects to GET.

Response Data

The endpoint returns an object with a list of valid Tariffs, the header will contain the pagination related headers.

Any older information that is not specified in the response is considered no longer valid. Each object must contain all required fields.

Fields that are not specified may be considered as null values.

Type Card. Description

Tariff * List of all tariffs.

11.2.2. Receiver Interface

Typically implemented by market roles like: eMSP and NSP.

Tariffs are Client Owned Objects, so the endpoints need to contain the required extra fields: {party_id} and {country_code}.

Endpoint structure definition:

OCPI 2.2-d2

101

{tariffs_endpoint_url}/{country_code}/{party_id}/{tariff_id}

Example:

https://www.server.com/ocpi/cpo/2.2/tariffs/BE/BEC/12

Method Description

GET Retrieve a Tariff as it is stored in the eMSP’s system.

POST n/a

PUT Push new/updated Tariff object to the eMSP.

PATCH n/a

DELETE Remove a Tariff object which is no longer in use and will not be used in future either.

11.2.2.1. GET Method

If the CPO wants to check the status of a Tariff in the eMSP’s system, it might GET the object from the eMSP’s system for validation

purposes. After all, the CPO is the owner of the object, so it would be illogical if the eMSP’s system had a different status or was

missing the object entirely.

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the CPO performing the PUT request on the eMSP’s system.

party_id CiString(3) yes Party ID (Provider ID) of the CPO performing the PUT request on the eMSP’s

system.

tariff_id CiString(36) yes Tariff.id of the Tariff object to retrieve.

Response Data

The response contains the requested object.

Type Card. Description

Tariff 1 The requested Tariff object.

11.2.2.2. PUT Method

New or updated Tariff objects are pushed from the CPO to the eMSP.

Request Body

In the PUT request, the new or updated Tariff object is sent in the body.

Type Card. Description

Tariff 1 New or updated Tariff object.

OCPI 2.2-d2

102

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the CPO performing the PUT request on the eMSP’s system.

This SHALL be the same value as the country_code in the Tariff object being

pushed.

party_id CiString(3) yes Party ID (Provider ID) of the CPO performing the PUT request on the eMSP’s

system. This SHALL be the same value as the party_id in the Tariff object

being pushed.

tariff_id CiString(36) yes Tariff.id of the Tariff object to create or replace.

Example: New Tariff 2 euro per hour charging time (not parking).

PUT To URL: https://www.server.com/ocpi/emsp/2.2/tariffs/NL/TNM/12

{

"country_code": "DE",

"party_id": "ALL",

"id": "12",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "TIME",

"price": 2.00,

"vat": 10.0,

"step_size": 300

}]

}

11.2.2.3. DELETE Method

Delete a Tariff object which is not used any more and will not be used in future either.

NOTE

Before deleting a Tariff object, it is RECOMMENDED to ensure that the Tariff object is not referenced by any

Connector object within the tariff_ids anymore.

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the CPO performing the PUT request on the eMSP’s system.

party_id CiString(3) yes Party ID (Provider ID) of the CPO performing the PUT request on the eMSP’s

system.

tariff_id CiString(36) yes Tariff.id of the Tariff object to delete.

OCPI 2.2-d2

103

11.3. Object description

11.3.1. Tariff Object

A Tariff object consists of a list of one or more Tariff Elements, which can be used to create complex Tariff structures.

When the list of Tariff Elements contains more than one Element with the same Tariff Dimension (ENERGY/FLAT/TIME etc.), than

the first Tariff Element with that Dimension in the list with matching Tariff Restrictions will be used. Only one Tariff per Element type

can be active at any point in time, but multiple Tariff Types can be active at once. IE you can have an ENERGY element and TIME

element active at the same time, but only the first valid element of each.

When no Tariff Element with a specific Dimension is found for which the Restrictions match, and there is no Tariff Element in the list

with the given Dimension without Restrictions, there will be no costs for that Tariff Dimension.

It is advised to always add a "default" Tariff Element per Dimension (ENERGY/FLAT/TIME etc.). This can be achieved by adding a

Tariff Element without Restrictions after all other occurrences of the same Dimension in the list of Tariff Elements (the order is

important). Such a Tariff Element will act as fallback when no other Tariff Element of a specific Dimension matches the relevant

parameters (Restrictions).

To define a "Free of Charge" tariff in OCPI, a Tariff with type = FLAT and price = 0.00 has to be provided. See: Free of Charge

Tariff example

Property Type Card. Description

country_code CiString(2) 1 ISO-3166 alpha-2 country code of the CPO that owns this Tariff.

party_id CiString(3) 1 CPO ID of the CPO that owns this Tariff (following the ISO-15118 standard).

id CiString(36) 1 Uniquely identifies the tariff within the CPO’s platform (and suboperator

platforms).

currency string(3) 1 ISO-4217 code of the currency of this tariff.

type TariffType ? Defines the type of the tariff. This allows for distinction in case of given Charging

Preferences. When omitted, this tariff is valid for all sessions.

tariff_alt_text DisplayText * List of multi-language alternative tariff info texts.

tariff_alt_url URL ? URL to a web page that contains an explanation of the tariff information in

human readable form.

min_price Price ? When this field is set, a Charging Session with this tariff will at least cost this

amount. This is different from a FLAT fee (Start Tariff, Transaction Fee), as a

FLAT fee is a fixed amount that has to be paid for any Charging Session. A

minimum price indicates that when the cost of a Charging Session is lower than

this amount, the cost of the Session will be equal to this amount. (Also see note

below)

max_price Price ? When this field is set, a Charging Session with this tariff will NOT cost more than

this amount. (See note below)

elements TariffElement + List of Tariff Elements.

start_date_time DateTime ? The time when this tariff becomes active, in UTC, time_zone field of the

Location can be used to convert to local time. Typically used for a new tariff that

is already given with the location, before it becomes active. (See note below)

OCPI 2.2-d2

104

Property Type Card. Description

end_date_time DateTime ? The time after which this tariff is no longer valid, in UTC, time_zone field if the

Location can be used to convert to local time. Typically used when this tariff is

going to be replaced with a different tariff in the near future. (See note below)

energy_mix EnergyMix ? Details on the energy supplied with this tariff.

last_updated DateTime 1 Timestamp when this Tariff was last updated (or created).

NOTE

min_price: As the VAT might be built up of different parts, there might be situations where minimum cost

including VAT is reached earlier or later than the minimum cost excluding VAT. So as a rule, they both apply: -

The total cost of a Charging Session excluding VAT can never be lower than the min_price excluding VAT. -

The total cost of a Charging Session including VAT can never be lower than the min_price including VAT.

NOTE

max_price: As the VAT might be built up of different parts, there might be situations where maximum cost

including VAT is reached earlier or later than the maximum cost excluding VAT. So as a rule, they both apply: -

The total cost of a Charging Session excluding VAT can never be higher than the max_price excluding VAT. -

The total cost of a Charging Session including VAT can never be higher than the max_price including VAT.

NOTE

start_date_time and end_date_time: When the Tariff of a Charge Point (Location) is changed during an

ongoing charging session, it is common to not switch the Tariff until the ongoing session is finished. But this is

NOT a rule of OCPI. When charging at a Charge Point, a driver accepts the tariff which is valid when they start

their charging session. If the Tariff of the Charge Point would change during the charging session, the driver

might get billed something they didn’t agree to when starting the session.

NOTE

The fields: tariff_alt_text and tariff_alt_url may be used separately, or in combination with each

other or even combined with the structured tariff elements. When a Tariff contains both the tariff_alt_text

and elements fields, the tariff_alt_text SHALL only contain additional tariff information in human-

readable text, not the price information that is also available via the elements field. Reason for this: the eMSP

might have additional fees they want to include in communication with their customer.

11.3.1.1. Examples

In the following section, a few different pricing strategies will be explained with some Tariff examples. For simplicity, we will use euro

as currency in all of the examples if not mentioned otherwise.

Simple Tariff example 0.25 euro per kWh

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 1 Wh

This tariff will result in costs of 5.00 euro (excl. VAT) or 5.50 euro (incl. VAT) when 20 kWh are charged.

OCPI 2.2-d2

105

{

"country_code": "DE",

"party_id": "ALL",

"id": "16",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}]

}],

"last_updated": "2018-12-17T11:16:55Z"

}

Tariff example 0.25 euro per kWh + start fee

• Start or transaction fee

• 0.50 euro (excl. VAT)

• 20% VAT

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 1 Wh

This tariff will result in total cost of 5.50 euro (excl. VAT) or 6.10 euro (incl. VAT) when 20 kWh are charged.

{

"country_code": "DE",

"party_id": "ALL",

"id": "17",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}, {

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}]

}],

"last_updated": "2018-12-17T11:36:01Z"

}

Tariff example 0.25 euro per kWh + minimum price

• Minimum price

- 0.50 euro (excl. VAT)

- 0.55 euro (incl. VAT, which is 10%)

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 1 Wh

OCPI 2.2-d2

106

This tariff will result in costs of 5.00 euro (excl. VAT) or 5.50 euro (incl. VAT) when 20 kWh are charged. But if less than 2 kWh is

charged, 0.50 euro (excl. VAT) or 0.55 euro (incl. VAT) will be billed.

This is different from a start fee as can be seen when compared to the example above.

{

"country_code": "DE",

"party_id": "ALL",

"id": "20",

"currency": "EUR",

"min_price": {

"excl_vat": 0.50,

"incl_vat": 0.55

"elements": [{

"price_components": [{

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}]

}],

"last_updated": "2018-12-17T16:45:21Z"

}

Tariff example 0.25 euro per kWh + parking fee + start fee

• Start or transaction fee

• 0.50 euro (excl. VAT)

• 20% VAT

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 1 Wh

• Parking

• 2.00 euro per hour (excl. VAT)

• 20% VAT

• Billed per 15 min (900 seconds)

For a charging session where 20 kWh are charged and the vehicle is parked for 40 minutes after the session ended, this tariff will

result in costs of 7.00 euro (excl. VAT) or 7.90 euro (incl. VAT). Because the parking time is billed per 15 minutes, the driver has to

pay for 45 minutes of parking even though they left 40 minutes after their vehicle stopped charging.

OCPI 2.2-d2

107

{

"country_code": "DE",

"party_id": "ALL",

"id": "18",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}, {

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}, {

"type": "PARKING_TIME",

"price": 2.00,

"vat": 20.0,

"step_size": 900

}]

}],

"last_updated": "2018-12-17T11:44:10Z"

}

Tariff example 0.25 euro per kWh + start fee + max price + tariff end date

• Maximum price

• 10 euro (excl. VAT)

• 11 euro (incl. VAT, which is 10%)

• Start or transaction fee

• 0.50 euro (excl. VAT)

• 20% VAT

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 1 Wh

This tariff has an end date: 30 June 2019, which is typically used when a tariff is going to be replaced by a new tariff. A Connector

of a Location can have multiple Tariffs (IDs) assigned. By assigning both, the old and the new tariff ID, they will automatically be

replaced. It is not required to update all Locations at the same time, the old tariff can also be removed later.

For a charging session where 50 kWh are charged, this tariff will result in costs of 10.00 euro (excl. VAT) or 11.00 euro (incl. VAT)

due to the price limit. If only 30 kWh were charged, the costs would be 8.00 euro (excl. VAT) and 8.85 euro (incl. VAT), as the start

fee combined with the energy costs would be lower than the defined max price.

OCPI 2.2-d2

108

{

"country_code": "DE",

"party_id": "ALL",

"id": "16",

"currency": "EUR",

"max_price": {

"excl_vat": 10.00,

"incl_vat": 11.00

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}, {

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}]

}],

"end_date_time": "2019-06-30T23:59:59Z",

"last_updated": "2018-12-17T17:15:01Z"

}

Simple Tariff example 2 euro per hour

An example of a tariff where the driver does not pay per kWh, but for the time of using the Charge Point.

• Charging Time

• 2.00 euro per hour (excl. VAT)

• 10% VAT

• Billed per 1 min (60 seconds)

As this is tariff only has a TIME price_component, the driver will not be billed for time they are not charging: PARKING_TIME

For a charging session of 2.5 hours, this tariff will result in costs of 5.00 euro (excl. VAT) or 5.50 euro (incl. VAT).

{

"country_code": "DE",

"party_id": "ALL",

"id": "12",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "TIME",

"price": 2.00,

"vat": 10.0,

"step_size": 60

}]

}],

"last_updated": "2015-06-29T20:39:09Z"

}

Simple Tariff example 3 euro per hour, 5 euro per hour parking

Example of a tariff where the driver pays for the time of using the Charge Point, but pays more when the car is no longer charging,

to discourage the EV driver of leaving his EV connected when it is already full.

• Charging Time

• 3.00 euro per hour (excl. VAT)

OCPI 2.2-d2

109

• 10% VAT

• Billed per 1 min (60 seconds)

• Parking

• 5.00 euro per hour (excl. VAT)

• 20% VAT

• Billed per 5 min (300 seconds)

A charging session of 2.5 hours (charging), where the vehicle is parked for 42 more minutes after charging ended, results in a total

session time of 150 minutes (charging) + 42 minutes (parking). This session with this tariff will result in total cost of 11.25 euro

(excl. VAT) or 12.75 euro (incl. VAT). Because the parking time is billed per 5 minutes, the driver has to pay for 45 minutes of

parking even though they left 42 minutes after their vehicle stopped charging.

{

"country_code": "DE",

"party_id": "ALL",

"id": "21",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "TIME",

"price": 3.00,

"vat": 10.0,

"step_size": 60

}, {

"type": "PARKING_TIME",

"price": 5.00,

"vat": 20.0,

"step_size": 300

}]

}],

"last_updated": "2018-12-17T17:00:43Z"

}

Ad-Hoc simple Tariff example with multiple languages

For ad-hoc charging (paying for charging without a contract), the tariff elements are less needed. The eMSP is not involved when

a driver uses ad-hoc payment at the Charge Point, so no CDR is send to an eMSP. Having a good human readable text is much

more useful.

• Charging Time

• 1.9 euro per hour (excl. VAT)

• 5.2% VAT

• Billed per 5 minutes (300 seconds)

For a charging session of 2.5 hours, this tariff will result in costs of 4.75 euro (excl. VAT) or 5.00 euro (incl. VAT).

OCPI 2.2-d2

110

{

"country_code": "DE",

"party_id": "ALL",

"id": "12",

"currency": "EUR",

"type": "AD_HOC_PAYMENT",

"tariff_alt_text": [{

"language": "en",

"text": "2.00 euro p/hour including VAT."

}, {

"language": "nl",

"text": "2.00 euro p/uur inclusief BTW."

}],

"elements": [{

"price_components": [{

"type": "TIME",

"price": 1.90,

"vat": 5.2,

"step_size": 300

}]

}],

"last_updated": "2015-06-29T20:39:09Z"

}

Ad-Hoc Tariff example not possible with OCPI

For this example, the credit card start tariff is 0.50 euro, but when using a debit card it is only 0.25 euro.

Such a tariff cannot be modeled with OCPI.

But by modeling it as 0.50 euro start tariff where debit card users are given a discount in the final CDR of 0.25 euro, nobody is likely

to complain. The tariff_alt_text explains this clearly.

{

"country_code": "DE",

"party_id": "ALL",

"id": "19",

"currency": "EUR",

"type": "AD_HOC_PAYMENT",

"tariff_alt_text": [{

"language": "en",

"text": "2.00 euro p/hour, start tariff debit card: 0.25 euro, credit card: 0.50 euro including VAT."

}, {

"language": "nl",

"text": "2.00 euro p/uur, starttarief bankpas: 0,25 euro, creditkaart: 0,50 euro inclusief BTW."

}],

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 0.40,

"vat": 25.0,

"step_size": 1

}, {

"type": "TIME",

"price": 1.90,

"vat": 5.2,

"step_size": 300

}]

}],

"last_updated": "2018-17-29T15:55:58Z"

}

Simple Tariff example with alternative URL

This examples shows the use of tariff_alt_url.

This examples shows a PROFILE_CHEAP tariff, which is a smart charging tariff. Drivers are able to select this tariff by setting the

profile_type in their Charging Preferences to CHEAP. In such case, the price might not be fixed, but depend on the real-time

OCPI 2.2-d2

111

energy prices. To explain this to the driver, a short text inside tariff_alt_text might not be the best solution. Showing a graph

could be better. Therefore it is also possible to provide an URL in tariff_alt_url to a site that explains the tariff better and in

more detail.

• Start or transaction fee

• 0.50 euro (excl. VAT)

• 20% VAT

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 0.1 kWh (100 Wh)

For a charging session where 20.45 kWh are charged: this tariff will result in:

• Start fee: 0.50 euro (excl. VAT), 0.60 euro (incl. VAT)

• Energy costs: 5.13 euro (excl. VAT), 5.64 euro (incl. VAT)

• Total: 5.63 euro (excl. VAT), 6.24 euro (incl. VAT)

if the announced prices were billed. Because the energy is billed per 0.1 kWh, the driver has to pay for 20.5 kWh even though they

only charged 20.45 kWh. Total cost of this session including the transaction fee:

The twist here is that this tariff makes use of tariff_alt_url which links to a page with real-time energy prices of the operator,

where is shown that the actual price per kWh is different. With an assumed current energy price of 0.22 euro per kWh (excl. VAT),

which is shown or explained on the page linked by tariff_alt_url, the resulting costs:

• Start fee: 0.50 euro (excl. VAT), 0.60 euro (incl. VAT)

• Energy costs: 4.51 euro (excl. VAT), 4.96 (incl. VAT)

• Total: 5.01 euro (excl. VAT), 5.56 euro (incl. VAT)

{

"country_code": "DE",

"party_id": "ALL",

"id": "13",

"currency": "EUR",

"type": "PROFILE_CHEAP",

"tariff_alt_url": "https://company.com/tariffs/13",

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}, {

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 100

}]

}],

"last_updated": "2015-06-29T20:39:09Z"

}

Complex Tariff example

• Start or transaction fee

• 2.50 euro (excl. VAT)

• 15% VAT

OCPI 2.2-d2

112

• Charging Time

• When charging with less than 32A

• 1.00 euro per hour (excl. VAT)

• 20% VAT

• Billed per 15 min (900 seconds)

• When charging with more than 32A on weekdays

• 2.00 euro per hour (excl. VAT)

• 20% VAT

• Billed per 10 min (600 seconds)

• When charging with more than 32A on weekends

• 1.25 euro per hour (excl. VAT)

• 20% VAT

• Billed per 10 min (600 seconds)

• Parking

• On weekdays between 09:00 and 18:00

• 5 euro per hour (excl. VAT)

• 10% VAT

• Billed per 5 min (300 seconds)

• On Saturday between 10:00 and 17:00

• 6 euro per hour (excl. VAT)

• 10% VAT

• Billed per 5 min (300 seconds)

For a charging session on a Monday morning starting at 09:30 which takes 2:45 hours (165 minutes), where the driver uses a

maximum of 16A of power and is parking for additional 42 minutes afterwards, this tariff will result in costs of 9.00 euro (excl. VAT)

or 10.30 euro (incl. VAT) for a total session time of 147 minutes (charging) + 42 minutes (parking). As the tariff switches from a

TIME based tariff to PARKING_TIME, step_size is not used on the charging time, only on the parking time. The driver has to pay

for 165 minutes charging (2.75 euro excl. VAT) and 45 minutes of parking as its billed per 5 minutes (3.75 euro excl. VAT).

For a charging session on a Saturday afternoon starting at 13:30 which takes 1:54 hours, where the driver uses a minimum of 43A

of power (all the time, which is only theoretically possible) and is parking for additional 71 minutes afterwards, this tariff will result in

a total cost of 12.375 euro (excl. VAT) or 13.975 euro (incl. VAT). Total charging time of 114 minutes (2.375 euro excl. VAT) + 71

minutes (parking) due to step_size: 75 minutes (7.50 euro excl VAT).

OCPI 2.2-d2

113

{

"country_code": "DE",

"party_id": "ALL",

"id": "14",

"currency": "EUR",

"type": "REGULAR",

"tariff_alt_url": "https://company.com/tariffs/14",

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 2.50,

"vat": 15.0,

"step_size": 1

}]

}, {

"price_components": [{

"type": "TIME",

"price": 1.00,

"vat": 20.0,

"step_size": 900

}],

"restrictions": {

"max_current": 32.00

}

}, {

"price_components": [{

"type": "TIME",

"price": 2.00,

"vat": 20.0,

"step_size": 600

}],

"restrictions": {

"min_current": 32.00,

"day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]

}

}, {

"price_components": [{

"type": "TIME",

"price": 1.25,

"vat": 20.0,

"step_size": 600

}],

"restrictions": {

"min_current": 32.00,

"day_of_week": ["SATURDAY", "SUNDAY"]

}

}, {

"price_components": [{

"type": "PARKING_TIME",

"price": 5.00,

"vat": 10.0,

"step_size": 300

}],

"restrictions": {

"start_time": "09:00",

"end_time": "18:00",

"day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]

}

}, {

"price_components": [{

"type": "PARKING_TIME",

"price": 6.00,

"vat": 10.0,

"step_size": 300

}],

"restrictions": {

"start_time": "10:00",

"end_time": "17:00",

"day_of_week": ["SATURDAY"]

}

}],

"last_updated": "2015-06-29T20:39:09Z"

}

OCPI 2.2-d2

114

Free of Charge Tariff example

In this example no VAT is given because it is not necessary (as the price is 0.00). This might not always be the case though and

it is of course permitted to add a VAT, even if the price is set to zero.

{

"country_code": "DE",

"party_id": "ALL",

"id": "15",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 0.00,

"step_size": 0

}]

}],

"last_updated": "2015-06-29T20:39:09Z"

}

First hour free energy example

In this example, we have the following scenario:

• The first hour of parking time is free.

• From the second to the fourth hour, parking costs 2.00 euro per hour

• From the fourth hour on, parking costs 3.00 euro per hour.

• The first kWh of energy is free, every additional kWh costs 0.20 euro.

Translated into our tariff schema, the pricing model looks like this:

• Energy

• First kWh: free

• Any additional energy

• 0.20 euro per kWh (excl. VAT)

• Billed per 1 Wh

• Parking

• First hour of parking: free

• Second to fourth hours of parking

• 2.00 euro per hour (excl. VAT)

• Billed per 1 min (60 seconds)

• Any parking after four hours

• 3.00 euro per hour (excl. VAT)

• Billed per 1 min (60 seconds)

For a charging session where the driver charges 20 kWh and where the vehicle is parked for 2:45 more hours after charging ended,

this tariff will result in costs of 7.30 euro (excl. VAT).

Cost breakdown:

• Energy: 19 kWh (first kWh is free) = 3.80 euro.

• Parking: 2:45 hours = 1:45 hours of paid parking (105 minutes) = 3.50 euro

As no VAT information is given, it is not possible to calculate total costs including VAT.

OCPI 2.2-d2

115

{

"country_code": "DE",

"party_id": "ALL",

"id" : "52",

"currency" : "EUR",

"elements" : [ {

"price_components" : [ {

"type" : "PARKING_TIME",

"price" : 0.0,

"step_size" : 60

} ],

"restrictions" : {

"min_duration" : 0,

"max_duration" : 3600

}

}, {

"price_components" : [ {

"type" : "PARKING_TIME",

"price" : 2.0,

"step_size" : 60

} ],

"restrictions" : {

"min_duration" : 3600,

"max_duration" : 10800

}

}, {

"price_components" : [ {

"type" : "PARKING_TIME",

"price" : 3.0,

"step_size" : 60

} ],

"restrictions" : {

"min_duration" : 10800

}

}, {

"price_components" : [ {

"type" : "ENERGY",

"price" : 0.0,

"step_size" : 1

} ],

"restrictions" : {

"max_kwh" : 1.0

}

}, {

"price_components" : [ {

"type" : "ENERGY",

"price" : 0.2,

"step_size" : 1

} ],

"restrictions" : {

"min_kwh" : 1.0

}

} ]

}

Tariff example with reservation price

• Reservation

• 5.00 euro per hour (excl. VAT)

• 20% VAT

• Billed per 1 min (60 seconds)

• Start or transaction fee

• 0.50 euro (excl. VAT)

• 20% VAT

• Energy

OCPI 2.2-d2

116

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 1 Wh

For a charging session that was started 15 minutes after the reservation time, where the driver charges 20 kWh, this tariff will result

in costs of 6.75 euro (excl. VAT) or 7.60 euro (incl. VAT).

Cost breakdown:

• Start fee: 0.50 euro excl VAT, 0.60 incl. VAT.

• Energy: 20 kWh = 5.00 euro excl. VAT, 5.50 euro incl. VAT.

• Reservation: 0:15 hours (15 minutes) = 1.25 euro excl. VAT, 1.50 euro incl. VAT.

{

"country_code": "DE",

"party_id": "ALL",

"id": "20",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "TIME",

"price": 5.00,

"vat": 20.0,

"step_size": 60

}],

"restrictions": {

"reservation": "RESERVATION"

}

}, {

"price_components": [{

"type": "FLAT",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}, {

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}]

}],

"last_updated": "2019-02-03T17:00:11Z"

}

Tariff example with reservation price and fee

• Reservation

• 2.00 euro reservation fee (excl. VAT)

• 5.00 euro per hour (excl. VAT)

• 20% VAT

• Billed per 5 min (300 seconds)

• Start or transaction fee

• 0.50 euro (excl. VAT)

• 20% VAT

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

OCPI 2.2-d2

117

• Billed per 1 Wh

For a charging session that was started 13 minutes after the reservation time, where the driver charges 20 kWh, this tariff will result

in costs of 8.75 euro (excl. VAT) or 10.00 euro (incl. VAT). Because the reservation fee is billed per 5 minutes, the driver has to pay

for 15 minutes of reservation even though they started the charging session 13 minutes after the reservation time.

Cost breakdown:

• Start fee: 0.50 euro excl VAT, 0.60 incl. VAT.

• Energy: 20 kWh = 5.00 euro excl. VAT, 5.50 euro incl. VAT.

• Reservation fee: 2.00 euro excl VAT, 2.00 incl. VAT.

• Reservation: 0:15 hours (15 minutes) = 1.25 euro excl. VAT, 1.50 euro incl. VAT.

{

"country_code": "DE",

"party_id": "ALL",

"id": "20",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 2.00,

"vat": 20.0,

"step_size": 1

}, {

"type": "TIME",

"price": 5.00,

"vat": 20.0,

"step_size": 300

}],

"restrictions": {

"reservation": "RESERVATION"

}

}, {

"price_components": [{

"type": "FLAT",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}, {

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}]

}],

"last_updated": "2019-02-03T17:00:11Z"

}

Tariff example with reservation price and expire fee

• Reservation

• 4.00 euro reservation expiration fee (excl. VAT) (billed when a reservation expires and is not followed by a charging

session)

• 2.00 euro per hour (excl. VAT)

• 20% VAT

• Billed per 10 min (600 seconds)

• Start or transaction fee

• 0.50 euro (excl. VAT)

• 20% VAT

OCPI 2.2-d2

118

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 1 Wh

This example is very similar to Tariff example with reservation price with the difference that expired reservations cost something and

that reservation time is billed per 10 minutes. Also, the price for reservation is different.

For a charging session that was started 22 minutes after the reservation time, where the driver charges 20 kWh, this tariff will result

in costs of 6.50 euro (excl. VAT) or 7.30 euro (incl. VAT). Because the reservation fee is billed per 10 minutes, the driver has to pay

for 30 minutes of reservation even though they started the charging session 22 minutes after the reservation time.

If the driver did not start a charging session and the reservation expired after the reserved time of 1 hour, the tariff would have

resulted in costs of 6.00 euro (excl. VAT) or 7.20 euro (incl. VAT). In case a reservation is not used, the driver has to pay the full

amount of reserved time as well as an additional expiration fee as compensation for not charging at all.

{

"country_code": "DE",

"party_id": "ALL",

"id": "20",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "FLAT",

"price": 4.00,

"vat": 20.0,

"step_size": 1

}],

"restrictions": {

"reservation": "RESERVATION_EXPIRES"

}

}, {

"price_components": [{

"type": "TIME",

"price": 2.00,

"vat": 20.0,

"step_size": 600

}],

"restrictions": {

"reservation": "RESERVATION"

}

}, {

"price_components": [{

"type": "FLAT",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}, {

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}]

}],

"last_updated": "2019-02-03T17:00:11Z"

}

Tariff example with reservation time and expire time

• Reservation

• 3.00 euro per hour (excl. VAT)

• 6.00 euro per hour (excl. VAT) (billed when a reservation expires and is not followed by a charging session)

• 20% VAT

OCPI 2.2-d2

119

• Billed per 10 min (600 seconds)

• Start or transaction fee

• 0.50 euro (excl. VAT)

• 20% VAT

• Energy

• 0.25 euro per kWh (excl. VAT)

• 10% VAT

• Billed per 1 Wh

This example is very similar to Tariff example with reservation price with the difference that expired reservations cost something and

that reservation time is billed per 10 minutes. Also, the price for reservation is different.

For a charging session that was started 22 minutes after the reservation time, where the driver charges 20 kWh, this tariff will result

in costs of 7.00 euro (excl. VAT) or 7.90 euro (incl. VAT). Because the reservation fee is billed per 10 minutes, the driver has to pay

for 30 minutes of reservation even though they started the charging session 22 minutes after the reservation time.

If the driver did not start a charging session and the reservation expired after the reserved time of 1.5 hours, the tariff would have

resulted in costs of 9.00 euro (excl. VAT) or 10.80 euro (incl. VAT). In case a reservation is not used, the driver has to pay the

expiration fee as compensation for not charging at all.

{

"country_code": "DE",

"party_id": "ALL",

"id": "20",

"currency": "EUR",

"elements": [{

"price_components": [{

"type": "TIME",

"price": 6.00,

"vat": 20.0,

"step_size": 600

}],

"restrictions": {

"reservation": "RESERVATION_EXPIRES"

}

}, {

"price_components": [{

"type": "TIME",

"price": 3.00,

"vat": 20.0,

"step_size": 600

}],

"restrictions": {

"reservation": "RESERVATION"

}

}, {

"price_components": [{

"type": "FLAT",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}, {

"type": "ENERGY",

"price": 0.25,

"vat": 10.0,

"step_size": 1

}]

}],

"last_updated": "2019-02-03T17:00:11Z"

}

OCPI 2.2-d2

120

11.4. Data types

11.4.1. DayOfWeek enum

Value Description

MONDAY Monday

TUESDAY Tuesday

WEDNESDAY Wednesday

THURSDAY Thursday

FRIDAY Friday

SATURDAY Saturday

SUNDAY Sunday

11.4.2. PriceComponent class

Property Type Card

Description

type TariffDimensionType 1 Type of tariff dimension.

price number 1 Price per unit (excl. VAT) for this tariff dimension.

vat number ? Applicable VAT percentage for this tariff dimension. If omitted, no VAT

is applicable. Not providing a VAT is different from 0% VAT, which would

be a value of 0.0 here.

step_size int 1 Minimum amount to be billed. This unit will be billed in this step_size

blocks. Amounts that are less then this step_size are rounded up to

the given step_size. For example: if type is TIME and step_size

has a value of 300, then time will be billed in blocks of 5 minutes. If 6

minutes were used, 10 minutes (2 blocks of step_size) will be billed.

NOTE

step_size: depends on the type and every type (except FLAT) defines a step_size multiplier, which is the

size of every step for that type in the given unit.

For example: PARKING_TIME has the step_size multiplier: 1 second, which means that the step_size of a

PriceComponent is multiplied by 1 second. Thus a step_size = 300 means 300 seconds (5 minutes).

This means that when someone parked for 8 minutes they will be billed for 10 minutes. The parking time will be

simply rounded up to the next larger chunk of step_size (i.e. blocks of 300 seconds in this example).

Another example: ENERGY has the step_size multiplied: 1 Wh, which means that the step_size of a

PriceComponent is multiplied by 1 Wh. Thus a step_size = 1 with a price = 0.25 will result in a cost

calculation that uses the charged Wh as precision.

If someone charges their EV with 115.2 Wh, then they are billed for 116 Wh, resulting in total cost of 0.029 euro.

When step_size = 25, then the same amount would be billed for 101 to 125 Wh: 0.031 euro.

When step_size = 500, then the same amount will be billed for 1 to 500 Wh: 0.125 euro.

NOTE

For more information about how step_size impacts the calculation of the cost of charging see: CDR object

description

OCPI 2.2-d2

121

NOTE

Take into account that using step_size can be confusing for customers/drivers. There may be local or national

regulations that define max step_size. E.g. in The Netherlands telecom companies are required to at least

offer one subscription which is paid per second. To prevent confusion by the customer, we recommend to keep

the step_size as small as possible and mention them clearly in your offering.

11.4.2.1. Example Tariff

Example Tariff to explain the step_size when switching from one TariffElement to another:

• Charging fee of 1.20 euro per hour (excl. VAT) before 17:00 with a step_size of 30 minutes (1800 seconds)

• Charging fee of 2.40 euro per hour (excl. VAT) after 17:00 with a step_size of 15 minutes (900 seconds)

• Parking fee of 1.00 euro per hour (excl. VAT) before 20:00 with a step_size of 15 minutes (900 seconds)

OCPI 2.2-d2

122

{

"country_code": "DE",

"party_id": "ALL",

"id": "22",

"currency": "EUR",

"elements": [

{

"price_components": [

{

"type": "TIME",

"price": 1.20,

"step_size": 1800

{

"type": "PARKING_TIME",

"price": 1.00,

"step_size": 900

}

"restrictions" : {

"start_time" : "00:00",

"end_time" : "17:00"

}

{

"price_components": [

{

"type": "TIME",

"price": 2.40,

"step_size": 900

{

"type": "PARKING_TIME",

"price": 1.00,

"step_size": 900

}

"restrictions" : {

"start_time" : "17:00",

"end_time" : "20:00"

}

{

"price_components": [

{

"type": "TIME",

"price": 2.40,

"step_size": 900

}

"restrictions" : {

"start_time" : "20:00",

"end_time" : "00:00"

}

"last_updated": "2018-12-18T17:07:11Z"

}

Example: switching to different Tariff Element #1

An EV driver plugs in at 16:55 and charges for 10 minutes (TIME). They then stop charging but stay plugged in for 2 more minutes

(PARKING_TIME). The total session time is therefore 12 minutes, resulting in the following costs:

• 5 billable minutes of charging time before 17:00, generating costs of 0.10 euro.

• 5 billable minutes of charging time after 17:00, generating costs of 0.20 euro. (step_size is not taken into account as we

are switching to another time based Tariff Element).

• 5 billable minutes of parking time (due to the step_size, total duration of 12 minutes is rounded to 15 minutes), generating

costs of 0.083 euro.

OCPI 2.2-d2

123

• The total for this charging session is therefore 0.383 euro (excl. VAT).

Example: switching to different Tariff Element #2

An EV driver plugs in at 16:35 and charges for 35 minutes (TIME). After that they immediately unplug, leaving with a total session

time of 35 minutes and a bill over the following costs:

• 25 billable minutes of charging time before 17:00, generating costs of 0.50 euro.

• 20 billable minutes of charging time after 17:00, generating costs of 0.80 euro. As the Price Component of the last Tariff

Element being used has a step_size of 15 minutes, the total duration is rounded to up to 45 minutes. When considering

the already billed 25 minutes of charging time before 17:00, we are left with 20 minutes to bill after 17:00.

• The total for this charging session is therefore 1.30 euro (excl. VAT).

Example: switching to Free-of-Charge Tariff Element

When parking becomes free after 20:00, the new TariffElement after 20:00 will not contain a PARKING_TIME (or TIME)

PriceComponent. So the last parking period that needs to be paid, which is before 20:00, will be billed according to the

step_size of the PARKING_TIME PriceComponent before 20:00.

An EV driver plugs in at 19:40 and charges for 12 minutes (TIME). They then stop charging but stay plugged in for 20 more minutes

(PARKING_TIME). The total session time is therefore 12 minutes, resulting in the following costs:

• 12 billable minutes of charging time, generating costs of 0.48 euro.

• 18 billable minutes of parking time, generating costs of 0.30 euro. As the Price Component of the last Tariff Element being

used has a step_size of 15 minutes, we bill a total duration of 30 minutes. When considering the already billed 12

minutes of charging time, we are left with 18 minutes of parking time to bill. The fact that parking is free after 20:00 has no

impact on step_size

• The total for this charging session is therefore 0.78 euro (excl. VAT).

11.4.3. ReservationRestrictionType enum

Value Description

RESERVATION Used in TariffElements to describe costs for a reservation.

RESERVATION_EXPIRES Used in TariffElements to describe costs for a reservation that expires (i.e. driver does not start a

charging session before expiry_date of the reservation).

NOTE

When a Tariff has both, RESERVATION and RESERVATION_EXPIRES TariffElements, where both TariffElements

have a TIME PriceComponent, then the time based cost of an expired reservation will be calculated based on the

RESERVATION_EXPIRES TariffElement.

11.4.4. TariffElement class

Property Type Card

Description

price_components PriceComponent + List of price components that describe the pricing of a tariff.

restrictions TariffRestrictions ? Restrictions that describe the applicability of a tariff.

OCPI 2.2-d2

124

11.4.5. TariffDimensionType enum

Value Description

ENERGY Defined in kWh, step_size multiplier: 1 Wh

FLAT Flat fee without unit for step_size

PARKING_TIME Time not charging: defined in hours, step_size multiplier: 1 second

TIME Time charging: defined in hours, step_size multiplier: 1 second

Can also be used in combination with a RESERVATION restriction to describe the price of the

reservation time.

11.4.6. TariffRestrictions class

These restrictions are not for the entire Charging Session. They only describe if and when a TariffElement becomes active or

inactive during a Charging Session.

Property Type Card. Description

start_time string(5) ? Start time of day in local time, the time zone is defined in the time_zone field of

the Location, for example 13:30, valid from this time of the day. Must be in 24h

format with leading zeros. Hour/Minute separator: ":" Regex: ([0-1][0-

9]|2[0-3]):[0-5][0-9]

end_time string(5) ? End time of day in local time, the time zone is defined in the time_zone field of

the Location, for example 19:45, valid until this time of the day. Same syntax as

start_time. If end_time < start_time then the period wraps around to the next

day. To stop at end of the day use: 00:00.

start_date string(10) ? Start date in local time, the time zone is defined in the time_zone field of the

Location, for example: 2015-12-24, valid from this day (inclusive). Regex:

([12][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])

end_date string(10) ? End date in local time, the time zone is defined in the time_zone field of the

Location, for example: 2015-12-27, valid until this day (exclusive). Same syntax

as start_date.

min_kwh number ? Minimum consumed energy in kWh, for example 20, valid from this amount of

energy (inclusive) being used.

max_kwh number ? Maximum consumed energy in kWh, for example 50, valid until this amount of

energy (exclusive) being used.

min_current number ? Sum of the minimum current (in Amperes) over all phases, for example 5. When

the EV is charging with more than, or equal to, the defined amount of current,

this TariffElement is/becomes active. If the charging current is or becomes lower,

this TariffElement is not or no longer valid and becomes inactive. This describes

NOT the minimum current over the entire Charging Session. This restriction can

make a TariffElement become active when the charging current is above the

defined value, but the TariffElement MUST no longer be active when the

charging current drops below the defined value.

OCPI 2.2-d2

125

Property Type Card. Description

max_current number ? Sum of the maximum current (in Amperes) over all phases, for example 20.

When the EV is charging with less than the defined amount of current, this

TariffElement becomes/is active. If the charging current is or becomes higher,

this TariffElement is not or no longer valid and becomes inactive. This describes

NOT the maximum current over the entire Charging Session. This restriction can

make a TariffElement become active when the charging current is below this

value, but the TariffElement MUST no longer be active when the charging

current raises above the defined value.

min_power number ? Minimum power in kW, for example 5. When the EV is charging with more than,

or equal to, the defined amount of power, this TariffElement is/becomes active. If

the charging power is or becomes lower, this TariffElement is not or no longer

valid and becomes inactive. This describes NOT the minimum power over the

entire Charging Session. This restriction can make a TariffElement become

active when the charging power is above this value, but the TariffElement MUST

no longer be active when the charging power drops below the defined value.

max_power number ? Maximum power in kW, for example 20. When the EV is charging with less than

the defined amount of power, this TariffElement becomes/is active. If the

charging power is or becomes higher, this TariffElement is not or no longer valid

and becomes inactive. This describes NOT the maximum power over the entire

Charging Session. This restriction can make a TariffElement become active

when the charging power is below this value, but the TariffElement MUST no

longer be active when the charging power raises above the defined value.

min_duration int ? Minimum duration in seconds the Charging Session MUST last (inclusive).

When the duration of a Charging Session is longer than the defined value, this

TariffElement is or becomes active. Before that moment, this TariffElement is not

yet active.

max_duration int ? Maximum duration in seconds the Charging Session MUST last (exclusive).

When the duration of a Charging Session is shorter than the defined value, this

TariffElement is or becomes active. After that moment, this TariffElement is no

longer active.

day_of_week DayOfWeek * Which day(s) of the week this TariffElement is active.

reservation ReservationR

estrictionType

? When this field is present, the TariffElement describes reservation costs. A

reservation starts when the reservation is made, and ends when the driver

starts charging on the reserved EVSE/Location, or when the reservation

expires. A reservation can only have: FLAT and TIME TariffDimensions, where

TIME is for the duration of the reservation.

11.4.6.1. Example: Tariff with max_power Tariff Restrictions

Example Tariff to explain the max_power Tariff Restriction:

• Charging fee of 0.20 euro per kWh (excl. VAT) when charging with a power of less than 16 kW.

• Charging fee of 0.35 euro per kWh (excl. VAT) when charging with a power between 16 and 32 kW.

• Charging fee of 0.50 euro per kWh (excl. VAT) when charging with a power above 32 kW (implemented as fallback tariff

without Restriction).

For a charging session where the EV charges the first kWh with a power of 6 kW, increases the power to 48 kW for the next 40 kWh

and reduces it again to 4 kW after that for another 0.5 kWh (probably due to physical limitations, i.e. temperature of the battery), this

tariff will result in costs of 20.30 euro (excl. VAT). The costs are composed of the following components:

OCPI 2.2-d2

126

• 1 kWh at 6 kW: 0.20 euro

• 40 kWh at 48 kW: 20.00 euro

• 0.5 kWh at 4 kW: 0.10 euro

{

"country_code": "DE",

"party_id": "ALL",

"id": "1",

"currency": "EUR",

"type": "REGULAR",

"elements": [{

"price_components": [{

"type": "ENERGY",

"price": 0.20,

"vat": 20.0,

"step_size": 1

}],

"restrictions": {

"max_power": 16.00

}

}, {

"price_components": [{

"type": "ENERGY",

"price": 0.35,

"vat": 20.0,

"step_size": 1

}],

"restrictions": {

"max_power": 32.00

}

}, {

"price_components": [{

"type": "ENERGY",

"price": 0.50,

"vat": 20.0,

"step_size": 1

}]

}],

"last_updated": "2018-12-05T12:01:09Z"

}

11.4.6.2. Example: Tariff with max_duration Tariff Restrictions

A supermarket wants to allow their customer to charge for free. As most customers will be out of the store in 20 minutes, they allow

free charging for 30 minutes. If a customer charges longer than that, they will charge them the normal price per kWh. But as they

want to discourage long usage of their Charge Points, charging becomes much more expensive after 1 hour:

• First 30 minutes of charging is free.

• Charging fee of 0.25 euro per kWh (excl. VAT) after 30 minutes.

• Charging fee of 0.40 euro per kWh (excl. VAT) after 60 minutes.

For a charging session with a duration of 40 minutes where 5 kWh are charged during the first 30 minutes and another 1.2 kWh in

the remaining 10 minutes of the session, this tariff will result in costs of 0.30 euro (excl. VAT). The costs are composed of the

following components:

• 5 kWh for free: 0.00 euro

• 1.2 kWh at 0.25/kWh: 0.30 euro

OCPI 2.2-d2

127

{

"country_code": "DE",

"party_id": "ALL",

"id": "2",

"currency": "EUR",

"type": "REGULAR",

"elements": [{

"price_components": [{

"type": "ENERGY",

"price": 0.00,

"vat": 20.0,

"step_size": 1

}],

"restrictions": {

"max_duration": 1800

}

}, {

"price_components": [{

"type": "ENERGY",

"price": 0.25,

"vat": 20.0,

"step_size": 1

}],

"restrictions": {

"max_duration": 3600

}

}, {

"price_components": [{

"type": "ENERGY",

"price": 0.40,

"vat": 20.0,

"step_size": 1

}]

}],

"last_updated": "2018-12-05T13:12:44Z"

}

11.4.7. TariffType enum

Value Description

AD_HOC_PAYMENT Used to describe that a Tariff is valid when ad-hoc payment is used at the Charge Point (for

example: Debit or Credit card payment terminal).

PROFILE_CHEAP Used to describe that a Tariff is valid when Charging Preference: CHEAP is set for the session.

PROFILE_FAST Used to describe that a Tariff is valid when Charging Preference: FAST is set for the session.

PROFILE_GREEN Used to describe that a Tariff is valid when Charging Preference: GREEN is set for the session.

REGULAR Used to describe that a Tariff is valid when using an RFID, without any Charging Preference, or

when Charging Preference: REGULAR is set for the session.

OCPI 2.2-d2

128

12. Tokens module

Module Identifier: tokens

Data owner: MSP

Type: Functional Module

The tokens module gives CPOs knowledge of the token information of an eMSP. eMSPs can push Token information to CPOs,

CPOs can build a cache of known Tokens. When a request to authorize comes from a Charge Point, the CPO can check against

this cache. With this cached information they know to which eMSP they can later send a CDR.

12.1. Flow and Lifecycle

12.1.1. Push model

When the eMSP creates a new Token object they push it to the CPO by calling PUT on the CPO’s Tokens endpoint with the newly

created Token object.

Any changes to Token in the eMSP system are sent to the CPO system by calling either the PUT or the PATCH on the CPO’s

Tokens endpoint with the updated Token(s).

When the eMSP invalidates a Token (deleting is not possible), the eMSP will send the updated Token (with the field: valid set to

false, by calling, either the PUT or the PATCH on the CPO’s Tokens endpoint with the updated Token.

When the eMSP is not sure about the state or existence of a Token object in the CPO system, the eMSP can call the GET to

validate the Token object in the CPO system.

12.1.2. Pull model

When a CPO is not sure about the state of the list of known Tokens, or wants to request the full list as a start-up of their system, the

CPO can call the GET on the eMSP’s Token endpoint to receive all Tokens, updating already known Tokens and adding new

received Tokens to it own list of Tokens. This is not intended for real-time operation, requesting the full list of tokens for every

authorization will put to much strain on systems. It is intended for getting in-sync with the server, or to get a list of all tokens (from a

server without Push mode) every X hours.

12.1.3. Real-time authorization

An eMSP might want their Tokens to be authorized 'real-time', not white-listed. For this the eMSP has to implement the POST

Authorize request and set the Token.whitelist field to NEVER for Tokens they want to have authorized 'real-time'.

If an eMSP doesn’t want real-time authorization, the POST Authorize request doesn’t have to be implemented as long as all their

Tokens have Token.whitelist set to ALWAYS.

When an eMSP does not want to Push the full list of tokens to CPOs, the CPOs will need to call the POST Authorize request to

check if a Token is known by the eMSP, and if it is valid.

NOTE

Doing real-time authorization of RFID will mean a longer delay of the authorization process, which might result in

bad user experience at the Charge Point. So care should be taken to keep delays in processing the request to an

absolute minimum.

NOTE

Real-time authorization might be asked for a charging location that is not published via the Location module,

typically a private charger. In most cases this is expected to result in: ALLOWED.

OCPI 2.2-d2

129

NOTE

If real-time authorization is asked for a location, the eMSP SHALL NOT validate that charging is possible based

on information like opening hours or EVSE status etc, this information might not be update to date.

12.2. Interfaces and endpoints

There is both a Sender and a Receiver interface for Tokens. It is advised to use the Push direction from Sender to Receiver during

normal operation. The Sender interface is meant to be used when the Receiver is not 100% sure the Token cache is still correct.

12.2.1. Receiver Interface

Typically implemented by market roles like: CPO.

With this interface the Sender can push the Token information to the Receiver. Tokens is a Client Owned Object, so the end-points

need to contain the required extra fields: {party_id} and {country_code}.

Endpoint structure definition:

{token_endpoint_url}{country_code}/{party_id}/{token_uid}[?type={type}]

Example:

https://www.server.com/ocpi/cpo/2.2/tokens/NL/TNM/012345678

Method Description

GET Retrieve a Token as it is stored in the CPO system.

POST n/a

PUT Push new/updated Token object to the CPO.

PATCH Notify the CPO of partial updates to a Token.

DELETE n/a, (Use PUT, Tokens cannot be removed).

12.2.1.1. GET Method

If the eMSP wants to check the status of a Token in the CPO system it might GET the object from the CPO system for validation

purposes. The eMSP is the owner of the objects, so it would be illogical if the CPO system had a different status or was missing an

object.

Request Parameters

The following parameters: country_code, party_id, token_uid have to be provided as URL segments.

The parameter: type may be provided as an URL parameter

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the eMSP requesting this GET from the CPO system.

party_id CiString(3) yes Party ID (Provider ID) of the eMSP requesting this GET from the CPO system.

token_uid CiString(36) yes Token.uid of the Token object to retrieve.

type TokenType no Token.type of the Token to retrieve. Default if omitted: RFID

OCPI 2.2-d2

130

Response Data

The response contains the requested object.

Type Card. Description

Token 1 The requested Token object.

12.2.1.2. PUT Method

New or updated Token objects are pushed from the eMSP to the CPO.

Request Body

In the put request a new or updated Token object is sent.

Type Card. Description

Token 1 New or updated Token object.

Request Parameters

The following parameters: country_code, party_id, token_uid have to be provided as URL segments.

The parameter: type may be provided as an URL parameter

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the eMSP sending this PUT request to the CPO system. This

SHALL be the same value as the country_code in the `Token object being

pushed.

party_id CiString(3) yes Party ID (Provider ID) of the eMSP sending this PUT request to the CPO

system. This SHALL be the same value as the party_id in the Token object

being pushed.

token_uid CiString(36) yes Token.uid of the (new) Token object (to replace).

type TokenType no Token.type of the Token of the (new) Token object (to replace). Default if omitted:

RFID

Example: put a new Token

PUT To URL: https://www.server.com/ocpi/cpo/2.2/tokens/NL/TNM/012345678

{

"country_code": "DE",

"party_id": "TNM",

"uid": "012345678",

"type": "RFID",

"contract_id": "DE8ACC12E46L89",

"visual_number": "DF000-2001-8999-1",

"issuer": "TheNewMotion",

"group_id": "DF000-2001-8999",

"valid": true,

"whitelist": "ALWAYS",

"last_updated": "2015-06-29T22:39:09Z"

}

OCPI 2.2-d2

131

12.2.1.3. PATCH Method

Same as the PUT method, but only the fields/objects that have to be updated have to be present, other fields/objects that are not

specified are considered unchanged.

Any request to the PATCH method SHALL contain the last_updated field.

Example: invalidate a Token

PATCH To URL: https://www.server.com/ocpi/cpo/2.2/tokens/NL/TNM/012345678

{

"valid": false,

"last_updated": "2019-06-19T02:11:11Z"

}

12.2.2. Sender Interface

Typically implemented by market roles like: eMSP.

This interface enables the Receiver to request the current list of Tokens, when needed. Via the POST method it is possible to

authorize a single token.

Method Description

GET Get the list of known Tokens, last updated between the {date_from} and {date_to} (paginated)

POST Real-time authorization request

PUT n/a

PATCH n/a

DELETE n/a

12.2.2.1. GET Method

Fetch information about Tokens known in the eMSP systems.

Endpoint structure definition:

{tokens_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={limi

t}]

Examples:

https://www.server.com/ocpi/emsp/2.2/tokens/?date_from=2019-01-28T12:00:00&date_to=2019-01-

29T12:00:00

https://ocpi.server.com/2.2/tokens/?offset=50

https://www.server.com/ocpi/2.2/tokens/?date_from=2019-01-29T12:00:00&limit=100

https://www.server.com/ocpi/emsp/2.2/tokens/?offset=50&limit=100

Request Parameters

If additional parameters: {date_from} and/or {date_to} are provided, only Tokens with (last_updated) between the given

{date_from} (including) and {date_to} (excluding) will be returned.

OCPI 2.2-d2

132

This request is paginated, it supports the pagination related URL parameters. This request is paginated, it supports the pagination

related URL parameters.

Parameter Datatype Requi

red

Description

date_from DateTime no Only return Tokens that have last_updated after or equal to this Date/Time

(inclusive).

date_to DateTime no Only return Tokens that have last_updated up to this Date/Time, but not

including (exclusive).

offset int no The offset of the first object returned. Default is 0.

limit int no Maximum number of objects to GET.

Response Data

The endpoint response with list of valid Token objects, the header will contain the pagination related headers.

Any older information that is not specified in the response is considered as no longer valid. Each object must contain all required

fields. Fields that are not specified may be considered as null values.

Type Card. Description

Token * List of all tokens.

12.2.2.2. POST Method

Do a 'real-time' authorization request to the eMSP system, validating if a Token might be used (at the optionally given Location).

Endpoint structure definition:

{tokens_endpoint_url}{token_uid}/authorize[?type={type}]

The /authorize is required for the real-time authorize request.

Examples:

https://www.server.com/ocpi/emsp/2.2/tokens/012345678/authorize

https://ocpi.server.com/2.2/tokens/012345678/authorize?type=RFID

When the eMSP does not know the Token, the eMSP SHALL respond with an HTTP status code: 404 (Not Found).

When the eMSP receives a 'real-time' authorization request from a CPO that contains too little information (no LocationReferences

provided) to determine if the Token might be used, the eMSP SHALL respond with the OCPI status: 2002

Request Parameters

The parameter: token_uid has to be provided as URL segments.

The parameter: type may be provided as an URL parameter

Parameter Datatype Requi

red

Description

token_uid CiString(36) yes Token.uid of the Token for which authorization is requested.

OCPI 2.2-d2

133

Parameter Datatype Requi

red

Description

type TokenType no Token.type of the Token for which this authorization is. Default if omitted: RFID

Request Body

In the body an optional LocationReferences object can be given. The eMSP SHALL then validate if the Token is allowed to be used

at this Location, and if applicable: which of the Locations EVSEs. The object with valid Location and EVSEs will be returned in the

response.

Type Card. Description

LocationReferences ? Location and EVSEs for which the Token is requested to be authorized.

Response Data

When the token is known by the Sender, the response SHALL contain a AuthorizationInfo object.

If the token is not known, the response SHALL contain the status code: 2004: Unknown Token, and no data field.

Type Card. Description

AuthorizationInfo 1 Contains information about the authorization, if the Token is allowed to charge and

optionally which EVSEs are allowed to be used.

12.3. Object description

12.3.1. AuthorizationInfo Object

Property Type Card. Description

allowed AllowedType 1 Status of the Token, and whether charging is allowed at the optionally

given location.

token Token 1 The complete Token object for which this authorization was requested.

location LocationRefer

ences

? Optional reference to the location if it was included in the request, and if

the EV driver is allowed to charge at that location. Only the EVSEs the

EV driver is allowed to charge at are returned.

authorization_reference CiString(36) ? Reference to the authorization given by the eMSP, when given, this

reference will be provided in the relevant Session and/or CDR.

info DisplayText ? Optional display text, additional information to the EV driver.

12.3.2. Token Object

Property Type Card. Description

country_code CiString(2) 1 ISO-3166 alpha-2 country code of the MSP that 'owns' this Token.

party_id CiString(3) 1 CPO ID of the MSP that 'owns' this Token (following the ISO-15118 standard).

OCPI 2.2-d2

134

Property Type Card. Description

uid CiString(36) 1 Unique ID by which this Token can be identified.

This is the field used by CPO system (RFID reader on the Charge Point) to

identify this token.

Currently, in most cases: type=RFID, this is the RFID hidden ID as read by the

RFID reader, but that is not a requirement.

If this is a APP_USER or AD_HOC_USER Token, it will be a uniquely, by the eMSP,

generated ID.

This field is named uid instead of id to prevent confusion with: contract_id.

type TokenType 1 Type of the token

contract_id CiString(36) 1 Uniquely identifies the EV Driver contract token within the eMSP’s platform (and

suboperator platforms). Recommended to follow the specification for eMA ID

from "eMI3 standard version V1.0" (http://emi3group.com/documents-links/)

"Part 2: business objects."

visual_number string(64) ? Visual readable number/identification as printed on the Token (RFID card), might

be equal to the contract_id.

issuer string(64) 1 Issuing company, most of the times the name of the company printed on the

token (RFID card), not necessarily the eMSP.

group_id CiString(36) ? This ID groups a couple of tokens. This can be used to make two or more

tokens work as one, so that a session can be started with one token and

stopped with another, handy when a card and key-fob are given to the EV-driver.

Beware that OCPP 1.5/1.6 only support group_ids (it is called parentId in OCPP

1.5/1.6) with a maximum length of 20.

valid boolean 1 Is this Token valid

whitelist WhitelistType 1 Indicates what type of white-listing is allowed.

language string(2) ? Language Code ISO 639-1. This optional field indicates the Token owner’s

preferred interface language. If the language is not provided or not supported

then the CPO is free to choose its own language.

default_profile_type ProfileType ? The default Charging Preference. When this is provided, and a charging session

is started on an Charge Point that support Preference base Smart Charging and

support this ProfileType, the Charge Point can start using this ProfileType,

without this having to be set via: Set Charging Preferences.

energy_contract EnergyContra

? When the Charge Point supports using your own energy supplier/contract at a

Charge Point, information about the energy supplier/contract is needed so the

CPO knows which energy supplier to use.

NOTE: In a lot of countries it is currently not allowed/possible to use a drivers

own energy supplier/contract at a Charge Point.

last_updated DateTime 1 Timestamp when this Token was last updated (or created).

The combination of uid and type should be unique for every token within the eMSP’s system.

NOTE

OCPP supports group_id (or ParentID as it is called in OCPP 1.5/1.6) OCPP 1.5/1.6 only support group ID’s with

maximum length of string(20), case insensitive. As long as EV-driver can be expected to charge at an OCPP

1.5/1.6 Charge Point, it is adviced to not used a group_id longer then 20.

OCPI 2.2-d2

135

12.3.2.1. Examples

Simple APP_USER example

{

"country_code": "DE",

"party_id": "TNM",

"uid": "bdf21bce-fc97-11e8-8eb2-f2801f1b9fd1",

"type": "APP_USER",

"contract_id": "DE8ACC12E46L89",

"issuer": "TheNewMotion",

"valid": true,

"whitelist": "ALLOWED",

"last_updated": "2018-12-10T17:16:15Z"

}

Full RFID example

{

"country_code": "DE",

"party_id": "TNM",

"uid": "12345678905880",

"type": "RFID",

"contract_id": "DE8ACC12E46L89",

"visual_number": "DF000-2001-8999-1",

"issuer": "TheNewMotion",

"group_id": "DF000-2001-8999",

"valid": true,

"whitelist": "ALLOWED",

"language": "it",

"default_profile_type": "GREEN",

"energy_contract": {

"supplier_name": "Greenpeace Energy eG",

"contract_id": "0123456789"

"last_updated": "2018-12-10T17:25:10Z"

}

12.4. Data types

12.4.1. AllowedType enum

Value Description

ALLOWED This Token is allowed to charge (at this location).

BLOCKED This Token is blocked.

EXPIRED This Token has expired.

NO_CREDIT This Token belongs to an account that has not enough credits to charge (at the given location).

NOT_ALLOWED Token is valid, but is not allowed to charge at the given location.

12.4.2. EnergyContract class

Information about a energy contract that belongs to a Token so a driver could use his/her own energy contract when charging at a

Charge Point.

OCPI 2.2-d2

136

Property Type Card. Description

supplier_name string(64) 1 Name of the energy supplier for this token.

contract_id string(64) ? Contract ID at the energy supplier, that belongs to the owner of this token.

12.4.3. LocationReferences class

References to location details.

Property Type Card. Description

location_id CiString(36) 1 Unique identifier for the location.

evse_uids CiString(36) * Unique identifiers for EVSEs within the CPO’s platform for the EVSE within the

given location.

12.4.4. TokenType enum

Value Description

AD_HOC_USER One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a

customer, probably an app user.

APP_USER Token ID generated by a server (or App.) to identify a user of an App. The same user uses the

same Token for every Session.

OTHER Other type of token

RFID RFID Token

NOTE

The eMSP is RECOMMENDED to push Tokens with type: AD_HOC_USER or APP_USER with whitelist set to

NEVER. Whitelists are very useful for RFID type Tokens, but the AD_HOC_USER/APP_USER Tokens are used to

start Sessions from an App etc. so whitelisting them has no advantages.

12.4.5. WhitelistType enum

Defines when authorization of a Token by the CPO is allowed.

The validity of a Token has no influence on this. If a Token is: valid = false, when the whitelist field requires real-time

authorization, the CPO SHALL do a real-time authorization, the state of the Token might have changed.

Value Description

ALWAYS Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall

always allow any use of this Token.

ALLOWED It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose

which version of authorization to use.

ALLOWED_OFFLINE In normal situations realtime authorization shall be used. But when the CPO cannot get a response

from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token

to be used.

NEVER Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime

authorization for any use of this Token to the eMSP.

OCPI 2.2-d2

137

13. Commands module

Module Identifier: commands

Type: Functional Module

The Commands module enables remote commands to be sent to a Location/EVSE. The following commands are supported:

•

RESERVE_NOW

•

CANCEL_RESERVATION

•

START_SESSION

•

STOP_SESSION

•

UNLOCK_CONNECTOR

See CommandType for a description of the different commands. Use the UNLOCK_CONNECTOR command with care, please read

the note at CommandType.

Module dependency: Locations module, Sessions module

13.1. Flow

With the Commands module, commands can be sent from the eMSP, via the CPO to a Charge Point. Most Charge Point are

hooked up to the internet via a relative slow wireless connection. To prevent long blocking calls, the commands module is designed

to work asynchronously.

The Sender (typically eMSP) send a request to a Receiver (typically CPO), via the Receivers Commands interface. The Receiver

checks if it can send the request to a Charge Point and will respond to the request with a status, indicating if the request can be

sent to a Charge Point.

The Receiver (typically CPO) sends the requested command (via another protocol, for example: OCPP) to a Charge Point. The

Charge Point will respond if it understands the command and will try to execute the command. This response doesn’t always mean

that the command was executed successfully. The Receiver (typically CPO) will forward the result in a new POST request to the

Senders Commands interface.

The following examples try to give insight into the message flow and the asynchronous nature of the OCPI Commands.

Example of a START_SESSION that is accepted, but no new Session is started because EV not plugged in before end of time-out.

This is an example for Charge Point that allows a remote start when the cable is not yet plugged in. Some Charge Points even

require this, there might, for example, be a latch in front of the socket to prevent vandalism.

eMSP

CPO

Charge Point

Command(START_SESSION, location_id=1234, token=200)

status_code = 1000, data: {CommandResponse { result = ACCEPTED }}

RemoteStartTransaction.req(Token=200)

RemoteStartTransaction.conf(Accepted)

CommandResult(result = FAILED)

EV NOT Plugged in before time-out

Figure 28. START_SESSION failed

Example of a START_SESSION that is accepted, but no new Session is started because the EV is not plugged in, and this Charge

Point does not allow a remote start without a cable already being plugged in.

OCPI 2.2-d2

138

eMSP

CPO

Charge Point

EV NOT Plugged in

Command(START_SESSION, location_id=1234, token=200)

status_code = 1000, data: {CommandResponse { result = ACCEPTED }}

RemoteStartTransaction.req(Token=200)

RemoteStartTransaction.conf(Rejected)

CommandResult(result = FAILED)

Figure 29. START_SESSION failed

Example of a START_SESSION that is accepted and results in a new Session.

eMSP

CPO

Charge Point

Command(START_SESSION, location_id=1234,

token.uid=200, token.type=AD_HOC_USER,

token.authorization_reference=567890)

status_code = 1000, data: {CommandResponse { result = ACCEPTED }}

RemoteStartTransaction.req(Token=200)

RemoteStartTransaction.conf(Accepted)

CommandResult(result = ACCEPTED)

opt

Authorize.req(Token=200)

Authorize.conf(Accepted)

EV Plugged in

StartTransaction.req(Token=200)

StartTransaction.conf(TransactionId=15)

Session(id=15, token=200, location_id=1234

authorization_reference=567890)

Figure 30. START_SESSION successful

Example of a START_SESSION with a Token that is Whitelist: NEVER.

The CPO does not check the Token in the START_SESSION. If needed, the Charge Point does an OCPP Authorize request. In

case of a Token whitelist NEVER or ALLOWED_OFFLINE, the CPO does an realtime authorization.

OCPI 2.2-d2

139

eMSP

CPO

Charge Point

EV Plugged in

Command(START_SESSION, location_id=1234, token.uid=123,

token.type=APP_USER, token.whitelist=NEVER,

token.authorization_reference=567890)

status_code = 1000, data: {CommandResponse { result = ACCEPTED }}

RemoteStartTransaction.req(Token=123)

RemoteStartTransaction.conf(Accepted)

CommandResult(result = ACCEPTED)

opt

Authorize.req(Token=123)

Authorize.conf(Accepted)

StartTransaction.req(Token=123)

StartTransaction.conf(TransactionId=15)

Session(id=15, token=123, location_id=1234,

authorization_reference=567890)

Figure 31. START_SESSION whitelist NEVER

Example of a UNLOCK_CONNECTOR that fails because the Location is not known by the CPO.

eMSP

CPO

Command(UNLOCK_CONNECTOR, location_id=1234, evse_uid=1234, connector=1)

status_code = 2003, data: {CommandResponse { result = REJECTED }}

2003 = Unknown Location

Figure 32. UNLOCK_CONNECTOR Unknown Location

Example of a RESERVE_NOW that is rejected by the Charge Point.

eMSP

CPO

Charge Point

Command(RESERVE_NOW, location_id=1234, token=200, reservationId=ABC123)

status_code = 1000, data: {CommandResponse { result = ACCEPTED }}

ReserveNow.req(idTag=200, reservationId=456)

ReserveNow.conf(Rejected)

CommandResult(result = REJECTED)

Figure 33. RESERVE_NOW rejected by Charge Point

Example of a successful RESERVE_NOW.

OCPI 2.2-d2

140

eMSP

CPO

Charge Point

Command(RESERVE_NOW, location_id=1234, token=200,

reservationId=ABC123,

response_url=https://server.com/reservation/ABC123)

status_code = 1000, data: {CommandResponse { result = ACCEPTED }}

ReserveNow.req(idTag=200, reservationId=456)

ReserveNow.conf(Accepted)

POST: https://server.com/reservation/ABC123

CommandResult(result = ACCEPTED)

Figure 34. Successful RESERVE_NOW

Reservation canceled by the CPO.

OCPI makes it possible for a CPO to cancel a reservation. This is not to be taken lightly. When a driver makes a reservation of a

Charge Point/EVSE, he/she wants to be sure to have a charging location. So if the CPO cancel the reservation, the driver will for

sure not like it. But there are some circumstances where the CPO is forced to cancel a reservation. For example: Charge Point has

become defect, or the CPO is notified of ongoing roadworks which makes the Charge Point unreachable etc.

To Cancel a reservation the CPO call the Senders interface with the same URL as was given by the Sender (eMSP) when the

RESERVE_NOW command was send.

The sequence diagram below continues after the sequence diagram above.

eMSP

CPO

Problem with Location 1234

POST: https://server.com/reservation/ABC123

CommandResult(result = CANCELED_RESERVATION)

Figure 35. Reservation canceled by the CPO

_These examples use OCPP 1.6 based commands between CPO and Charge Point, but that is not a requirement for OCPI.

If the Sender (typically eMSP) wants to have a reference between the calls send to the Receivers interface and the asynchronous

result received from the Charge Point via the CPO, the Sender can make some unique identifier part of the`response_url` that is

part of every method in the Receiver interface. The Receiver will call this URL when the result is received from the Charge Point.

The Sender can then match the unique identifier from the URL called with the request.

13.2. Interfaces and endpoints

The commands module consists of two interfaces: a Receiver interface that enables a Sender (typically eMSP) (and its clients) to

send commands to a Location/EVSE and an Sender interface to receive the response from the Location/EVSE asynchronously.

13.2.1. Receiver Interface

Typically implemented by market roles like: CPO.

Endpoint structure definition:

{commands_endpoint_url}{command}

Examples:

OCPI 2.2-d2

141

https://www.server.com/ocpi/cpo/2.2/commands/START_SESSION

https://ocpi.server.com/commands/STOP_SESSION

https://server.com/ocpi/cpo/2.2/commands/RESERVE_NOW

Example endpoint structure: ``

Method Description

GET n/a

POST Send a command to the CPO, requesting the CPO to send the command to the Charge Point

PUT n/a

PATCH n/a

DELETE n/a

13.2.1.1. POST Method

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

command CommandTyp

yes Type of command that is requested.

13.2.1.2. Request Body

Depending on the command parameter the body SHALL contain the applicable object for that command.

Type Card. Description

Choice: one of five

> CancelReservation 1 CancelReservation object, for the CANCEL_RESERVATION command, with information

needed to cancel an existing reservation.

> ReserveNow 1 ReserveNow object, for the RESERVE_NOW command, with information needed to reserve

a (specific) connector of a Charge Point for a given Token.

> StartSession 1 StartSession object, for the START_SESSION command, with information needed to start a

sessions.

> StopSession 1 StopSession object, for the STOP_SESSION command, with information needed to stop a

sessions.

> UnlockConnector 1 UnlockConnector object, for the UNLOCK_CONNECTOR command, with information needed

to unlock a connector of a Charge Point.

Response Data

The response contains the direct response from the Receiver, not the response from the Charge Point itself, that will be sent via an

OCPI 2.2-d2

142

asynchronous POST on the Sender interface if this response is ACCEPTED.

Datatype Card. Description

CommandResponse 1 Result of the command request, by the CPO (not the Charge Point). So this indicates if the

CPO understood the command request and was able to send it to the Charge Point. This is

not the response by the Charge Point

13.2.2. Sender Interface

Typically implemented by market roles like: eMSP.

The Sender interface receives the asynchronous responses.

Endpoint structure definition:

No structure defined. This is open to the Sender to define, the URL is provided to the Receiver by the Sender in the POST to the

Receiver interface. Therefor OCPI does not define variables.

Example:

https://www.server.com/ocpi/emsp/2.2/commands/{command}

https://ocpi.server.com/commands/{command}/{uid}

Method Description

GET n/a

POST Receive the asynchronous response from the Charge Point.

PUT n/a

PATCH n/a

DELETE n/a

13.2.2.1. POST Method

Endpoint structure definition:

It is up to the implementation of the eMSP to determine what parameters are put in the URL. The eMSP sends a URL in the POST

method body to the CPO. The CPO is required to use this URL for the asynchronous response by the Charge Point. It is advised to

make this URL unique for every request to differentiate simultaneous commands, for example by adding a unique id as a URL

segment.

Examples:

https://www.server.com/ocpi/emsp/2.2/commands/RESERVE_NOW/1234

https://www.server.com/ocpi/emsp/2.2/commands/UNLOCK_CONNECTOR/2

13.2.2.2. Request Body

Datatype Card. Description

CommandResult 1 Result of the command request, from the Charge Point.

OCPI 2.2-d2

143

13.3. Object description

13.3.1. CancelReservation Object

With CancelReservation the Sender can request the Cancel of an existing Reservation. The CancelReservation needs to contain

the reservation_id that was given by the Sender to the ReserveNow.

As there might be cost involved for a Reservation, canceling a reservation might still result in a CDR being send for the reservation.

Property Type Card. Description

response_url URL 1 URL that the CommandResult POST should be send to. This URL might contain

an unique ID to be able to distinguish between CancelReservation requests.

reservation_id CiString(36) 1 Reservation id, unique for this reservation. If the Charge Point already has a

reservation that matches this reservationId the Charge Point will replace the

reservation.

13.3.2. CommandResponse Object

The CommandResponse object is send in the HTTP response body.

Because OCPI does not allow/require retries, it could happen that the asynchronous result url given by the eMSP is never

successfully called. The eMSP might have had a glitch, HTTP 500 returned, was offline for a moment etc. For the eMSP to be able

to give a quick as possible response to another system or driver app. it is important for the eMSP to known the timeout on a certain

command.

Property Type Card. Description

result CommandResponseType 1 Response from the CPO on the command request.

timeout int 1 Timeout for this command in seconds. When the Result is not received

within this timeout, the eMSP can assume that the message might never be

send.

message DisplayText * Human-readable description of the result (if one can be provided), multiple

languages can be provided.

13.3.3. CommandResult Object

Property Type Card. Description

result CommandResultType 1 Result of the command request as sent by the Charge Point to the CPO.

message DisplayText * Human-readable description of the reason (if one can be provided),

multiple languages can be provided.

13.3.4. ReserveNow Object

The evse_uid is optional. If no EVSE is specified, the Charge Point should keep one EVSE available for the EV Driver identified

by the given Token. (This might not be supported by all Charge Points). A reservation can be replaced/updated by sending a

RESERVE_NOW request with the same Location (Charge Point) and the same reservation_id.

A successful reservation will result in a new Session object being created by the CPO.

OCPI 2.2-d2

144

A not used Reservation of a Charge Point/EVSE MAY result in cost being made, thus also a CDR.

The eMSP provides a Token that has to be used by the Charge Point. The Token provided by the eMSP for the ReserveNow

SHALL be authorized by the eMSP before sending it to the CPO. Therefor the CPO SHALL NOT check the validity of the Token

provided before sending the request to the Charge Point.

If this is an OCPP Charge Point, the Charge Point decides if it needs to validate the given Token, in such case:

• If this Token is of type: AD_HOC_USER or APP_USER the CPO SHALL NOT do a realtime authorization at the eMSP for this .

• If this Token is of type: RFID, the CPO SHALL NOT do a realtime authorization at the eMSP for this Token at the given

EVSE/Charge Point within 15 minutes after having received this ReserveNow.

The eMSP MAY use Tokens that have not been pushed via the Token module, especially AD_HOC_USER or APP_USER Tokens are

only used by commands send by an eMSP. As these are never used locally at the Charge Point like RFID.

Unknown Tokens received by the CPO in the ReserveNow Object don’t need to be stored in the Token module. In other words,

when a Token has been received via ReserveNow, the same Token does not have to be returned in a Token GET request from the

eMSP.

An eMSP sending a ReserveNow SHALL only use Token that are owned by this eMSP in ReserveNow, using Tokens of other

eMSPs is not allowed.

The reservation_id send by the Sender (eMSP) to the Receiver (CPO) SHALL NOT be send directly to a Charge Point. The

CPO SHALL make sure the Reservation ID send to the Charge Point is unique, is not used by another Sender (eMSP). We don’t

want a Sender (eMSP) to replace or cancel a reservation of another Sender (eMSP).

Property Type Card. Description

response_url URL 1 URL that the CommandResult POST should be send to. This URL might

contain an unique ID to be able to distinguish between ReserveNow

requests.

token Token 1 Token object for how to reserve this Charge Point (and specific EVSE).

expiry_date DateTime 1 The Date/Time when this reservation ends, in UTC.

reservation_id CiString(36) 1 Reservation id, unique for this reservation. If the Receiver (typically

CPO) Point already has a reservation that matches this reservationId for

that Location it will replace the reservation.

location_id CiString(36) 1 Location.id of the Location (belonging to the CPO this request is send

to) for which to reserve an EVSE.

evse_uid CiString(36) ? Optional EVSE.uid of the EVSE of this Location if a specific EVSE has

to be reserved.

authorization_reference CiString(36) ? Reference to the authorization given by the eMSP, when given, this

reference will be provided in the relevant Session and/or CDR.

13.3.5. StartSession Object

The evse_uid is optional. If no EVSE is specified, the Charge Point can itself decide on which EVSE to start a new session. (this

might not be supported by all Charge Points).

The eMSP provides a Token that has to be used by the Charge Point. The Token provided by the eMSP for the StartSession

SHALL be authorized by the eMSP before sending it to the CPO. Therefor the CPO SHALL NOT check the validity of the Token

provided before sending the request to the Charge Point.

If this is an OCPP Charge Point, the Charge Point decides if it needs to validate the given Token, in such case:

OCPI 2.2-d2

145

• If this Token is of type: AD_HOC_USER or APP_USER the CPO SHALL NOT do a realtime authorization at the eMSP for this .

• If this Token is of type: RFID, the CPO SHALL NOT do a realtime authorization at the eMSP for this Token at the given

EVSE/Charge Point within 15 minutes after having received this StartSession. (This means that if the driver decided to

use his RFID within 15 minutes at the same Charge Point, because the app is not working somehow, the RFID is already

authorized)

The eMSP MAY use Tokens that have not been pushed via the Token module, especially AD_HOC_USER or APP_USER Tokens are

only used by commands send by an eMSP. As these are never used locally at the Charge Point like RFID.

Unknown Tokens received by the CPO in the StartSession Object don’t need to be stored in the Token module. In other words,

when a Token has been received via StartSession, the same Token does not have to be returned in a Token GET request from

the eMSP. However, the information of the Token SHALL be put in the Session and CDR.

An eMSP sending a StartSession SHALL only use Token that are owned by this eMSP in StartSession, using Tokens of

other eMSPs is not allowed.

Property Type Card. Description

response_url URL 1 URL that the CommandResult POST should be sent to. This URL might

contain an unique ID to be able to distinguish between StartSession

requests.

token Token 1 Token object the Charge Point has to use to start a new session. The

Token provided in this request is authorized by the eMSP.

location_id CiString(36) 1 Location.id of the Location (belonging to the CPO this request is send

to) on which a session is to be started.

evse_uid CiString(36) ? Optional EVSE.uid of the EVSE of this Location on which a session is to

be started.

authorization_reference CiString(36) ? Reference to the authorization given by the eMSP, when given, this

reference will be provided in the relevant Session and/or CDR.

NOTE

In case of an OCPP 1.x Charge Point, the EVSE ID should be mapped to the connector ID of a Charge Point.

OCPP 1.x does not have good support for Charge Points that have multiple connectors per EVSE. To make

StartSession over OCPI work, the CPO SHOULD present the different connectors of an EVSE as separate

EVSE, as is also written by the OCA in the application note: "Multiple Connectors per EVSE in a OCPP 1.x

implementation".

13.3.6. StopSession Object

Property Type Card. Description

response_url URL 1 URL that the CommandResult POST should be sent to. This URL might contain

an unique ID to be able to distinguish between StopSession requests.

session_id CiString(36) 1 Session.id of the Session that is requested to be stopped.

13.3.7. UnlockConnector Object

Property Type Card. Description

response_url URL 1 URL that the CommandResult POST should be sent to. This URL might contain

an unique ID to be able to distinguish between UnlockConnector requests.

OCPI 2.2-d2

146

Property Type Card. Description

location_id CiString(36) 1 Location.id of the Location (belonging to the CPO this request is send to) of

which it is requested to unlock the connector.

evse_uid CiString(36) 1 EVSE.uid of the EVSE of this Location of which it is requested to unlock the

connector.

connector_id CiString(36) 1 Connector.id of the Connector of this Location of which it is requested to unlock.

13.4. Data types

13.4.1. CommandResponseType enum

Response to the command request from the eMSP to the CPO.

Value Description

NOT_SUPPORTED The requested command is not supported by this CPO, Charge Point, EVSE etc.

REJECTED Command request rejected by the CPO. (Session might not be from a customer of the eMSP that

send this request)

ACCEPTED Command request accepted by the CPO.

UNKNOWN_SESSION The Session in the requested command is not known by this CPO.

13.4.2. CommandResultType enum

Result of the command that was send to the Charge Point.

Value Description

ACCEPTED Command request accepted by the Charge Point.

CANCELED_RESERVATION The Reservation has been canceled by the CPO.

EVSE_OCCUPIED EVSE is currently occupied, another session is ongoing. Cannot start a new session

EVSE_INOPERATIVE EVSE is currently inoperative or faulted.

FAILED Execution of the command failed at the Charge Point.

NOT_SUPPORTED The requested command is not supported by this Charge Point, EVSE etc.

REJECTED Command request rejected by the Charge Point.

TIMEOUT Command request timeout, no response received from the Charge Point in a reasonable

time.

UNKNOWN_RESERVATION The Reservation in the requested command is not known by this Charge Point.

13.4.3. CommandType enum

The command requested.

OCPI 2.2-d2

147

Value Description

CANCEL_RESERVATION Request the Charge Point to cancel a specific reservation.

RESERVE_NOW Request the Charge Point to reserve a (specific) EVSE for a Token for a certain time, starting now.

START_SESSION Request the Charge Point to start a transaction on the given EVSE/Connector.

STOP_SESSION Request the Charge Point to stop an ongoing session.

UNLOCK_CONNECTOR Request the Charge Point to unlock the connector (if applicable). This functionality is for help desk

operators only!

The command UNLOCK_CONNECTOR may only be used by an operator or the eMSP. This command SHALL never be allowed

to be sent directly by the EV-Driver. The UNLOCK_CONNECTOR is intended to be used in the rare situation that the connector

is not unlocked successfully after a transaction is stopped. The mechanical unlock of the lock mechanism might get

stuck, for example: fail when there is tension on the charging cable when the Charge Point tries to unlock the connector.

In such a situation the EV-Driver can call either the CPO or the eMSP to retry the unlocking.

OCPI 2.2-d2

148

14. ChargingProfiles module

Module Identifier: chargingprofiles

Type: Functional Module

With the ChargingProfiles module, parties (SCSP but also MSPs) can send (Smart) Charging Profiles to a Location/EVSE. It is also

possible to request the 'ActiveChargingProfile' from a Location/EVSE.

The ActiveChargingProfile is the charging profile as calculated by the EVSE. It is the result of the calculation of all smart charging

inputs present in the EVSE, also Local Limits might be taken into account.

The ChargingProfile is similar to the concept of Charging Profiles in OCPP, but exposes this functionality to third parties. These

objects and the accompanying interfaces make certain abstractions that make them more suitable for energy parties to signal their

intent. The data structures are base on OCPP 1.6 and 2.0 to make conversion of messages between OCPI and OCPP easy.

NOTE

Charging Profiles set via this module are no guarantee that the EV will charge with the exact given limit, it is a

maximum limit, not a target. A lot of factors influence the charging speed. The EV might not take the amount of

energy that the EVSE is willing to provide to it, the battery might be too warm or almost full. A single phase cable

might be used on a three phase Charge Point. There can be local energy limits (load balancing between EVSEs

on a relative small energy connection to a group of EVSEs) that might limit the energy offered by the EVSE to the

EV even further.

ChargingProfile can be created by the owner of a Token on Sessions that belong to that token. If another party sends a

ChargingProfile and the CPO has no contract that allows that party to set profiles on sessions, the CPO is allowed to reject such

profiles.

This module can be used by the eMSP, but can also be used by another party that provide "Smart Charging Services" (Smart

Charging Service Provider (SCSP) / Aggregator / Energy Service Broker etc.) These SCSPs then depend on the CPO sending

session information to them. They need to know which session is ongoing to be able to influence it. If a SCSP uses this module,

read eMSP as SCSP.

NOTE

OCPI provides the means for SCSPs to do this. Parties doing this have to adhere to local privacy laws, have to

have setup contracts etc. Local laws might oblige explicit consent from the driver etc.

Module dependency: Sessions module

14.1. Smart Charging Topologies

There are different Smart Charging Topologies possible. Which topology can be used depends on the contracts between different

parties.

NOTE

Care has to be taken to prevent mixing the different topologies. When multiple parties start sending Charging

Profiles, the resulting charging speed might be unpredictable. In case of OCPP Charge Points, the result will be

the minimum of all the Charging Profiles, resulting in a slower than needed charging speed.

14.1.1. The eMSP generates ChargingProfiles.

The most straight forward topology, the eMSP generates ChargingProfiles for its own customers, no SCSP is involved. The eMSP

'owns' the customer, so if the eMSP knows that its customer agrees with the eMSP manipulating the charging speed, the eMSP is

free to do this.

OCPI 2.2-d2

149

eMSP

CPO

Charge Point

OCPI

Figure 36. Smart Charging Topology: The eMSP generates ChargingProfiles.

Interface Role

Sender eMSP

Receiver CPO

14.1.2. The eMSP delegated Smart Charging to SCSP.

In the topology, the eMSP has delegated the generation of ChargingProfiles to a SCSP. For this, the eMSP and SCSP have agreed

to use OCPI as the interface.

The eMSP 'owns' the customer, so if the eMSP knows that its customer agrees with the eMSP manipulating the charging speed,

the eMSP is free to do this. The eMSP can forward OCPI Session Objects to the SCSP. the SCSP can act on the received/updated

Session Objects, by sending Charging Profile commands via the eMSP to the CPO.

The eMSP and SCSP have to take into account that they have to oblige to local privacy laws when exchanging information about

eMSPs customers.

From the CPO point of view, this topology is similar to the one above, the CPO will not know the difference.

SCSP

eMSP

CPO

Charge Point

OCPI OCPI

Figure 37. Smart Charging Topology: The eMSP generates ChargingProfiles.

Connection Interface Role

SCSP - eMSP Sender SCSP

SCSP - eMSP Receiver eMSP

eMSP - CPO Sender eMSP

eMSP - CPO Receiver CPO

14.1.3. The CPO delegated Smart Charging to SCSP.

In this topology, the CPO has delegated the generation of ChargingProfiles to a SCSP. For this, the CPO and SCSP have agreed to

use OCPI as the interface.

The CPO 'owns' the EVSE on which charging happens. As the CPO does not 'own' the customers, the CPO needs to make sure

the EV driver knows that the charging speed might not be the maximum the driver has expected, this could be something as simple

as a sticker on the Charge Point, or might even be part of the tariff text.

The CPO might generate ChargingProfiles themselves, but as OCPI is then not used this is not part of this document.

The CPO can forward OCPI Session Objects to the SCSP. the SCSP can act on the received/updated Session Objects, by sending

Charging Profile commands to the CPO.

The CPO and SCSP have to take into account that they have to oblige to local privacy laws when exchanging information about

eMSPs customers.

OCPI 2.2-d2

150

In this topology, the eMSP is not aware that the CPO is using OCPI to receive Charging Profiles from the SCSP.

eMSP

SCSP

CPO

Charge Point

OCPI

Figure 38. Smart Charging Topology: The eMSP generates ChargingProfiles.

Interface Role

Sender SCSP

Receiver CPO

14.2. Use Cases

This module is designed to support the following use cases, for all the above mentioned topologies.

• The eMSP/SCSP sends/updates a ChargingProfile to manipulate an ongoing charging session.

• The eMSP/SCSP request to remove the set ChargingProfile from an ongoing charging session.

• The eMSP/SCSP request the ActiveChargingProfile for an ongoing charging session.

• The CPO updates the eMSP/SCSP of changes to an ActiveChargingProfile.

14.3. Flow

The ChargingProfile creation is a request to activate a charging profile on a running charging session.

Most Charge Points are hooked up to the internet via a relative slow wireless connection. To prevent long blocking calls, the

ChargingProfile module is designed to work asynchronously. (similar to the Commands module.

The Sender (Typically SCSP) sends a request to a Receiver (Typically CPO), via the Receiver interface. The Receiver checks if it

can send the request to a Charge Point and will respond to the request with a status, indicating if the request can be sent to a

Charge Point.

The Receiver sends the requested command (via another protocol, for example: OCPP) to a Charge Point. The Charge Point will

respond if it understands the command and will try to execute the command. This response doesn’t always mean that the

ChargingProfile will be executed. The CPO will forward the result in a new POST request to the Sender (Typically SCSP)

ChargingProfile interface.

The Sender (Typically SCSP) can send the Charging Profile to the EVSE via the CPO by using the CPO PUT method for an

ongoing session. The Sender can request the current profile the EVSE has calculated, based on different inputs, and is planned to

be used for the ongoing session by calling the CPO GET method. The Sender has the ability to remove the Charging Profile for the

session by calling the CPO DELETE method

When the Sender has (at least once) successfully sent a Charging Profile for an ongoing charging session, the Receiver (Typically

CPO) SHALL keep the Sender updated with changes to the ActiveChargingProfile of that Session. If the Receiver is aware of any

changes, he notifies the Sender by calling the MSP PUT method. The changes might be triggered by the CPO sending additional

Charging Profiles, or the some local limit being applied to the Charge Point, and the Charge Point notifies the CPO of the Changes.

The Receiver can cancel/remove an existing ChargingProfile, it can let the eMSP know by calling the MSP PUT method

For calculating optimum ChargingProfiles it might be useful for the eMSP or SCSP to know the ChargingProfile that the Charge

Point has planned for the Session: ActiveChargingProfile. The ActiveChargingProfile might differ from ChargingProfile requested via

OCPI 2.2-d2

151

OCPI. There might be other limiting factors being taken into account by the CPO and or Charge Point, that limit the ChargingProfile.

The ActiveChargingProfile profile can be requested by the Sender by calling the CPO GET method on the Charging Profile

Receiver interface. The CPO will then ask the Charge Point for the planned ActiveChargingProfile. When that is received it is

forwarded to the URL given by the eMSP or SCSP.

The CPO can limit the amount of request that can be done on the Charging Profiles interface, this too prevent creating a too high

load or data usages. To do this the CPO can reject a request on the Charging Profile Receiver interface be responding with:

TOO_OFTEN.

If the Sender (typically eMSP or SCSP) wants to have a reference between the calls send to the Receivers interface and the

asynchronous result received from the Charge Point via the CPO, the Sender can make some unique identifier part of

the`response_url` that is part of every method in the Receiver interface. The Receiver will call this URL when the result is received

from the Charge Point. The Sender can then match the unique identifier from the URL called with the request.

14.3.1. Example of setting/updating a ChargingProfile by the Sender (typically

the SCSP or eMSP)

When a new Session is started, or when an update to an existing Session is available, the CPO sends the Session object to the

eMSP or SCSP. The eMSP or SCSP calculates a Charging Profile and sends it to the CPO by calling the Charging Profiles PUT

method on the Receiver interface.

The CPO responds to the eMSP or SCSP, the response body will contain the response to the request, acknowledging the request

was understood and can be forwarded to the Charge Point.

The CPO sends the requests to the Charge Point. When the CPO receives a response from the Charge Point, that result is sent to

the eMSP or SCSP by call the POST method, on the URL provided by the eMSP of SCSP in the PUT request, this call will contain

a ChargingProfileResult Object.

Sender

eMSP or SCSP

CPO

Receiver

Charge Point

StartTransaction.req(Token=200)

StartTransaction.conf(TransactionId=15)

Session(id=15)

Calculate ChargingProfile

PUT https://server.com/ocpi/2.2/chargingprofiles/15

SetChargingProfile(response_url=https://client.com/12345)

status_code = 1000, data: {ChargingProfileResponse { result = ACCEPTED }}

SetChargingProfile.req

SetChargingProfile.conf

POST https://client.com/12345

ChargingProfileResult(result = ACCEPTED)

Figure 39. Example of a SetChargingProfile.

14.3.2. Example of a setting/updating a ChargingProfile by the SCSP via the

eMSP

When a new Session is started, the CPO sends the Session object to the eMSP, the eMSP forwards the Session object to the

SCSP.

When a new Session is started, or when an update to an existing Session is available, the CPO sends the Session object to the

eMSP. The eMSP forwards the Session Object to the SCSP. The SCSP calculates a Charging Profile and sends it to the eMSP by

calling the Charging Profiles PUT method on the Sender interface implemented by the eMSP. The eMSP forwards it to the CPO by

OCPI 2.2-d2

152

calling the Charging Profiles PUT method on the Receiver interface.

The CPO responds to the eMSP, the response body will contain the response to the request, acknowledging the request was

understood and can be forwarded to the Charge Point. The eMSP forwards this response to the SCSP.

The CPO sends the requests to the Charge Point. When the CPO receives a response from the Charge Point, that result is send to

the eMSP by call the POST method, on the URL provided by the eMSP in the PUT request of the eMSP. The eMSP forwards this

result to the the URL provided by the SCSP in the PUT request of the SCSP, this call will contain a ChargingProfileResult Object.

SCSP

Sender

eMSP

Sender

Receiver

CPO

Receiver

Charge Point

StartTransaction.req(Token=200)

StartTransaction.conf(TransactionId=15)

Session(id=15)

Calculate ChargingProfile

PUT https://emsp.com/ocpi/2.2/chargingprofiles/15

SetChargingProfile(response_url=https://client.com/12345)

PUT https://cpo.com/ocpi/2.2/chargingprofiles/15

SetChargingProfile(response_url=https://emsp.com/4567)

status_code = 1000,

data: {ChargingProfileResponse { result = ACCEPTED }}

status_code = 1000,

data: {ChargingProfileResponse { result = ACCEPTED }}

SetChargingProfile.req

SetChargingProfile.conf

POST https://emsp.com/4567

ChargingProfileResult(result = ACCEPTED)

POST https://client.com/12345

ChargingProfileResult(result = ACCEPTED)

Figure 40. Example of a SetChargingProfile via the MSP.

14.3.3. Example of a removing/clearing ChargingProfile sent by the Sender

(typically the eMSP or SCSP)

The Sender might want to remove the charging profile, for example the EV driver has selected to switch to charging with the highest

speed possible. The Sender can ask the CPO to remove the set charging profile. This can be done by calling the DELETE method

on the Receiver interface.

The CPO responds to the eMSP or SCSP, the response body will contain the response to the request, acknowledging the request

was understood and can be forwarded to the Charge Point.

The CPO sends the clear requests to the Charge Point. When the CPO receives a response from the Charge Point, that result is

sent to the eMSP by call the POST method, on the URL provided by the eMSP in the DELETE request of the eMSP, this call will

contain a ClearProfileResult Object.

OCPI 2.2-d2

153

Sender

eMSP or SCSP

CPO

Receiver

Charge Point

Ongoing Session with id=15

DELETE https://server.com/ocpi/2.2/chargingprofiles/15?response_url=https://client.com/12345

status_code = 1000, data: {ChargingProfileResponse { result = ACCEPTED }}

ClearChargingProfile.req

ClearChargingProfile.conf

POST https://client.com/12345

ClearProfileResult(result = ACCEPTED)

Figure 41. Example of a ClearChargingProfile.

14.3.4. Example of a removing/clearing ChargingProfile send by the SCSP via

the eMSP

The SCSP might want to remove the charging profile, for example the EV driver has selected to switch to charging with the highest

speed possible. The SCSP can ask the eMSP to ask the CPO to remove the set charging profile. This can be done by calling the

DELETE method on the eMSPs Charging Profile Receiver interface. The eMSP forwards this to the CPO by calling the DELETE

method on the CPOs Charging Profile Receiver interface.

The CPO responds to the eMSP, the response body will contain the response to the request, acknowledging the request was

understood and can be forwarded to the Charge Point. The eMSP forwards this response to the SCSP.

The CPO send the clear requests to the Charge Point. When the CPO receives a response from the Charge Point, that result is

sent to the eMSP by call the POST method, on the URL provided by the eMSP in the DELETE request of the eMSP. The eMSP

forwards this result to the the URL provided by the SCSP in the DELETE request of the SCSP, this call will contain a

ClearProfileResult Object.

SCSP

eMSP

Sender

Receiver

CPO

Receiver

Charge Point

Ongoing Session with id=15

DELETE https://server.com/ocpi/2.2/chargingprofiles/15

?response_url=https://scsp.com/12345

DELETE https://server.com/ocpi/2.2/chargingprofiles/15

?response_url=https://emsp.com/789AB

status_code = 1000, data:

{ChargingProfileResponse { result = ACCEPTED }}

status_code = 1000, data:

{ChargingProfileResponse { result = ACCEPTED }}

ClearChargingProfile.req

ClearChargingProfile.conf

POST https://emsp.com/789AB

ClearProfileResult(result = ACCEPTED)

POST https://scsp.com/12345

ClearProfileResult(result = ACCEPTED)

Figure 42. Example of a ClearChargingProfile via the MSP.

OCPI 2.2-d2

154

14.3.5. Example of a GET ActiveChargingProfile send by the Sender (typically

the eMSP or SCSP)

When the Sender wants to know the current planned charging profile for a session, the Sender can ask the CPO for the

ActiveChargingProfile by calling the GET method on the Receiver interface.

The CPO responds to the eMSP or SCSP, the response body will contain the response to the request, acknowledging the request

was accepted and can be forwarded to the Charge Point.

The CPO sends a message to the Charge Point to retrieve the current active charging profile. When the CPO receives a response

from the Charge Point, that ActiveChargingProfile is send to the eMSP by call the POST method, on the URL provided by the eMSP

in the GET request of the eMSP, this call will contain a ActiveChargingProfileResult Object.

Sender

eMSP or SCSP

CPO

Receiver

Charge Point

Ongoing Session with id=15

GET https://server.com/ocpi/2.2/chargingprofiles/15?response_url=https://client.com/12345

status_code = 1000, data: {ChargingProfileResponse { result = ACCEPTED }}

GetCompositeSchedule.req

GetCompositeSchedule.conf

POST https://client.com/12345

ActiveProfileResult(result = ACCEPTED, ActiveChargingProfile)

Figure 43. Example of a GET ActiveChargingProfile.

14.3.6. Example of a GET ActiveChargingProfile send by the SCSP via eMSP

When the SCSP wants to known the current planned charging profile for a session, the SCSP can ask the the eMSP to ask the

CPO for the ActiveChargingProfile by calling the GET method on the eMSPs Charging Profile Receiver interface. The eMSP

forwards this to the CPO by calling the GET method on the CPOs Charging Profile Receiver interface.

The CPO responds to the eMSP, the response body will contain the response to the request, acknowledging the request was

accepted and can be forwarded to the Charge Point. The eMSP forwards this response to the SCSP.

The CPO sends a message to the Charge Point to retrieve the current active charging profile. When the CPO receives a response

from the Charge Point, that ActiveChargingProfile is send to the eMSP by call the POST method, on the URL provided by the eMSP

in the GET request of the eMSP, this call will contain a ActiveChargingProfileResult Object. The eMSP forwards this result to the the

URL provided by the SCSP in the GET request of the SCSP, this call will contain the same ActiveChargingProfileResult Object.

OCPI 2.2-d2

155

SCSP

Sender

eMSP

Sender

Receiver

CPO

Receiver

Charge Point

Ongoing Session with id=15

GET https://server.com/ocpi/2.2/chargingprofiles/15

?response_url=https://scsp.com/12345

GET https://server.com/ocpi/2.2/chargingprofiles/15

?response_url=https://emsp.com/789AB

status_code = 1000, data:

{ChargingProfileResponse { result = ACCEPTED }}

status_code = 1000, data:

{ChargingProfileResponse { result = ACCEPTED }}

GetCompositeSchedule.req

GetCompositeSchedule.conf

POST https://emsp.com/789AB

ActiveProfileResult(result = ACCEPTED, ActiveChargingProfile)

POST https://scsp.com/12345

ActiveProfileResult(result = ACCEPTED, ActiveChargingProfile)

Figure 44. Example of a GET ActiveChargingProfile via the MSP.

14.3.7. Example of the Receiver (typically the CPO) sending an updated

ActiveChargingProfile

When the CPO knows the ActiveChargingProfile of a Charge Point has changed, the Receiver (typically the CPO) sends this

update ActiveChargingProfile to the Sender (typically the eMSP or SCSP), by calling the PUT method on the Sender interface.

Charge Point

CPO

Receiver

Sender

eMSP or SCSP

Ongoing Session with id=15

update ChargingProfile

PUT https://www.server.com/ocpi/2.2/chargingprofiles/15

ActiveChargingProfile()

Figure 45. Example of an ActiveChargingProfile being send by the CPO

14.3.8. Example of the Receiver (typically the CPO) sending an updated

ActiveChargingProfile to the SCSP via the eMSP

When the CPO knows the ActiveChargingProfile of a Charge Point has changed, the Receiver (typically the CPO) sends this

update ActiveChargingProfile to the Sender (SCSP), by calling the PUT method on the eMSPs Sender interface.

The eMSP forwards this ActiveChargingProfile to the SCSP, by calling the PUT method on the SCSPs Sender interface.

OCPI 2.2-d2

156

Charge Point

CPO

Receiver

Sender

eMSP

SCSP

Sender

Ongoing Session with id=15

update ChargingProfile

PUT https://www.server.com/ocpi/2.2/chargingprofiles/15

ActiveChargingProfile()

PUT https://www.server.com/ocpi/2.2/chargingprofiles/15

ActiveChargingProfile()

Figure 46. Example of an ActiveChargingProfile being sent by the CPO via the eMSP

14.4. Interfaces and endpoints

The ChargingProfiles module consists of two interfaces: a Receiver interface that enables a Sender (and its clients) to send

ChargingProfiles to a Location/EVSE, and an Sender interface to receive the response from the Location/EVSE asynchronously.

14.4.1. Receiver Interface

Typically implemented by market roles like: CPO.

Example endpoint structures:

Method Description

GET Gets the ActiveChargingProfile for a specific charging session.

POST n/a

PUT Creates/updates a ChargingProfile for a specific charging session.

PATCH n/a

DELETE Cancels an existing ChargingProfile for a specific charging session.

14.4.1.1. GET Method

Retrieves the ActiveChargingProfile as it is currently planned for the the given session.

Endpoint structure definition:

{chargingprofiles_endpoint_url}{session_id}?duration={duration}&response_url={url}

Example:

https://www.cpo.com/ocpi/2.2/chargingprofiles/1234?duration=900&response_url=https://www.msp.com

/ocpi/2.2/chargingprofile/response?request_id=5678

NOTE

As it is not common to add a body to a GET request, all parameters are added to the URL.

Request Parameters

The following parameters can be provided as URL segments.

OCPI 2.2-d2

157

Parameter Datatype Requi

red

Description

session_id CiString(36) yes The unique id that identifies the session in the CPO platform.

duration int 1 Length of the requested ActiveChargingProfile in seconds Duration in seconds. *

response_url URL 1 URL that the ActiveChargingProfileResult POST should be send to. This URL

might contain an unique ID to be able to distinguish between GET

ActiveChargingProfile requests.

NOTE

duration: Balance the duration between maximizing the information gained and the data usage and computation

to execute on the request. Warning: asking for longer duration than necessary might result in additional data

costs, while its added value diminishes with every change in the schedule.

Response Data

The response contains the direct response from the Receiver, not the response from the EVSE itself. That information will be sent

via an asynchronous POST on the Sender interface if this response is ACCEPTED.

Datatype Card. Description

ChargingProfileResponse 1 Result of the ActiveChargingProfile request, by the Receiver (Typically CPO), not the

location/EVSE. So this indicates if the Receiver understood the ChargingProfile request

and was able to send it to the EVSE. This is not the response by the Charge Point.

14.4.1.2. PUT Method

Creates a new ChargingProfile on a session, or replaces an existing ChargingProfile on the EVSE.

Endpoint structure definition:

{chargingprofiles_endpoint_url}{session_id}

Example:

https://www.cpo.com/ocpi/2.2/chargingprofiles/1234

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

session_id CiString(36) yes The unique id that identifies the session in the CPO platform.

14.4.1.3. Request Body

The body contains a SetChargingProfile object, that contains the new ChargingProfile and a response URL.

Type Card. Description

SetChargingProfile 1 SetChargingProfile object with information needed to set/update the Charging Profile for a

session.

OCPI 2.2-d2

158

Response Data

The response contains the direct response from the Receiver (Typically CPO), not the response from the EVSE itself, that will be

sent via an asynchronous POST on the Sender interface if this response is ACCEPTED.

Datatype Card. Description

ChargingProfileResponse 1 Result of the ChargingProfile PUT request, by the CPO (not the location/EVSE). So this

indicates if the CPO understood the ChargingProfile PUT request and was able to send it

to the EVSE. This is not the response by the Charge Point.

14.4.1.4. DELETE Method

Clears the ChargingProfile set by the eMSP on the given session.

Endpoint structure definition:

{chargingprofiles_endpoint_url}{session_id}?response_url={url}

Example:

https://www.cpo.com/ocpi/2.2/chargingprofiles/1234?response_url=https://www.server.com/example

NOTE

As it is not common to add a body to a DELETE request, all parameters are added to the URL.

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

session_id CiString(36) yes The unique id that identifies the session in the CPO platform.

response_url URL 1 URL that the ClearProfileResult POST should be send to. This URL might

contain an unique ID to be able to distinguish between DELETE ChargingProfile

requests.

Response Data

The response contains the direct response from the Receiver (typically CPO), not the response from the EVSE itself, that will be

sent via an asynchronous POST on the Sender interface if this response is ACCEPTED.

Datatype Card. Description

ChargingProfileResponse 1 Result of the ChargingProfile DELETE request, by the CPO (not the location/EVSE). So

this indicates if the CPO understood the ChargingProfile DELETE request and was able to

send it to the EVSE. This is not the response by the Charge Point.

14.4.2. Sender Interface

Typically implemented by market roles like: SCSP.

The Sender interface receives the asynchronous responses.

OCPI 2.2-d2

159

Method Description

GET n/a

POST Receive the asynchronous response from the Charge Point.

PUT Receiver (typically CPO) can send an updated ActiveChargingProfile when other inputs have made changes to

existing profile. When the Receiver (typically CPO) sends a update profile to the EVSE, for an other reason

then the Sender (Typically SCSP) asking, the Sender SHALL post an update to this interface. When a local

input influence the ActiveChargingProfile in the EVSE AND the Receiver (typically CPO) is made aware of this,

the Receiver SHALL post an update to this interface.

PUT n/a

PATCH n/a

DELETE n/a

14.4.2.1. POST Method

Request Parameters

There are no URL segment parameters required by OCPI.

As the Sender interface is called by the Receiver (typically CPO) on the URL given response_url in the Sender request to the

Receiver interface. It is up to the implementation of the Sender (typically SCSP) to determine what parameters are put in the URL.

The Sender sends a URL in the POST method body to the Receiver. The Receiver is required to use this URL for the asynchronous

response by the Charge Point. It is advised to make this URL unique for every request to differentiate simultaneous commands, for

example by adding a unique id as a URL segment.

Endpoint structure definition:

No structure defined. This is open to the eMSP to define, the URL is provided to the Receiver by the Sender. Therefor OCPI does

not define variables.

Examples:

https://www.server.com/ocpi/2.2/chargingprofiles/chargingprofile/12345678

https://www.server.com/activechargingprofile/12345678

https://www.server.com/clearprofile?request_id=12345678

https://www.server.com/ocpi/2.2/12345678

The content of the request body depends on the original request by the eMSP to which this POST is send as a result.

14.4.2.2. Request Body

Datatype Card. Description

Choice: one of three

ActiveChargingProfileResult 1 Result of the GET ActiveChargingProfile request, from the Charge Point.

ChargingProfileResult 1 Result of the PUT ChargingProfile request, from the Charge Point.

ClearProfileResult 1 Result of the DELETE ChargingProfile request, from the Charge Point.

OCPI 2.2-d2

160

14.4.2.3. Response Body

The response to the POST on the Sender interface SHALL contain the Response Format with the data field omitted.

14.4.2.4. PUT Method

Updates the Sender (typically SCSP) when the Receiver (typically CPO) knows the ActiveChargingProfile has changed.

The Receiver SHALL call this interface every time it knows changes have been made that influence the ActiveChargingProfile for an

ongoing session AND the Sender has at least once successfully called the charging profile Receiver PUT interface for this session

(SetChargingProfile). If the Receiver doesn’t know the ActiveChargingProfile has changed (EVSE does not notify the Receiver

(typically CPO) of the change) it is not required to call this interface.

The Receiver SHALL NOT call this interface for any session where the Sender has never, successfully called the charging profile

Receiver PUT interface for this session (SetChargingProfile).

The Receiver SHALL send a useful relevant duration of ActiveChargingProfile to send to the Sender. As a guide: between 5 and 60

minutes. If the Sender wants a longer ActiveChargingProfile the Sender can always do a GET with a longer duration.

Endpoint structure definition:

{chargingprofiles_endpoint_url}{session_id}

Example:

https://www.server.com/ocpi/2.2/chargingprofiles/1234

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Requi

red

Description

session_id CiString(36) yes The unique id that identifies the session in the CPO platform.

14.4.2.5. Request Body

The body contains the update ActiveChargingProfile, The ActiveChargingProfile is the charging profile as calculated by the EVSE.

Type Card. Description

ActiveChargingProfile 1 The new ActiveChargingProfile. If there is no longer any charging profile active, the

ActiveChargingProfile SHALL reflect this by showing the maximum charging capacity of the

EVSE.

14.4.2.6. Response Body

The response to the PUT on the eMSP interface SHALL contain the Response Format with the data field omitted.

14.5. Object description

14.5.1. ChargingProfileResponse Object

The ChargingProfileResponse object is send in the HTTP response body.

OCPI 2.2-d2

161

Because OCPI does not allow/require retries, it could happen that the asynchronous result url given by the eMSP is never

successfully called. The eMSP might have had a glitch, HTTP 500 returned, was offline for a moment etc. For the eMSP to be able

to reject to timeouts, it is important for the eMSP to known the timeout on a certain command.

Property Type Card. Description

result ChargingProfileResponseType 1 Response from the CPO on the ChargingProfile request.

timeout int 1 Timeout for this ChargingProfile request in seconds. When the

Result is not received within this timeout, the eMSP can assume

that the message might never be sent.

14.5.2. ActiveChargingProfileResult Object

The ActiveChargingProfileResult object is send by the CPO to the given response_url in a POST request. It contains the result

of the GET (ActiveChargingProfile) request send by the eMSP.

Property Type Card. Description

result ChargingProfileResultType 1 The EVSE will indicate if it was able to process the request for the

ActiveChargingProfile

profile ActiveChargingProfile ? The requested ActiveChargingProfile, if the result field is set to: ACCEPTED

14.5.3. ChargingProfileResult Object

The ChargingProfileResult object is send by the CPO to the given response_url in a POST request. It contains the result of the

PUT (SetChargingProfile) request send by the eMSP.

Property Type Card. Description

result ChargingProfileResultType 1 The EVSE will indicate if it was able to process the new/updated charging

profile.

14.5.4. ClearProfileResult Object

The ClearProfileResult object is send by the CPO to the given response_url in a POST request. It contains the result of the

DELETE (ClearProfile) request send by the eMSP.

Property Type Card. Description

result ChargingProfileResultType 1 The EVSE will indicate if it was able to process the removal of the charging

profile (ClearChargingProfile).

14.5.5. SetChargingProfile Object

Object set to a CPO to set a Charging Profile.

Property Type Card. Description

charging_profile ChargingProfile 1 Contains limits for the available power or current over time.

OCPI 2.2-d2

162

Property Type Card. Description

response_url URL 1 URL that the ChargingProfileResult POST should be send to. This

URL might contain an unique ID to be able to distinguish between

GET ActiveChargingProfile requests.

14.6. Data types

14.6.1. ActiveChargingProfile class

Property Type Card. Description

start_date_time DateTime 1 Date and time at which the Charge Point has calculated this

ActiveChargingProfile. All time measurements within the profile are

relative to this timestamp.

charging_profile ChargingProfile 1 Charging profile structure defines a list of charging periods.

14.6.2. ChargingRateUnit enum

Unit in which a charging profile is defined.

Value Description

W Watts (power)

This is the TOTAL allowed charging power. If used for AC Charging, the phase current should be

calculated via: Current per phase = Power / (Line Voltage * Number of Phases). The "Line Voltage"

used in the calculation is the Line to Neutral Voltage (VLN). In Europe and Asia VLN is typically

220V or 230V and the corresponding Line to Line Voltage (VLL) is 380V and 400V. The "Number of

Phases" is the numberPhases from the ChargingProfilePeriod. It is usually more convenient to use

this for DC charging. Note that if numberPhases in a ChargingProfilePeriod is absent, 3 SHALL be

assumed.

A Amperes (current)

The amount of Ampere per phase, not the sum of all phases. It is usually more convenient to use

this for AC charging.

14.6.3. ChargingProfile class

Charging profile class defines a list of charging periods.

Property Type Card. Description

start_date_time DateTime ? Starting point of an absolute profile. If absent the profile

will be relative to start of charging.

duration int ? Duration of the charging profile in seconds. If the

duration is left empty, the last period will continue

indefinitely or until end of the transaction in case

startProfile is absent.

charging_rate_unit ChargingRateUnit 1 The unit of measure.

OCPI 2.2-d2

163

Property Type Card. Description

min_charging_rate number ? Minimum charging rate supported by the EV. The unit

of measure is defined by the chargingRateUnit. This

parameter is intended to be used by a local smart

charging algorithm to optimize the power allocation for

in the case a charging process is inefficient at lower

charging rates. Accepts at most one digit fraction (e.g.

8.1)

charging_profile_period ChargingProfilePeriod * List of ChargingProfilePeriod elements defining

maximum power or current usage over time.

14.6.4. ChargingprofilePeriod class

Charging profile period structure defines a time period in a charging profile, as used in: ChargingProfile

Property Type Card. Description

start_period int 1 Start of the period, in seconds from the start of profile. The value of StartPeriod

also defines the stop time of the previous period.

limit number 1 Charging rate limit during the profile period, in the applicable chargingRateUnit,

for example in Amperes (A) or Watts (W). Accepts at most one digit fraction (e.g.

8.1).

14.6.5. ChargingProfileResponseType enum

Response to the ChargingProfile request from the eMSP to the CPO.

Value Description

ACCEPTED ChargingProfile request accepted by the CPO, request will be forwarded to the EVSE.

NOT_SUPPORTED The ChargingProfiles not supported by this CPO, Charge Point, EVSE etc.

REJECTED ChargingProfile request rejected by the CPO. (Session might not be from a customer of the eMSP

that send this request)

TOO_OFTEN ChargingProfile request rejected by the CPO, requests are send more often then allowed.

UNKNOWN_SESSION The Session in the requested command is not known by this CPO.

14.6.6. ChargingProfileResultType enum

Result of a ChargingProfile request that the EVSE sends via the CPO to the eMSP.

Value Description

ACCEPTED ChargingProfile request accepted by the EVSE.

REJECTED ChargingProfile request rejected by the EVSE.

UNKNOWN No Charging Profile(s) were found by the EVSE matching the request.

OCPI 2.2-d2

164

15. HubClientInfo module

Module Identifier: hubclientinfo

Data owner: Hub

Type: Configuration Module

This module provides parties connected to a hub with the connection status of other parties that are connected to a hub that they

can communicate with. So, CPOs know which eMSP and other parties are online and vice versa.

Unlike the usual OCPI modules, this module is between eMSP/CPO and Hub instead of between eMSP and CPO.

15.1. Scenarios

This section will describe what the expected behavior is when a party receives information of a ConnectionState change.

15.1.1. Another Party becomes CONNECTED

Party is (back) online. Request can be sent again. Every party receiving Client Owned Objects from this party should be prepared

to receive Client Owned Objects with URLs that contain the party_id and country_code of this party.

15.1.2. Another Party goes OFFLINE

Connection to party is not available: No requests can be sent. Do not queue Push messages. When the other party comes back

online, it is their responsibility to do a GET to get back in sync.

15.1.3. Another Party becomes PLANNED

No requests can be sent to this new party yet. It can be a good idea to sent some notification to an operator to get into contact with

the new party so contracts can be setup. This state may also be used when a Hub has some configuration indicating which parties

have contracts which each other. When a company does not have a connection configured. This state may also be sent to parties.

15.1.4. Another Party becomes SUSPENDED

Like with OFFLINE, no requests should be sent to this party, they cannot be delivered.

When for example CDRs still have to be delivered, so there is some unfinished business, parties are advised to get into contact with

the other party in another way the OCPI: Call them, send an e-mail.

15.2. Flow and Life-cycle

15.2.1. Push model

When the Hub creates a new ClientInfo object they push it to the connected parties by calling PUT on the connected party

ClientInfo endpoint with the newly created ClientInfo object.

Any changes to ClientInfo in the Hub system are send to the connected party system by calling the PUT method on the connected

party ClientInfo endpoint with the updated ClientInfo.

When the Hub invalidates a ClientInfo object (deleting is not possible), the Hub will send the updated ClientInfo object (with the

field: status set to SUSPENDED, by calling the PUT method on the connected party ClientInfo endpoint with the updated ClientInfo

object.

OCPI 2.2-d2

165

When the connected party is not sure about the state or existence of a ClientInfo object in the Hub system, the connected party can

call the GET to request to ClientInfo object from the Hub system.

15.2.2. Pull model

When a connected party is not sure about the state of the list of known connected parties of a Hub, or wants to request the full list

at the start-up of their system, the connected party can call the GET on the Hubs ClientInfo endpoint to receive all ClientInfo

objects. This method is not for operational flow.

15.2.3. Still alive check.

The hubs needs to determine if a connection is still "alive".

To do this, the Hub should keep track of the time that has passed since the last message was received from a connected party.

When this is longer then X minutes (when unsure, start with 5 minutes) the Hub should send a: GET to the Version information

endpoint. As the Version information endpoint is always required in OCPI, and this endpoint is provided by all parties, and a GET to

the versions endpoint does not have any side effects, this is seen as the best way to do an "still-alive"check.

15.3. Interfaces

There is both a Sender (Typically Hub) as a Receiver interface for ClientInfo. It is advised to use the Push direction from Sender to

connected clients during normal operation. The Hub interface is meant to be used when the connected client is not 100% sure the

ClientInfo cache is still correct.

15.3.1. Receiver Interface

Typically implemented by all parties connecting to a Hub.

With this interface the Hub can push the ClientInfo information to a connected client (eMSP/CPO etc) Example endpoint structure:

/ocpi/cpo/2.0/clientinfo/{country_code}/{party_id}

Method Description

GET Retrieve a ClientInfo object as it is stored in the connected clients system.

POST n/a

PUT Push new/updated ClientInfo object to the connect client.

PATCH n/a

DELETE n/a, Use PUT, ClientInfo objects cannot be removed).

15.3.1.1. GET Method

If the Hub wants to check the status of a ClientInfo object in the connected clients system it might GET the object from the

connected clients system for validation purposes. The Hub is the owner of the objects, so it would be illogical if the connected client

system had a different status or was missing an object.

Request Parameters

The following parameters can be provided as URL segments.

OCPI 2.2-d2

166

Parameter Datatype Requi

red

Description

country_code CiString(2) yes Country code of the requested ClientInfo object.

party_id CiString(3) yes Party ID (Provider ID) of the requested ClientInfo object.

Response Data

The response contains the requested object.

Type Card. Description

ClientInfo 1 The requested ClientInfo object.

15.3.1.2. PUT Method

New or updated ClientInfo objects are pushed from the Hub to a connected client.

Request Body

In the put request a the new or updated ClientInfo object is send.

Type Card. Description

ClientInfo 1 New or updated ClientInfo object.

Request Parameters

The following parameters can be provided as URL segments.

Parameter Datatype Required Description

country_code CiString(2) yes Country code of the eMSP

sending this PUT request to

the CPO system.

party_id CiString(3) yes Party ID (Provider ID) of the

eMSP sending this PUT

request to the CPO system.

Example: put a new ClientInfo object

PUT To URL: https://www.server.com/ocpi/cpo/2.0/clientinfo/NL/ALL

{

"country_code": "NL",

"party_id": "ALL",

"role": "CPO",

"status": "PLANNED",

}

15.3.2. Sender Interface

Typically implemented by the Hub.

OCPI 2.2-d2

167

This interface enables Receivers to request the current list of ClientInfo objects from the Sender, when needed.

Method Description

GET Get the list of known ClientInfo objects, last updated between the {date_from} and {date_to} paginated)

POST n/a

PUT n/a

PATCH n/a

DELETE n/a

15.3.2.1. GET Method

Fetch information about clients connected to a Hub.

Endpoint structure definition:

{locations_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={l

imit}]

Examples:

https://www.server.com/ocpi/cpo/2.2/hubclientinfo/?date_from=2019-01-28T12:00:00&date_to=2019-

01-29T12:00:00

https://ocpi.server.com/2.2/hubclientinfo/?offset=50

https://www.server.com/ocpi/2.2/hubclientinfo/?date_from=2019-01-29T12:00:00&limit=100

https://www.server.com/ocpi/cpo/2.2/hubclientinfo/?offset=50&limit=100

15.3.2.2. Request Parameters

If additional parameters: {date_from} and/or {date_to} are provided, only ClientInfo objects with (last_updated) between

the given {date_from} (including) and {date_to} (excluding) will be returned.

This request is paginated, it supports the pagination related URL parameters.

Parameter Datatype Requi

red

Description

date_from DateTime no Only return ClientInfo that have last_updated after or equal to this Date/Time

(inclusive).

date_to DateTime no Only return ClientInfo that have last_updated up to this Date/Time, but not

including (exclusive).

offset int no The offset of the first object returned. Default is 0.

limit int no Maximum number of objects to GET.

15.3.2.3. Response Data

The endpoint response with list of valid ClientInfo objects, the header will contain the pagination related headers.

Any older information that is not specified in the response is considered as no longer valid. Each object must contain all required

OCPI 2.2-d2

168

fields. Fields that are not specified may be considered as null values.

Type Card. Description

ClientInfo * List of all (or matching) ClientInfo objects.

15.4. Object description

15.4.1. ClientInfo Object

Property Type Card. Description

party_id CiString(3) 1 CPO or eMSP ID of this party (following the 15118 ISO standard), as

used in the credentials exchange.

country_code CiString(2) 1 Country code of the country this party is operating in, as used in the

credentials exchange.

role Role 1 The role of the connected party.

status ConnectionStatus 1 Status of the connection to the party.

last_updated DateTime 1 Timestamp when this ClientInfo object was last updated.

15.5. Data types

15.5.1. ConnectionStatus enum

Value Description

CONNECTED Party is connected.

OFFLINE Party is currently not connected.

PLANNED Connection to this party is planned, but has never been connected.

SUSPENDED Party is now longer active, will never connect anymore.

OCPI 2.2-d2

169

16. Types

16.1. CiString type

Case Insensitive String. Only printable ASCII allowed. (Non-printable characters like: Carriage returns, Tabs, Line breaks, etc are

not allowed)

16.2. DateTime type

All timestamps are formatted as string(25) following RFC 3339, with some additional limitations.

All timestamps SHALL be in UTC. The absence of the timezone designator implies a UTC timestamp. Fractional seconds MAY be

used.

Example of how timestamps shall be formatted in OCPI, other formats/patterns are not allowed:

2015-06-29T20:39:09Z

2015-06-29T20:39:09

2016-12-29T17:45:09.2Z

2016-12-29T17:45:09.2

2018-01-01T01:08:01.123Z

2018-01-01T01:08:01.123

NOTE

+00:00 is not the same as UTC.

16.3. DisplayText class

Property Type Card. Description

language string(2) 1 Language Code ISO 639-1.

text string(512) 1 Text to be displayed to a end user. No markup, html etc. allowed.

Example:

{

"language": "en",

"text": "Standard Tariff"

}

16.4. number type

Numbers in OCPI are formatted as JSON numbers. Unless mentioned otherwise, numbers use 4 decimals and a sufficiently large

amount of digits.

16.5. Price class

Property Type Card. Description

excl_vat number 1 Price/Cost excluding VAT.

incl_vat number ? Price/Cost including VAT.

OCPI 2.2-d2

170

16.5.1. Role enum

Value Description

CPO Charge Point Operator Role.

EMSP eMobility Service Provider Role.

HUB Hub role.

NAP National Access Point Role (national Database with all Location information of a country).

NSP Navigation Service Provider Role, role like an eMSP (probably only interested in Location

information).

OTHER Other role.

SCSP Smart Charging Service Provider Role.

16.6. string type

Case Sensitive String. Only printable UTF-8 allowed. (Non-printable characters like: Carriage returns, Tabs, Line breaks, etc are not

allowed)

All strings in messages and enumerations are case sensitive, unless explicitly stated otherwise.

16.7. URL type

An URL a string(255) type following the w3.org spec.

OCPI 2.2-d2

171

17. Changelog

17.1. Changes between OCPI 2.1.1 and 2.2

Lots of typos fixed and textual improvements.

The following changes to messages/objects etc.

Context (Module / Object) Expected

Impact:

eMSP /

CPO

Expected

Effort:

eMSP /

CPO

Description

CDRs /

CDR Object

Medium /

Major

Average /

Large

- Added county_code and party_id fields, making it easier to

determine the owner of a CDR.

- Added session_id field, making it easier to match a CDR to a

Session.

- Renamed stop_date_time field to end_date_time, to bring the

naming inline with the rest of OCPI.

- Changed total_cost field from type: number to Price, this

provides the eMSP with the total cost including VAT.

- Replaced auth_id field with CdrToken. auth_id alone could not

be used to uniquely identify a Token. By copying the information for

the dynamic Token object, the CDR will always reflect the 'true' status

of Token at the start of the charging session.

- Replaced location field with cdr_location, this also changed

type, from Location to CdrLocation. Reusing the Location

object always caused a lot of confusing, things were not clear. By

creating a dedicated object CdrLocation with only the relevant

fields, things should be much clearer.

- Added credit and credit_reference_id fields, to allow for

Credit CDRs to be send.

- Added total_fixed_cost, total_energy_cost,

total_time_cost, total_parking_cost and

total_reservation_cost fields, to allow more cost details in the

CDRs.

- Added authorization_reference field for binding an

authorization to the resulting session.

- Added signed_data field, enabling OCPI to be used to transport

signed meter data from the Charge Point to the eMSP and EV driver,

can be used for Eichrecht.

- Added invoice_reference_id field (optional), to allow a CDRs

to reference an invoice.

- Field id changed in length from 36 to 39, to allow for something to

be appended after the original id in case of a Credit CDR.

Commands /

AuthMethod enum

Minor /

Minor

Minimal /

Minimal

Added COMMAND value, to enable reporting authorization via

Command like: StartSession or ReserveNow.

CDRs /

CdrDimensionType enum

Medium /

Medium

Minimal /

Minimal

Added RESERVATION_TIME value, to enable reporting of cost for a

reservation in a Session or CDR.

CDRs /

CdrDimensionType enum

Medium /

Medium

Minimal /

Minimal

Removed FLAT value, that is of no use on a CDR, only causes

confusion, should have been removed when CdrDimensionType was

created from DimensionType of OCPI 2.0.

OCPI 2.2-d2

172

Context (Module / Object) Expected

Impact:

eMSP /

CPO

Expected

Effort:

eMSP /

CPO

Description

CDRs /

ChargingPeriod class

Medium /

Medium

Minimal /

Minimal

Added tariff_id field to ChargingPeriod, when the session

switches from one tariff to another, this needs to be known, can be

relevant with Preference based Smart Charging.

ChargingProfiles Major /

Major

Large /

Large

Added new ChargingProfiles module.

Commands /

CancelReservation Object

Minor /

Minor

Minimal /

Minimal

Added CancelReservation object for the cancel reservation

command.

Commands /

CommandType Enum

Minor /

Minor

Minimal /

Minimal

Added CANCEL_RESERVATION value, adding the cancel reservation

command.

Commands /

CommandResponse Object

Minor /

Minor

Minimal /

Minimal

- Added message field, enables the CPO to send a message to the

user when something goes wrong.

- Added timeout field, enables the eMSP to cleanup not responded

outstanding commands.

Commands /

ReserveNow Object

Minor /

Medium

Minimal /

Average

- Changed location_id and evse_uids from string to CiString,

making them case-insensitive, which had always been the idea.

Lengths changed from 39 to 36, matching changes in the object

definitions.

- Changed reservation_id from int to CiString(36), making it

possible to use UUIDs.

- Added authorization_reference field for binding an

authorization to the resulting session.

- Changed/added requirements in description of ReserveNow Object.

Commands /

StartSession Object

Minor /

Medium

Minimal /

Average

- Changed location_id and evse_uids from string to CiString,

making them case-insensitive, which had always been the idea.

Lengths changed from 39 to 36, matching changes in the object

definitions.

- Added authorization_reference field for binding an

authorization to the resulting session.

- Changed/added requirements in description of StartSession Object.

Commands /

StopSession Object

Minor /

Minor

Minimal /

Minimal

Changed session_id from string to CiString, making it case-

insensitive, which had always been the idea.

Commands /

UnlockConnector Object

Minor /

Minor

Minimal /

Minimal

- Changed location_id, evse_uids and connector_ids from

string to CiString, making them case-insensitive, which had always

been the idea.

- Length of location_id and evse_uids changed from 39 to 36,

matching changes in the object definitions.

Commands /

CommandResponseType Enum

Minor /

Minor

Minimal /

Minimal

removed TIMEOUT as possible value. This is moved to the new

CommandResult object.

Commands /

CommandResultType Enum

Minor /

Minor

Minimal /

Minimal

added CANCELED_RESERVATION value. Make it possible for a CPO

to cancel an existing reservation in case of issues with the Charge

Point.

Commands /

CommandResult Object

Medium /

Medium

Medium /

Medium

Changed result message from CPO to eMSP from

CommandResponse to CommandResult to make it more clear.

OCPI 2.2-d2

173

Context (Module / Object) Expected

Impact:

eMSP /

CPO

Expected

Effort:

eMSP /

CPO

Description

Credentials /

Credentials Object

Minor /

Minor

Minimal /

Minimal

Changed country_code and party_id from string to CiString,

making them case-insensitive, which had always been the idea.

Replaced the business_details, party_id and country_code

field with a roles list. Making it possible to implement different

parties and roles in the same OCPI instance. The fields are now

moved into a new `CredentialsRole class.

HubClientInfo Medium /

Medium

Medium /

Medium

Added new HubClientInfo module.

Locations /

Sender GET Object method

Minor /

Minor

Minimal /

Minimal

- Changed location_id, evse_uids and connector_ids from

string to CiString, making them case-insensitive, which had always

been the idea.

- Length of location_id and evse_uids changed from 39 to 36,

matching changes in the object definitions.

Locations /

Receiver GET & PUT methods

Minor /

Minor

Minimal /

Minimal

- Changed country_code, party_id, location_id, evse_uids

and connector_ids from string to CiString, making them case-

insensitive, which had always been the idea.

- Length of location_id and evse_uids changed from 39 to 36,

matching changes in the object definitions.

Locations /

Receiver PATCH method

Minor /

Minor

Minimal /

Minimal

- Changed country_code, party_id, location_id, evse_uids

and connector_ids from string to CiString, making them case-

insensitive, which had always been the idea.

- Length of location_id and evse_uids changed from 39 to 36,

matching changes in the object definitions.

- Added description on how to handle last_updated, and made it

required for all PATCH requests.

Locations /

Connector Object

Minor /

Minor

Minimal /

Minimal

- Field id is changed from string to CiString, making it now case-

insensitive, which had always been the idea.

- Added max_electric_power field, some DC Fast Charger have a

lower max power then can be calculated form voltage and

amperage.

- Changed tariff_id field to tariff_ids, and changed

cardinality from ? to *. Making it possible to make provided tariffs for

different Smart Charging Preferences and also for ad hoc payment.

Changed type from string to CiString, matching the change to Tariff.id.

- Changed amperage field to max_amperage and voltage field to

max_voltage, to better reflect the real meaning of both fields.

Locations /

EVSE Object

Minor /

Minor

Minimal /

Minimal

- Fields uid and evse_id is changed from string to CiString, making

them case-insensitive, which had always been the idea.

- length of uid changed from 39 to 36, as 36 is enough to store UUID

and GUIDs.

OCPI 2.2-d2

174

Context (Module / Object) Expected

Impact:

eMSP /

CPO

Expected

Effort:

eMSP /

CPO

Description

Locations /

Location Object

Minor /

Minor

Minimal /

Minimal

- Added county_code and party_id fields, making it easier to

determine the owner of a Location.

- Field id is changed from string to CiString, making it now case-

insensitive, which had always been the idea.

- length changed from 39 to 36, as 36 is enough to store UUID and

GUIDs.

- Added state field, optional, to allow as much different address

schemes from around the world as possible..

- Changed postal_code field from required to optional, with the

remark that omitting is only allowed when location has no

postal_code.

- Changed time_zone field from optional to required, as the opening

hours and tariff start/end depend on this, they are more and more

important.

- Renamed type field to parking_type and made it optional. It

better reflects what this field really describes.

- Added publish field, required, to control which locations may or

may not be publish in apps etc. - Added publish_allowed_to

field, optional, to give access to locations to only a limited set of

users.

Locations /

AdditionalGeoLocation class

Minor /

Minor

Minimal /

Minimal

Changed regex for fields: latitude and longitude from fixed 6

decimal places, to more flexible 5 to 7 decimal places.

Locations /

Capability enum

Minor /

Minor

Minimal /

Minimal

added new values for: CHARGING_PREFERENCES_CAPABLE,

DEBIT_CARD_PAYABLE and TOKEN_GROUP_CAPABLE.

Locations /

ConnectorType enum

Minor /

Minor

Minimal /

Minimal

added new values for: PANTOGRAPH_TOP_DOWN and

PANTOGRAPH_BOTTOM_UP.

Locations /

EnvironmentalImpact class

Minor /

Minor

Minimal /

Minimal

Changed field name from source to category, this was a copy/past

error in an older version of OCPI, as this is not used (much) yet, it is

better for understandability of OCPI for correct the field name.

Locations /

Facility enum

Minor /

Minor

Minimal /

Minimal

added new values for: BIKE_SHARING, PARKING_LOT, TRAM_STOP

and METRO_STATION.

Locations /

GeoLocation class

Minor /

Minor

Minimal /

Minimal

Changed regex for fields: latitude and longitude from fixed 6

decimal places, to more flexible 5 to 7 decimal places.

Locations /

Hours class

Minor /

Minor

Minimal /

Minimal

removed to option for either: twentyfourseven or regular_hours, now

twentyfourseven is always required and regular_hours is required

when twentyfourseven=false, this is much less confusing.

Locations /

Image class

Minor /

Minor

Minimal /

Minimal

Changed field type from string to CiString, is for machine to machine

communication, so UTF-8 is not needed.

Locations /

RegularHours class

Minor /

Minor

Minimal /

Minimal

Improved the regex for time format.

Locations /

LocationType enum

Minor /

Minor

Minimal /

Minimal

Renamed to: ParkingType

Added the values: ON_DRIVEWAY and ALONG_MOTORWAY

Removed the values: OTHER and UNKNOWN, no longer needed as this

is now optional.

OCPI 2.2-d2

175

Context (Module / Object) Expected

Impact:

eMSP /

CPO

Expected

Effort:

eMSP /

CPO

Description

Sessions /

Sender PUT method

Medium /

Medium

Large /

Large

Added setting Charging Preferences on a session. Proving the CPO

with preferences from the driver, needed for Smart Charging. For this

the following data types are added: ChargingPreferences,

ChargingPreferencesResponse, ProfileType,

Sessions /

Receiver GET and PUT methods

Minor /

Minor

Minimal /

Minimal

Changed country_code, party_id and session_id from string

to CiString, making them case-insensitive, which had always been the

idea.

Sessions /

Receiver PATCH method

Minor /

Minor

Minimal /

Minimal

Changed country_code, party_id and session_id from string

to CiString, making them case-insensitive, which had always been the

idea.

Added description and requirements how to add

charging_periods and made last_updated required for all

PATCH requests.

Sessions /

Session Object

Minor /

Medium

Minimal /

Average

- Added county_code and party_id fields, making it easier to

determine the owner of a Session.

- Field id is changed from string to CiString, making it now case-

insensitive, which had always been the idea.

- Changed total_cost field from type: number to Price, this

provides the eMSP with the total cost including VAT.

- Renamed start_datetime field to start_date_time, to bring

the naming inline with the rest of OCPI.

- Renamed end_datetime field to end_date_time, to bring the

naming inline with the rest of OCPI.

- Replaced auth_id with CdrToken class. auth_id alone could not

be used to uniquely identify a Token.

- Replaced location object with location_id, evse_uid and

connector_id. Having the Location Object in the Session was

overkill, only reference is more inline with the rest.

- Added authorization_reference field for binding an

authorization to the resulting session.

Tariffs /

Receiver PATCH method

Minor /

Minor

Minimal /

Minimal

PATCH is removed from Tariffs as this was seen is not useful, use

PUT instead.

Tariffs /

Tariff Object

Minor /

Minor

Minimal /

Minimal

- Added county_code and party_id fields, making it easier to

determine the owner of a Tariff.

- Field id is changed from string to CiString, making it now case-

insensitive, which had always been the idea.

- Renamed start_datetime field to start_date_time, to bring

the naming inline with the rest of OCPI.

- Renamed end_datetime field to end_date_time, to bring the

naming inline with the rest of OCPI.

- Added optional min_price field, making it possible to set a

minimum price on a Charging Session.

- Added optional max_price field, making it possible to set a

maximum price on a Charging Session.

- Added type field to make it possible to make different tariffs for

different Smart Charging Preferences and also for ad hoc payment.

Tariffs /

PriceComponent class

Minor /

Minor

Minimal /

Minimal

- Added vat field to send the applicable VAT with every tariff

component.

OCPI 2.2-d2

176

Context (Module / Object) Expected

Impact:

eMSP /

CPO

Expected

Effort:

eMSP /

CPO

Description

Tariffs /

ReservationRestrictionType enum

Minor /

Minor

Minimal /

Minimal

Added new enum for Reservation restrictions.

Tariffs /

TariffRestrictions class

Minor /

Minor

Minimal /

Minimal

Added optional reservation field, making it possible to define the

tariff of a reservation (and an expired reservation).

Added optional min_current and max_current field, making it

possible to have a tariff that depends on the current being charged,

instead of the power.

Improved the regex for time format.

Tokens /

Sender GET & POST methods

Minor /

Minor

Minimal /

Minimal

Changed country_code, party_id and token_uid from string to

CiString, making them case-insensitive, which had always been the

idea.

Tokens /

Receiver GET & PUT methods

Minor /

Minor

Minimal /

Minimal

Changed country_code, party_id and tariff_id from string to

CiString, making them case-insensitive, which had always been the

idea.

Added token_type field, making it possible to make a distinction

between different Token types with the same uid.

Tokens /

Receiver PATCH method

Minor /

Minor

Minimal /

Minimal

Changed country_code, party_id and tariff_id from string to

CiString, making them case-insensitive, which had always been the

idea.

Added token_type field, making it possible to make a distinction

between different Token types with the same uid. Made

last_updated required for all PATCH requests.

Tokens /

Token Object

Minor /

Minor

Minimal /

Minimal

- Added county_code and party_id fields, making it easier to

determine the owner of a Token.

- Fields uid changed from string to CiString, making it now case-

insensitive, which had always been the idea.

- Fields auth_id_ renamed to contract_id, a much more logical

and less confusing name. Also changed from string to CiString,

making it now case-insensitive, which had always been the idea.

- Added group_id field to enable support for OCPP

GroupId/ParentId.

- Added default_profile_type field to enable a default

Preference base Smart Charging ProfileType to be provided for a

user.

- Added energy_contract field to make it possible, if allowed, to

use a drivers energy supplier/contract at a Charge Point.

Tokens /

AuthorizationInfo Object

Minor /

Medium

Minimal /

Average

Added token field to enable real-time authorization of unknown

Tokens.

Added authorization_reference field for binding an

authorization to the resulting session.

Tokens /

LocationReferences class

Minor /

Minor

Minimal /

Minimal

- Changed location_id and evse_uids from string to CiString,

making them case-insensitive, which had always been the idea.

- Length of location_id and evse_uids changed from 39 to 36,

matching changes in the object definitions.

- Removed connector_ids, this was not usable as they are not

unique within the Location, there is also no use case.

OCPI 2.2-d2

177

Context (Module / Object) Expected

Impact:

eMSP /

CPO

Expected

Effort:

eMSP /

CPO

Description

Tokens /

TokenType enum

Minor /

Minor

Minimal /

Minimal

Added value AD_HOC_USER and APP_USER`. As more and more

eMSPs are launching Apps, this becomes more common, so a

special categories are useful.

Versions /

Endpoint class

Medium /

Medium

Minimal /

Minimal

Field role added, making it possible to have one OCPI version end-

point for both eMSP and CPO role, so one OCPI connection when

both CPO and eMSP implemented by the same party.

Transport & Format Medium /

Medium

Medium /

Medium

To enable routing of messages through a Hub, new 'OCPI-to-' and

'OCPI-from-' headers are introduced.

Transport & Format Minor /

Minor

Minimal /

Minimal

Unique message ID and Correlation message ID headers are now

required in every request/response.

Types /

DateTime

Minor /

Minor

Minimum

Changed to: RFC 3339 (was ISO 8601) this does not change the

OCPI format, RFC 3339 is more limited, and therefor more inline with

OCPI then ISO 8601 was.

Fractional seconds are now allowed.

Types /

string

Minor /

Minor

Minimum

Type string changed from ASCII to UTF-8. String is used for human-

readable information and thus needed to support for a lot more

character sets then only ASCII.

OCPI 2.2-d2

178