govee

package module
v0.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 3, 2026 License: MIT Imports: 7 Imported by: 0

README

govee-go

An unofficial Go client library for the Govee Developer REST API, with an emphasis on simplicity.

Installation

go get github.com/DTCurrie/govee-go

Getting an API Key

  1. Open the Govee Home app on your phone.
  2. Go to Profile → Settings → Apply for API Key.
  3. Submit your information and wait for the key to arrive by email.

Usage

package main

import (
    "context"
    "fmt"
    "log"

    govee "github.com/DTCurrie/govee-go"
)

func main() {
    client := govee.New("your-api-key")

    devices, err := client.GetDevices(context.Background())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Found %d devices\n", len(devices))

    for _, d := range devices {
        fmt.Printf("  %s (%s) — %s\n", d.DeviceName, d.Model, d.DeviceID)
    }

    // Turn on the first device
    if len(devices) > 0 {
        d := devices[0]
        if err := client.TurnOn(context.Background(), d.DeviceID, d.Model); err != nil {
            log.Fatal(err)
        }

        // Set brightness to 75%
        client.SetBrightness(context.Background(), d.DeviceID, d.Model, 75)

        // Set color to orange
        client.SetColor(context.Background(), d.DeviceID, d.Model, 255, 165, 0)

        // Set color temperature to daylight (6500K)
        client.SetColorTemp(context.Background(), d.DeviceID, d.Model, 6500)
    }
}

API Reference

Creating a Client
client := govee.New(apiKey string, opts ...Option)

Available options:

Option Description
govee.WithBaseURL(url string) Override the API base URL (useful for testing)
govee.WithHTTPClient(hc *http.Client) Replace the default HTTP client
Device Discovery
devices, err := client.GetDevices(ctx context.Context) ([]Device, error)

Returns all devices associated with the API key. Each Device includes:

Field Type Description
DeviceID string MAC address, used in all control/state calls
Model string Product model (e.g. "H6159")
DeviceName string User-assigned name from the Govee app
Controllable bool Whether the device accepts control commands
Retrievable bool Whether the device state can be queried
SupportCmds []string Commands the device accepts: "turn", "brightness", "color", "colorTem"
Properties.ColorTemp *ColorTemRange Color temperature range in Kelvin (nil if not supported)

Use device.SupportsCmd("color") to check command support.

Querying Device State
state, err := client.GetDeviceState(ctx context.Context, deviceID, model string) (*DeviceState, error)

Only available when device.Retrievable == true. Returns:

Field Type Description
Online bool Whether the device is reachable (cached; may be stale)
PowerState string "on" or "off"
Brightness int Current brightness (0–100)
Color *Color Current RGB color (nil if not in color mode)
ColorTemp int Current color temperature in Kelvin (0 if not in color temp mode)
Controlling Devices

All control methods require deviceID (MAC address) and model.

err = client.TurnOn(ctx, deviceID, model string) error
err = client.TurnOff(ctx, deviceID, model string) error
err = client.SetBrightness(ctx, deviceID, model string, brightness int) error  // 0-100
err = client.SetColor(ctx, deviceID, model string, r, g, b int) error          // 0-255 per channel
err = client.SetColorTemp(ctx, deviceID, model string, kelvin int) error
Error Handling

API errors are returned as *APIError:

if err != nil {
    var apiErr *govee.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API error %d: %s\n", apiErr.Code, apiErr.Message)
    }
}

Rate Limits

Scope Limit
All APIs combined 10,000 requests/day
GetDevices 10 requests/minute
GetDeviceState 10 requests/minute per device
Control commands 10 requests/minute per device

License

MIT — see LICENSE.

Documentation

Overview

Package govee provides a Go client for the Govee Developer REST API v1. It supports listing devices, querying device state, and sending control commands (on/off, brightness, RGB color, color temperature).

Usage:

client := govee.New("your-api-key")
devices, err := client.GetDevices(ctx)
err = client.TurnOn(ctx, devices[0].DeviceID, devices[0].Model)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	Code    int
	Message string
}

APIError is returned when the Govee API responds with a non-200 status code.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a Govee API client. Create one with New().

func New

func New(apiKey string, opts ...Option) *Client

New creates a new Govee API client authenticated with the given API key.

func (*Client) GetDeviceState

func (c *Client) GetDeviceState(ctx context.Context, deviceID, model string) (*DeviceState, error)

GetDeviceState queries the current state of a device. Only devices with Retrievable=true return useful state. Note: the "online" field is cached on Govee's side and may be stale.

func (*Client) GetDevices

func (c *Client) GetDevices(ctx context.Context) ([]Device, error)

GetDevices returns all Govee devices associated with the API key.

func (*Client) SetBrightness

func (c *Client) SetBrightness(ctx context.Context, deviceID, model string, brightness int) error

SetBrightness sets the brightness of the device (0–100). A value of 0 turns the device off.

func (*Client) SetColor

func (c *Client) SetColor(ctx context.Context, deviceID, model string, r, g, b int) error

SetColor sets the RGB color of the device. Each channel is 0–255.

func (*Client) SetColorTemp

func (c *Client) SetColorTemp(ctx context.Context, deviceID, model string, kelvin int) error

SetColorTemp sets the color temperature of the device in Kelvin. The valid range is device-specific (reported in DeviceProperties.ColorTemp).

func (*Client) TurnOff

func (c *Client) TurnOff(ctx context.Context, deviceID, model string) error

TurnOff turns the device off.

func (*Client) TurnOn

func (c *Client) TurnOn(ctx context.Context, deviceID, model string) error

TurnOn turns the device on.

type Color

type Color struct {
	R int `json:"r"`
	G int `json:"g"`
	B int `json:"b"`
}

Color represents an RGB color value.

type ColorTempRange

type ColorTempRange struct {
	Min int `json:"min"`
	Max int `json:"max"`
}

ColorTempRange is the supported color temperature range for a device, in Kelvin.

type Device

type Device struct {
	// DeviceID is the MAC address of the device, used to identify it in control and state requests.
	DeviceID string `json:"device"`
	// Model is the product model string (e.g. "H6159").
	Model string `json:"model"`
	// DeviceName is the user-assigned name from the Govee app.
	DeviceName string `json:"deviceName"`
	// Controllable is true when the device accepts control commands.
	Controllable bool `json:"controllable"`
	// Retrievable is true when the device state can be queried.
	Retrievable bool `json:"retrievable"`
	// SupportCmds lists the commands the device accepts: "turn", "brightness", "color", "colorTem".
	SupportCmds []string `json:"supportCmds"`
	// Properties holds optional per-device property constraints.
	Properties DeviceProperties `json:"properties"`
}

Device represents a Govee smart device returned by the API.

func (Device) SupportsCmd

func (d Device) SupportsCmd(cmd string) bool

SupportsCmd reports whether the device supports the given command name.

type DeviceProperties

type DeviceProperties struct {
	// ColorTemp is non-nil when the device supports the "colorTemp" command.
	ColorTemp *ColorTempRange `json:"colorTemp,omitempty"`
}

DeviceProperties holds optional per-device constraints returned by DeviceList.

type DeviceState

type DeviceState struct {
	// Online indicates whether the device is reachable. Note: this is cached by
	// the Govee API and may be stale; control commands should still be attempted
	// even when Online is false.
	Online bool
	// PowerState is "on" or "off".
	PowerState string
	// Brightness is the current brightness level (0–100). 0 means off or unknown.
	Brightness int
	// Color is the current RGB color, or nil if not reported.
	Color *Color
	// ColorTemp is the current color temperature in Kelvin, or 0 if not reported.
	ColorTemp int
}

DeviceState is the current reported state of a device.

type Option

type Option func(*Client)

Option is a functional option for configuring a Client.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL overrides the default API base URL. Useful for testing.

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient replaces the default *http.Client. Useful for custom transports or timeouts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL