blitzortungc

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jun 2, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

README

Blitzortungc 🌩️

Go library for listening to lightning strike and thunderstorm events from blitzortung.org. Please make sure to read their terms of services before using this library. This library is not affiliated in any way with the blitzortung.org project.

blitzortung logo

The service provided by blitzortung.org is not an official authority for lightning or thunderstorm data. The data provided is only for private and entertainment purposes. The project blitzortung.org is for the contributors merely a voluntary leisure activity.

Installation

$ go get -u github.com/0x5a17ed/blitzortungc

Documentation

Index

Constants

This section is empty.

Variables

View Source
var UserAgent = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

UserAgent is the User-Agent header DefaultDialer sends on the WebSocket upgrade request. Override it at init time to identify your application to the upstream service. Custom Dialer implementations are responsible for setting their own header.

Functions

func Inflate

func Inflate(d []byte) ([]byte, error)

Inflate decodes the LZW-style UTF-8 stream the upstream service uses for its strike messages. Codes are encoded as UTF-8 runes: runes below 256 emit themselves as a single byte, and runes from 256 upward index a dictionary that grows as the stream is consumed, with the standard KωK edge case for codes that reference the entry about to be defined.

Returns an error if d contains an invalid UTF-8 byte sequence.

Types

type Client

type Client struct {
	// Handler is called for handling lightning strike events.
	Handler Handler

	// ErrorHook is called when the read hit an error while
	// processing server data.
	ErrorHook func(error)

	// DisableRemoteConfig disables fetching the live server list and
	// subscribe payload from blitzortung.org's JS at Run start. With
	// it set, the baked-in defaults are used unconditionally.
	DisableRemoteConfig bool

	// HTTPClient is used to fetch the upstream JS for remote config.
	// If nil, http.DefaultClient is used. Ignored when
	// DisableRemoteConfig is true.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

Client represents a client for the service of https://www.blitzortung.org/en/ for tracking lightning and thunderstorms in real time.

func (*Client) Run

func (c *Client) Run(ctx context.Context, dialer Dialer) error

Run runs the given client, connecting to the lightning events source server and tries to keep the connection alive. Calls Handler.HandleStrike for incoming events.

func (*Client) Shutdown

func (c *Client) Shutdown()

Shutdown shuts the client down cleanly and prevents it from reconnecting to the data source again.

type Dialer

type Dialer interface {
	Dial(ctx context.Context, urlStr string) (*websocket.Conn, *http.Response, error)
}

Dialer establishes the underlying WebSocket connection. Provide a custom implementation to inject HTTP headers, a custom HTTP client, or to mock the transport in tests. DefaultDialer dials with websocket.Dial and the package-level UserAgent applied.

var DefaultDialer Dialer = dialerFunc(func(ctx context.Context, urlStr string) (
	*websocket.Conn,
	*http.Response,
	error,
) {
	return websocket.Dial(ctx, urlStr, &websocket.DialOptions{
		HTTPHeader: http.Header{"User-Agent": []string{UserAgent}},
	})
})

DefaultDialer is the Dialer used when none is configured: it calls websocket.Dial with the package-level UserAgent applied.

type Handler

type Handler interface {
	HandleStrike(s *Strike)
}

type HandlerFunc

type HandlerFunc func(s *Strike)

func (HandlerFunc) HandleStrike

func (f HandlerFunc) HandleStrike(s *Strike)

type InflateError added in v0.2.0

type InflateError struct {
	Wrapped error
	RawData []byte
}

InflateError is reported via the Client's ErrorHook when an incoming WebSocket message can't be inflated (typically because it contains invalid UTF-8). RawData carries the original compressed payload.

func (InflateError) Error added in v0.2.0

func (e InflateError) Error() string

func (InflateError) Is added in v0.2.0

func (e InflateError) Is(target error) bool

func (InflateError) Unwrap added in v0.2.0

func (e InflateError) Unwrap() error

type Station

type Station struct {
	// Station that has reported the signal.
	ID int `json:"sta"`

	// Status of the signal.
	// bit 1 = polarity negative
	// bit 2 = polarity positive
	// bit 3 = signal is used for the computation
	Status int `json:"status"`

	// Time difference to the time of the lightning strike in nanoseconds.
	TimeDeltaValue int `json:"time"`

	Latitude  float64 `json:"lat"` // Latitude of the detector in degree (decimal).
	Longitude float64 `json:"lon"` // Longitude of the detector in degree (decimal).
	Altitude  int     `json:"alt"` // Altitude of the detector in meter.
}

Station represents a single station that reported a given lightning strike.

type Strike

type Strike struct {
	Status   *int `json:"status,omitempty"`
	Polarity int  `json:"pol"`

	Signals []Station `json:"sig"`

	TimeValue  big.Int `json:"time"`
	DelayValue float64 `json:"delay"`

	// MaxDeviationSpan is the maximal deviation span in nanoseconds.
	MaxDeviationSpan int `json:"mds"`
	// MaxCircularGap is the maximal circular gap in degree between two stations.
	MaxCircularGap *int `json:"mcg,omitempty"`

	Region    int     `json:"region"`
	Latitude  float64 `json:"lat"` // Latitude in degree (decimal).
	Longitude float64 `json:"lon"` // Longitude in degree (decimal).
	Altitude  int     `json:"alt"` // Altitude in meter.
}

Strike represents a single lightning strike as reported by the remote server.

func (Strike) Delay

func (s Strike) Delay() time.Duration

Delay interprets the DelayValue field as a time.Duration value.

func (Strike) Time

func (s Strike) Time() time.Time

Time interprets the TimeValue field as a time.Time value.

type UnmarshalError

type UnmarshalError struct {
	Wrapped error
	RawData []byte
}

func (UnmarshalError) Error

func (e UnmarshalError) Error() string

func (UnmarshalError) Is

func (e UnmarshalError) Is(target error) bool

func (UnmarshalError) Unwrap

func (e UnmarshalError) Unwrap() error

Directories

Path Synopsis
_example
cmd command
internal
upstream
Package upstream extracts the WebSocket server list and the initial subscribe payload from the blitzortung.org browser JS.
Package upstream extracts the WebSocket server list and the initial subscribe payload from the blitzortung.org browser JS.

Jump to

Keyboard shortcuts

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