GraphQL Reference

This page provides technical specifics about the GraphQL API. To get an introduction to out, go ahead and visit the GraphQL Tutorial.

GraphiQL Console

Introspect the Auto API schema easily with the GraphiQL console.

Table of Contents

Endpoint

The GraphQL API has only a single endpoint that accepts POST requests with the following headers.

Endpoint URL

The GraphQL URL is https://sandbox.graphql-api.high-mobility.com/v1 when working with the car emulators and https://graphql-api.high-mobility.com/v1 for cars in production mode.

Content-Type: application/json
Accept: application/json
Authorization: Bearer JWT_TOKEN

Query

Schema Inspection

The schema can be inspected to find out more about it's datapoints and types.
The query is executed against the schema and information regarding the schema is returned in the response for evaluation.

To get the types available in the schema, the types field can be queried with name, kind and fields. In addition fields needs a scalar like name to return a specific value (GraphQL queries must end with a scalar).
Besides the __schema, there are numerous other fields in the introspection system to inspect the schema, like __Type, __TypeKind, __Field, __InputValue, __EnumValue, __Directive.

Example

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

Query

Queries currently only support query type requests, not mutation-s. The structure is based on AutoAPI and is divided into capabilities, their properties and property components.

The property components-fields are data, timestamp, failure and availability.

Data

Some properties output a simple scalar value in the data field, for example:

...
    batteryLevel {
      data
    }

While others can be more complex, like custom types.

...
    departureTimes {
      data {
        state
        time {
          hour
          minute
        }
      }
    }

Or measurement types with a unit:

...
    estimatedRange {
      data {
        unit
        value
      }
    }

Example

{
  "data": {
    "charging": {
      "batteryLevel": {
        "data": 0.5
      },

      "departureTimes": [
        {
          "data": {
            "state": "active",
            "time": {
              "minute": 32,
              "hour": 16
            }
          }
        },
        ...
      ],

      "estimatedRange": {
        "data": {
          "value": 567.89,
          "unit": "km"
        }
      }
    }
  }
}

Timestamp

The timestamp field outputs the time the value was last updated or changed.
It's returned as a ISO 8601 string formated as yyyy-MM-dd'T'HH:mm:ss.SSSZ.

Example:

...
    batteryLevel {
      timestamp
      data
    }

Example

{
  "data": {
    "charging": {
      "batteryLevel": {
        "data": 0.5,
        "timestamp": "2021-02-03T14:31:00.000+0100"
      }
    }
  }
}

Failure

The failure field outputs a failure if the property encountered any, or null if there was no failure.

The failure custom type has 2 subfields description and reason that can be requested (at least 1 is required), for example:

...
    preconditioningDepartureEnabled {
      failure {
        description
        reason
      }
      data
    }

Example

{
  "data": {
    "charging": {
      "preconditioningDepartureEnabled": {
        "failure": {
          "description": "The description for the failure",
          "reason": "unauthorized"
        },
        "data": null
      }
    }
  }
}

Availability

COMING SOON

The possibility to retrieve the availability of a data point with the GraphQL API is coming soon.

The availability field outputs information about a property's rate limit and update rate.

The custom type exposes fields for appliesPer, rateLimit and updateRate, for example:

...
    batteryCurrent {
      availability {
        appliesPer
        rateLimit {
          unit
          value
        }
        updateRate
      }
    }

Example

{
  "data": {
    "charging": {
      "batteryCurrent": {
        "appliesPer": "vehicle",
        "rateLimit": {
          "unit": "Hz",
          "value": 1.0
        },
        "updateRate": "tripHigh"
      }
    }
  }
}