TeslaMateApi

TeslaMateApi is a RESTful API to get data collected by self-hosted data logger TeslaMate in JSON.

Written in Golang
Data is collected from TeslaMate Postgres database and local MQTT Broker
Endpoints return data in JSON format
Send commands to your Tesla through the TeslaMateApi

How to use
- Docker-compose
- Environment variables
API documentation
Security information
Credits

How to use

You can either use it in a Docker container or go download the code and deploy it yourself on any server.

Docker-compose

If you run the simple Docker deployment of TeslaMate, then adding this will do the trick. You'll have TeslaMateApi exposed at port 8080 locally then.

services:
  teslamateapi:
    image: tobiasehlert/teslamateapi:latest
    restart: always
    depends_on:
      - database
    environment:
      - ENCRYPTION_KEY=MySuperSecretEncryptionKey
      - DATABASE_USER=teslamate
      - DATABASE_PASS=secret
      - DATABASE_NAME=teslamate
      - DATABASE_HOST=database
      - MQTT_HOST=mosquitto
      - TZ=Europe/Berlin
    ports:
      - 8080:8080

If you are using TeslaMate Traefik setup in Docker with environment variables file (.env), then you can simply add this section to the services: section of the docker-compose.yml file:

services:
  teslamateapi:
    image: tobiasehlert/teslamateapi:latest
    restart: always
    depends_on:
      - database
    environment:
      - ENCRYPTION_KEY=${TM_ENCRYPTION_KEY}
      - DATABASE_USER=${TM_DB_USER}
      - DATABASE_PASS=${TM_DB_PASS}
      - DATABASE_NAME=${TM_DB_NAME}
      - DATABASE_HOST=database
      - MQTT_HOST=mosquitto
      - TZ=${TM_TZ}
    labels:
      - "traefik.enable=true"
      - "traefik.port=8080"
      - "traefik.http.middlewares.redirect.redirectscheme.scheme=https"
      - "traefik.http.middlewares.teslamateapi-auth.basicauth.realm=teslamateapi"
      - "traefik.http.middlewares.teslamateapi-auth.basicauth.usersfile=/auth/.htpasswd"
      - "traefik.http.routers.teslamateapi-insecure.rule=Host(`${FQDN_TM}`)"
      - "traefik.http.routers.teslamateapi-insecure.middlewares=redirect"
      - "traefik.http.routers.teslamateapi.rule=Host(`${FQDN_TM}`) && (Path(`/api`) || PathPrefix(`/api/`))"
      - "traefik.http.routers.teslamateapi.entrypoints=websecure"
      - "traefik.http.routers.teslamateapi.middlewares=teslamateapi-auth"
      - "traefik.http.routers.teslamateapi.tls.certresolver=tmhttpchallenge"

In this case, the TeslaMateApi would be accessible at teslamate.example.com/api/

Environment variables

Basically the same environment variables for the database, mqqt and timezone need to be set for TeslaMateApi as you have for TeslaMate.

Required environment variables (even if there are some default values available)

| Variable | Type | Default | | ------------------ | ------ | --------------- | | DATABASE_USER | string | teslamate | | DATABASE_PASS | string | secret | | DATABASE_NAME | string | teslamate | | DATABASE_HOST | string | database | | ENCRYPTION_KEY | string | | | MQTT_HOST | string | mosquitto | | TZ | string | Europe/Berlin |

Optional environment variables

| Variable | ----------------------------- | TESLAMATE_SSL | TESLAMATE_HOST | TESLAMATE_PORT | API_TOKEN | API_TOKEN_DISABLE | DATABASE_PORT | DATABASE_TIMEOUT | DATABASE_SSL | DATABASE_SSL_CA_CERT_FILE | DEBUG_MODE | DISABLE_MQTT | MQTT_TLS | MQTT_PORT | MQTT_USERNAME | MQTT_PASSWORD | MQTT_NAMESPACE | MQTT_CLIENTID | TESLA_API_HOST | Type | Default | | ------- | ----------------------------- | | boolean | false | | string | teslamate | | string | 4000 | | string | | | string | false | | integer | 5432 | | integer | 60000 | | string | disable | | string | | | boolean | false | | boolean | false | | boolean | false | | integer | 1883 (if TLS is true: 8883) | | string | | | string | | | string | | | string | 4 char random string | | string | retrieved by access token |

Commands environment variables

| Variable | Type | Default | | --------------------------- | ------- | ----------------- | | ENABLE_COMMANDS | boolean | false | | COMMANDS_ALL | boolean | false | | COMMANDS_ALLOWLIST | string | allow_list.json | | COMMANDS_LOGGING | boolean | false | | COMMANDS_WAKE | boolean | false | | COMMANDS_ALERT | boolean | false | | COMMANDS_REMOTESTART | boolean | false | | COMMANDS_HOMELINK | boolean | false | | COMMANDS_SPEEDLIMIT | boolean | false | | COMMANDS_VALET | boolean | false | | COMMANDS_SENTRYMODE | boolean | false | | COMMANDS_DOORS | boolean | false | | COMMANDS_TRUNK | boolean | false | | COMMANDS_WINDOWS | boolean | false | | COMMANDS_SUNROOF | boolean | false | | COMMANDS_CHARGING | boolean | false | | COMMANDS_CLIMATE | boolean | false | | COMMANDS_MEDIA | boolean | false | | COMMANDS_SHARING | boolean | false | | COMMANDS_SOFTWAREUPDATE | boolean | false | | COMMANDS_UNKNOWN | boolean | false |

API documentation

More detailed documentation of every endpoint will come..

Available endpoints

GET /api
GET /api/v1
GET /api/v1/cars
GET /api/v1/cars/:CarID
GET /api/v1/cars/:CarID/battery-health
GET /api/v1/cars/:CarID/charges
- Supported parameters:
  - startDate (optional, use canonical UTC format in RFC3339)
  - endDate (optional, use canonical UTC format in RFC3339)
GET /api/v1/cars/:CarID/charges/current
GET /api/v1/cars/:CarID/charges/:ChargeID
GET /api/v1/cars/:CarID/command
POST /api/v1/cars/:CarID/command/:Command
GET /api/v1/cars/:CarID/drives
- Supported parameters:
  - startDate (optional, use canonical UTC format in RFC3339)
  - endDate (optional, use canonical UTC format in RFC3339)
  - minDistance (optional, filter by minimum trip distance, units based on TeslaMate settings)
  - maxDistance (optional, filter by maximum trip distance, units based on TeslaMate settings)
GET /api/v1/cars/:CarID/drives/:DriveID
PUT /api/v1/cars/:CarID/logging/:Command
GET /api/v1/cars/:CarID/logging
GET /api/v1/cars/:CarID/status
GET /api/v1/cars/:CarID/updates
POST /api/v1/cars/:CarID/wake_up
GET /api/v1/globalsettings
GET /api/healthz
GET /api/ping
GET /api/readyz

[!TIP] Canonical UTC format in RFC3339, e.g. 2006-01-02T15:04:05Z or 2006-01-02T15:04:05+07:00

Authentication

If you want to use command or logging endpoints such as /api/v1/cars/:CarID/command/:Command, /api/v1/cars/:CarID/wake_up, or /api/v1/cars/:CarID/logging/:Command you need to add authentication to your request.

You need to specify a token yourself (called API_TOKEN) in the environment variables file, to set it. The token has the requirement to be a minimum of 32 characters long.

There are two options available for authentication to be done.

Adding extra header Authorization: Bearer <token> to your request. (recommended option)
Adding URI parameter ?token=<token> to the endpoint you try to reach. (not a good option)

* Note: If you use the second option and your logs get compromised, your token will be leaked.

Commands

Commands are not enabled by default.

You need to enable them in your environment variables (with ENABLE_COMMANDS=true) and you need to specify which commands you want to use as well.

There

Teslamateapi

Install / Use

README