CONNECT API Reference

CONNECT API GraphQL Reference

Contact

CONNECT API Support
development@connect.gp-joule.de

License

No-license

API Endpoints

Production:
https://url.test/graphql

Authentication

To authenticate yourself to the API, you will receive an API key from us. This API must then be included in the header as x-api-key for each query.

curl --location --request POST '<api-url>/graphql' \
--header 'x-api-key: XXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Content-Type: application/json' \
--data-raw '{"query":"query getChargepoints($count: Int, $page: Int) {\r\n  getChargepoints(count: 100, page: 0) {\r\n    chargepoints {\r\n      uuid\r\n      publicName\r\n      connectorsTotal\r\n      connectorsFree\r\n      connectorsOccupied\r\n      connectorsUnavailable\r\n      connectors {\r\n        uuid\r\n        name\r\n        status {\r\n          status\r\n          updatedAt\r\n        }\r\n        evse\r\n        type\r\n      }\r\n    }\r\n    nextPage\r\n    count\r\n    total\r\n  }\r\n}","variables":{}}'

Queries

The schema allows the following Querries

`getCard`

Returns a card by tag id

Returns a Card!

Name	Description
`tagId` - `String!`	Unique identifier of a charge card/authentication medium

Example

Query

query getCard($tagId: String!) {
  getCard(tagId: $tagId) {
    active
    billingContact
    cardType
    contact
    name
    rate
    tagId
    validFrom
  }
}

Variables

{"tagId": "xyz789"}

Response

{
  "data": {
    "getCard": {
      "active": false,
      "billingContact": ID,
      "cardType": 987,
      "contact": ID,
      "name": "abc123",
      "rate": "xyz789",
      "tagId": "xyz789",
      "validFrom": "2021-07-06T16:01:41.120Z"
    }
  }
}

Queries

`getCards`

Returns a list of cards with pagination (limit and offset). The absolute limit of a response is 1000.

Returns [Card]!

Name	Description
`contactId` - `String!`	Unique identifier of a contact
`active` - `Boolean`	Return active cards only
`offset` - `Int`	Defines the starting point of the pagination
`limit` - `Int`	Defines the number of returned elements

Example

Query

query getCards($contactId: String!, $active: Boolean, $offset: Int, $limit: Int) {
  getCards(contactId: $contactId, active: $active, offset: $offset, limit: $limit) {
    active
    billingContact
    cardType
    contact
    name
    rate
    tagId
    validFrom
  }
}

Variables

{"contactId": "abc123", "active": true, "offset": 987, "limit": 987}

Response

{
  "data": {
    "getCards": [
      {
        "active": false,
        "billingContact": ID,
        "cardType": 123,
        "contact": ID,
        "name": "xyz789",
        "rate": "abc123",
        "tagId": "xyz789",
        "validFrom": "2021-07-06T16:01:41.120Z"
      }
    ]
  }
}

Queries

`getChargepoint`

Returns details of a chargpoint either by the chargepoint ID or an evse of a particular connector. One paramter is required. If chargpoint id is set, evse will be ignored.

Returns a Chargepoint!

Name	Description
`id` - `ID`	Chargepoint ID
`evse` - `String`	The EVSE ID defines the unique identifier, a number and letter code of a QR code, of a charging point.

Example

Query

query getChargepoint($id: ID, $evse: String) {
  getChargepoint(id: $id, evse: $evse) {
    connectors {
      ...ConnectorFragment
    }
    connectorsFree
    connectorsOccupied
    connectorsTotal
    connectorsUnavailable
    createdAt
    id
    location {
      ...LocationFragment
    }
    name
    publicName
    updatedAt
  }
}

Variables

{
  "id": ID,
  "evse": "DE*CON*E1000229"
}

Response

{
  "data": {
    "getChargepoint": {
      "connectors": [Connector],
      "connectorsFree": 123,
      "connectorsOccupied": 123,
      "connectorsTotal": 987,
      "connectorsUnavailable": 123,
      "createdAt": DateTime,
      "id": ID,
      "location": Location,
      "name": "xyz789",
      "publicName": "abc123",
      "updatedAt": DateTime
    }
  }
}

Queries

`getChargepoints`

Returns a list of Chargepoints with pagination (limit and offset). The absolute limit of a response is 1000.

Returns a PaginatedChargepoints!

Name	Description
`offset` - `Int`	Defines the starting point of the pagination
`limit` - `Int`	Defines the number of returned elements

Example

Query

query getChargepoints($offset: Int, $limit: Int) {
  getChargepoints(offset: $offset, limit: $limit) {
    chargepoints {
      ...ChargepointFragment
    }
    count
  }
}

Variables

{"offset": 987, "limit": 123}

Response

{
  "data": {
    "getChargepoints": {
      "chargepoints": [Chargepoint],
      "count": 987
    }
  }
}

Queries

`getChargingSession`

Returns a chargingsession by ID

Returns a Session

Name	Description
`id` - `ID!`	Session ID

Example

Query

query getChargingSession($id: ID!) {
  getChargingSession(id: $id) {
    cardId
    connector {
      ...SessionConnectorFragment
    }
    costs
    costsNet
    currency
    duration
    endTime
    id
    meterEnd
    meterStart
    meterTotal
    startTime
    status
    tariff
    taxAmount
  }
}

Variables

{"id": ID}

Response

{
  "data": {
    "getChargingSession": {
      "cardId": "abc123",
      "connector": SessionConnector,
      "costs": 5.11,
      "costsNet": 4.29,
      "currency": "EUR",
      "duration": 5400,
      "endTime": "2021-01-28T13:42:00.420Z",
      "id": ID,
      "meterEnd": 56000,
      "meterStart": 69100,
      "meterTotal": 13100,
      "startTime": "2021-01-28T12:12:00.420Z",
      "status": SessionStatus,
      "tariff": "xyz789",
      "taxAmount": 0.82
    }
  }
}

Queries

`getChargingSessions`

Returns a list of ChargingSessions with pagination (limit and offset) either by a contact or a particular card/authentication medium. The absolute limit of a response is 1000.

Returns [Session]!

Name	Description
`contactId` - `String!`	Unique identifier of a contact
`tagId` - `String`	Unique identifier of a charge card/authentication medium
`active` - `Boolean`	Return active sessions only
`offset` - `Int`	Defines the starting point of the pagination
`limit` - `Int`	Defines the number of returned elements

Example

Query

query getChargingSessions($contactId: String!, $tagId: String, $active: Boolean, $offset: Int, $limit: Int) {
  getChargingSessions(contactId: $contactId, tagId: $tagId, active: $active, offset: $offset, limit: $limit) {
    cardId
    connector {
      ...SessionConnectorFragment
    }
    costs
    costsNet
    currency
    duration
    endTime
    id
    meterEnd
    meterStart
    meterTotal
    startTime
    status
    tariff
    taxAmount
  }
}

Variables

{
  "contactId": "abc123",
  "tagId": "abc123",
  "active": false,
  "offset": 987,
  "limit": 123
}

Response

{
  "data": {
    "getChargingSessions": [
      {
        "cardId": "abc123",
        "connector": SessionConnector,
        "costs": 5.11,
        "costsNet": 4.29,
        "currency": "EUR",
        "duration": 5400,
        "endTime": "2021-01-28T13:42:00.420Z",
        "id": ID,
        "meterEnd": 56000,
        "meterStart": 69100,
        "meterTotal": 13100,
        "startTime": "2021-01-28T12:12:00.420Z",
        "status": SessionStatus,
        "tariff": "abc123",
        "taxAmount": 0.82
      }
    ]
  }
}

Queries

`getContact`

Returns a contact by id

Returns a Contact!

Name	Description
`id` - `ID!`	Unique contact ID

Example

Query

query getContact($id: ID!) {
  getContact(id: $id) {
    birthdate
    customerNumber
    email
    fax
    gender
    givenName
    id
    isCompany
    location {
      ...LocationFragment
    }
    name
    phone
  }
}

Variables

{"id": ID}

Response

{
  "data": {
    "getContact": {
      "birthdate": "2021-07-06T16:01:41.120Z",
      "customerNumber": "xyz789",
      "email": Email,
      "fax": "abc123",
      "gender": "abc123",
      "givenName": "xyz789",
      "id": ID,
      "isCompany": true,
      "location": Location,
      "name": "xyz789",
      "phone": "xyz789"
    }
  }
}

Queries

`getContacts`

Returns a list of Contacts with pagination (limit and offset). The absolute limit of a response is 1000.

Returns [Contact]

Name	Description
`offset` - `Int`	Defines the starting point of the pagination
`limit` - `Int`	Defines the number of returned elements

Example

Query

query getContacts($offset: Int, $limit: Int) {
  getContacts(offset: $offset, limit: $limit) {
    birthdate
    customerNumber
    email
    fax
    gender
    givenName
    id
    isCompany
    location {
      ...LocationFragment
    }
    name
    phone
  }
}

Variables

{"offset": 987, "limit": 987}

Response

{
  "data": {
    "getContacts": [
      {
        "birthdate": "2022-01-06T16:01:41.120Z",
        "customerNumber": "xyz789",
        "email": Email,
        "fax": "xyz789",
        "gender": "xyz789",
        "givenName": "xyz789",
        "id": ID,
        "isCompany": true,
        "location": Location,
        "name": "abc123",
        "phone": "xyz789"
      }
    ]
  }
}

Queries

`getPrice`

Returns the price information for a charging point with the given tagId

Returns a PriceInfo

Name	Description
`chargepoint` - `ID!`	Unique identifier of a chargepoint
`tagId` - `String`	Unique identifier of a charge card/authentication medium

Example

Query

query getPrice($chargepoint: ID!, $tagId: String) {
  getPrice(chargepoint: $chargepoint, tagId: $tagId) {
    currency
    name
    price
  }
}

Variables

{"chargepoint": ID, "tagId": "abc123"}

Response

{
  "data": {
    "getPrice": {"currency": "abc123", "name": "abc123", "price": 123.45}
  }
}

Mutations

The schema allows the following Mutations

`remoteStart`

Triggered the charging process

Returns a RemoteStartResponse!

Name	Description
`connectorId` - `String!`
`tagId` - `String!`

Example

Query

mutation remoteStart($connectorId: String!, $tagId: String!) {
  remoteStart(connectorId: $connectorId, tagId: $tagId) {
    message
    session
    status
  }
}

Variables

{"connectorId": "xyz789", "tagId": "abc123"}

Response

{
  "data": {
    "remoteStart": {
      "message": "abc123",
      "session": ID,
      "status": "xyz789"
    }
  }
}

Mutations

`remoteStop`

Stops the charging process with the given session

Returns a RemoteStopResponse!

Name	Description
`session` - `ID!`

Example

Query

mutation remoteStop($session: ID!) {
  remoteStop(session: $session) {
    message
    session
    status
  }
}

Variables

{"session": ID}

Response

{
  "data": {
    "remoteStop": {
      "message": "abc123",
      "session": ID,
      "status": "xyz789"
    }
  }
}

Mutations

`updateCard`

Update card information

Returns a Card!

Name	Description
`tagId` - `String!`	Unique identifier of a charge card/authentication medium
`name` - `String`	Name of the card user
`active` - `Boolean`	Activating or deactivating a card

Example

Query

mutation updateCard($tagId: String!, $name: String, $active: Boolean) {
  updateCard(tagId: $tagId, name: $name, active: $active) {
    active
    billingContact
    cardType
    contact
    name
    rate
    tagId
    validFrom
  }
}

Variables

{"tagId": "abc123", "name": "abc123", "active": true}

Response

{
  "data": {
    "updateCard": {
      "active": false,
      "billingContact": ID,
      "cardType": 123,
      "contact": ID,
      "name": "xyz789",
      "rate": "xyz789",
      "tagId": "xyz789",
      "validFrom": "2022-01-06T16:01:41.120Z"
    }
  }
}

Types

`Boolean`

The Boolean scalar type represents true or false.

Example

true

Types

`Card`

Represents a card and its properties

Field Name	Description
`active` - `Boolean`	Indicates whether the authentication medium (the card) is active/inactive.
`billingContact` - `ID`	Shows the billing contact
`cardType` - `Int`	Type of authentication medium (card).
`contact` - `ID`	Unique identifier of a contact
`name` - `String`	Name of the card user
`rate` - `String`	Shows the traif to which the card is assigned.
`tagId` - `String`	Unique identifier of a charge card/authentication medium.
`validFrom` - `Date`	Valid from e.g.: YYYY-MM-DD

Example

{
  "active": true,
  "billingContact": ID,
  "cardType": 123,
  "contact": ID,
  "name": "abc123",
  "rate": "abc123",
  "tagId": "xyz789",
  "validFrom": "2021-07-06T16:01:41.120Z"
}

Types

`Chargepoint`

Represents all parameters of a charging station, incl. the connectors

Field Name	Description
`connectors` - `[Connector]`	A list of the available charging connectors
`connectorsFree` - `Int`	Number of free charging connectors
`connectorsOccupied` - `Int`	Number of occupied charging connectors
`connectorsTotal` - `Int`	Total number of charging connectors available
`connectorsUnavailable` - `Int`	Number of unavailable charging connectors (e.g. due to faults).
`createdAt` - `DateTime`	Creation date of the Chargepoint
`id` - `ID!`	Unique identifier of the charging station that can be used for direct query.
`location` - `Location`	Location of the charging station
`name` - `String`	Internal name of the charging station
`publicName` - `String`	Public name of the charging station. This should be used for display in applications.
`updatedAt` - `DateTime`	Displays the last change date.

Example

{
  "connectors": [Connector],
  "connectorsFree": 987,
  "connectorsOccupied": 123,
  "connectorsTotal": 987,
  "connectorsUnavailable": 123,
  "createdAt": DateTime,
  "id": ID,
  "location": Location,
  "name": "xyz789",
  "publicName": "xyz789",
  "updatedAt": DateTime
}

Types

`Connector`

Represents all parameters of a single charging connector.

Field Name	Description
`evse` - `String`	The EVSE ID defines the unique identifier, a number and letter code of a QR code, of a charging point. e.g.: DECONE1000229
`id` - `ID!`	Unique identifier in the form of a id.
`name` - `String`	Name of the charging connector.
`status` - `ConnectorStatus`	The last status of a charging connector.
`type` - `ConnectorType`	The type of charging connector.

Example

{
  "evse": "DE*CON*E1000229",
  "id": ID,
  "name": "xyz789",
  "status": ConnectorStatus,
  "type": ConnectorType
}

Types

`ConnectorStatus`

The last status of a charging connector

Field Name	Description
`status` - `Status`	Status: Available, Occupied oder Faulted
`updatedAt` - `DateTime`	Last date of change of status

Example

{
  "status": Status,
  "updatedAt": DateTime
}

Types

`ConnectorType`

The type of charging connector

Field Name	Description
`currentType` - `String`	Current type AC / DC
`description` - `String`	Description of the connector Type
`maxPower` - `Float`	Maximum power of the charging connector
`name` - `String`	Name of the connector Type

Example

{
  "currentType": "abc123",
  "description": "abc123",
  "maxPower": 987.65,
  "name": "abc123"
}

Types

`Contact`

The contact represents all the information of the contact.

Field Name	Description
`birthdate` - `Date`	Represents the date of birth of a contact
`customerNumber` - `String`	Represents an individual customer number and is unique.
`email` - `Email`	E-Mail address
`fax` - `String`	Fax
`gender` - `String`	Gender of the contact for addressing in the app or messages.
`givenName` - `String`	Given name or first name of the contact
`id` - `ID!`	Unique identifier in the form of a id.
`isCompany` - `Boolean`	Indicates whether the contact is a company or a person.
`location` - `Location`	Address and place of contact
`name` - `String`	Name or surname of a contact
`phone` - `String`	Phone number

Example

{
  "birthdate": "2021-07-06T16:01:41.120Z",
  "customerNumber": "abc123",
  "email": Email,
  "fax": "abc123",
  "gender": "abc123",
  "givenName": "xyz789",
  "id": ID,
  "isCompany": true,
  "location": Location,
  "name": "xyz789",
  "phone": "abc123"
}

Types

`Date`

ISO8601 Date string in the format YYYY-MM-DD

Example

2021-01-28

Types

`DateTime`

ISO8601 date and time string in the format YYYY-MM-DDThh:mm:ss.sssZ

Example

2021-01-28T12:12:12.420Z

Types

`DefaultResponse`

Standard response

Field Name	Description
`status` - `Status`	Status

Example

{"status": Status}

Types

`Email`

An email address in the format local-part@domain-part as defined by RFC 822

Example

object

Types

`Float`

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example

987.65

Types

`ID`

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example

9d5566fa-9ad6-4bf9-9fc8-35cc3a308be7

Types

`Int`

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example

Types

`Location`

Location

Field Name	Description
`city` - `String`	City
`country` - `String`	Country
`lat` - `Float`	Latitude
`long` - `Float`	Longitude
`street` - `String`	Street
`zip` - `String`	Zip

Example

{
  "city": "abc123",
  "country": "abc123",
  "lat": 123.45,
  "long": 123.45,
  "street": "abc123",
  "zip": "abc123"
}

Types

`PaginatedChargepoints`

Represents charging station as a list

Field Name	Description
`chargepoints` - `[Chargepoint!]!`	Represents all parameters of a charging station, incl. the connectors
`count` - `Int`	Number of chargepoints

Example

{"chargepoints": [Chargepoint], "count": 123}

Types

`PriceInfo`

Price information

Field Name	Description
`currency` - `String`	Curency e.g.: EUR for euro
`name` - `String`
`price` - `Float`	Price per kwh in the specified currency

Example

{"currency": "xyz789", "name": "abc123", "price": 987.65}

Types

`RemoteStartResponse`

Response to remote start

Field Name	Description
`message` - `String`	Info message
`session` - `ID`	Unique identifier of a loading process that can be used for direct query.
`status` - `String`	Shows the status of the charging process that has been started.

Example

{"message": "xyz789", "session": ID, "status": "abc123"}

Types

`RemoteStopResponse`

Response to remote stop

Field Name	Description
`message` - `String`	Info message
`session` - `ID`	Unique identifier of a loading process that can be used for direct query.
`status` - `String`	Shows the status of the stopped charging process.

Example

{"message": "xyz789", "session": ID, "status": "abc123"}

Types

`Session`

Information about a charging process.

Field Name	Description
`cardId` - `String`	Unique identifier of the authentication medium that used.
`connector` - `SessionConnector`	Connector which was used during this session.
`costs` - `Float`	Total costs of the charging process.
`costsNet` - `Float`	Total costs VAT exluded of the charging process.
`currency` - `String`	Currency in which the charging process was calculated.
`duration` - `Int`	Duration of the charging process in seconds [s]
`endTime` - `DateTime`	End time of the charging process
`id` - `ID`	Unique identifier of a charging process that can be used for direct query.
`meterEnd` - `Int`	Energy meter when stopping the charging process
`meterStart` - `Int`	Energy meter when starting the charging process
`meterTotal` - `Int`	Amount of energy charged in watt hours [Wh]. Difference between meterStart and meterEnd.
`startTime` - `DateTime`	Start time of the charging process
`status` - `SessionStatus`	Shows the state of a session.
`tariff` - `String`	Name of the tariff used.
`taxAmount` - `Float`	Tax (VAT) amount included in total costs

Example

{
  "cardId": "abc123",
  "connector": SessionConnector,
  "costs": 5.11,
  "costsNet": 4.29,
  "currency": "EUR",
  "duration": 5400,
  "endTime": "2021-01-28T13:42:00.420Z",
  "id": ID,
  "meterEnd": 56000,
  "meterStart": 69100,
  "meterTotal": 13100,
  "startTime": "2021-01-28T12:12:00.420Z",
  "status": SessionStatus,
  "tariff": "abc123",
  "taxAmount": 0.82
}

Types

`SessionConnector`

Connector information

Field Name	Description
`connectorId` - `String`	Unique identifier of a connector
`connectorType` - `String`	The type of charging connector.
`evse` - `String`	The EVSE ID defines the unique identifier, a number and letter code of a QR code, of a charging point. e.g.: DECONE1000229

Example

{"connectorId": "xyz789", "connectorType": "abc123", "evse": "abc123"}

Types

`SessionStatus`

Shows the state of a session.

Enum Value	Description
`STARTED`	A charging process has been started and is still ongoing.
`STOPPED`	A charging process has been stopped.

Types

`Status`

Status of a charging station or charging connector

Enum Value	Description
`AVAILABLE`	Charging stations or charging connectors is available.
`FAULTED`	Charging stations or charging connectors is faulty
`OCCUPIED`	Charging stations or charging connectors is occupied.
`UNAVAILABLE`	Charging stations or charging connectors is not available..
`UNKNOWN`	The status of the charging station or the charging connector is unknown.

Types

`String`

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Documentation by Anvil SpectaQL