@goodcharge/sdk

Publish a charging station and its live occupancy to goodcharge.

Requires Node.js 24 or later. No runtime dependency.

Before you start

Create an account, turn on two-factor authentication, add a station and get an API key — see Create an account.

Your first station is reviewed by the goodcharge team before it appears in the app. Later stations appear as soon as they are published.

Install

npm install @goodcharge/sdk

Quick start

import { GoodchargeStation } from '@goodcharge/sdk';

const station = new GoodchargeStation({ apiKey: process.env.GOODCHARGE_API_KEY! });

await station.publish({
  metadata: {
    gps_coordinates: { latitude: 45.764, longitude: 4.835 },
    address: '1 place Bellecour',
    city: 'Lyon',
    postal_code: '69002',
    country: 'FR',
    private: { level: 'public' },
  },
  charging_points: [{ plug_type: 'type_2', power: 22, status: 'free' }],
  pricing: { connection_fee: 0.5, price_per_kilowatt_hour: 0.35, currency: 'EUR' },
});

// When a car plugs in:
await station.updatePoints([{ position: 1, status: 'occupied' }]);

// When nothing changes, keep the station alive (goodcharge flags it after 15 minutes of silence):
const stop = station.startHeartbeat({ onError: console.error });

Calls on one GoodchargeStation are serialised: each one waits for whichever call is already in flight to settle before it starts its own first attempt, so a retried write can never land after a newer call, and a heartbeat never races an app call. There is nothing to await or lock yourself — just call the methods in order.

Monitoring

import { createServer } from 'node:http';
import { metricsHandler } from '@goodcharge/sdk';

createServer(metricsHandler([station])).listen(9464, '127.0.0.1');

Alert rules and a Grafana dashboard ship in monitoring/. See Monitoring with Prometheus.

Documentation

The full reference — constructor options, methods, station fields, status values and error codes — lives at docs.goodcharge.app.

Licence

Proprietary: you may use this package, unmodified, only to access goodcharge APIs. See LICENSE.