fems

Documentation

Overview

Package fems is a client for the Fire Environment Mapping System (FEMS).

FEMS is the United States Forest Service system that archives RAWS weather and runs the National Fire Danger Rating System. It is the authoritative source of both the observations and the computed fire danger output, so it is the ground truth for a check of the nfdrs package.

This client reads two endpoints:

• Weather returns the RAWS weather observations as firewx.Station and firewx.Obs values. FEMS reports weather in Fahrenheit, inches, and miles per hour; the client converts to SI at the boundary.
• NFDR returns the computed NFDRS output for each hour: the dead and live fuel moistures, the Keetch-Byram Drought Index, and the ignition, energy release, spread, and burning indices.

A public request returns the most recent two weeks. The full archive needs an authenticated account, which this client does not support yet.

Reference: FEMS, https://fems.fs2c.usda.gov.

Index

• Constants
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) NFDR(ctx context.Context, req Request) ([]NFDROutput, error)
  • func (c *Client) Weather(ctx context.Context, req Request) ([]StationSeries, error)
• type Doer
• type NFDROutput
• type Option
  • func WithBaseURL(url string) Option
  • func WithHTTPClient(d Doer) Option
  • func WithUserAgent(ua string) Option
• type Request
• type StationSeries

Examples

• Client.NFDR

Constants

const DefaultBaseURL = "https://fems.fs2c.usda.gov/api/climatology"

DefaultBaseURL is the base URL of the FEMS climatology API.

Types

type Client

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

Client reads data from the FEMS climatology API. A public request needs no token and returns the most recent two weeks.

func New

func New(opts ...Option) *Client

New returns a Client. With no options, it uses the real API base URL and a standard HTTP client with a 60 second timeout.

func (*Client) NFDR

func (c *Client) NFDR(ctx context.Context, req Request) ([]NFDROutput, error)

NFDR reads the computed NFDRS output for the request and returns one NFDROutput per station per hour. This is the FEMS ground truth for a check of the nfdrs package.

Example

ExampleClient_NFDR shows how to read the computed NFDRS output. This is the FEMS ground truth: a caller compares it against the nfdrs package. A real caller uses fems.New() and the default base URL; this example points the client at a test server so it can run.

package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"

	"alpineworks.io/firewx/fetch/fems"
)

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		fmt.Fprint(w, "\"stationName\",\"observationTime\",\"fuelModelType\","+
			"\"energyReleaseComponent\",\"burningIndex\",\"stationId\"\n"+
			"\"GREENBASE\",\"2026-07-25T00:00:00Z\",\"Y\",27.91,23.61,20284\n")
	}))
	defer srv.Close()

	c := fems.New(fems.WithBaseURL(srv.URL), fems.WithHTTPClient(srv.Client()))

	out, err := c.NFDR(context.Background(), fems.Request{
		Stations: []string{"20284"},
		Start:    time.Date(2026, 7, 25, 0, 0, 0, 0, time.UTC),
		End:      time.Date(2026, 7, 26, 0, 0, 0, 0, time.UTC),
	})
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	erc, _ := out[0].EnergyReleaseComponent.Get()
	fmt.Printf("%s ERC=%.1f\n", out[0].StationID, erc)
}

Output:
20284 ERC=27.9

func (*Client) Weather

func (c *Client) Weather(ctx context.Context, req Request) ([]StationSeries, error)

Weather reads the RAWS weather observations for the request and returns one StationSeries per station. FEMS reports weather in Fahrenheit, inches, and miles per hour; the client converts each value to SI.

type Doer

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

Doer sends an HTTP request and returns the response. The standard *http.Client satisfies it. A test can give a stub instead.

type NFDROutput

type NFDROutput struct {
	StationID   string
	StationName string
	Time        time.Time

	// FuelModel is the NFDRS fuel model letter, for example "Y".
	FuelModel string

	OneHourFuelMoisture      firewx.Opt[firewx.Percent]
	TenHourFuelMoisture      firewx.Opt[firewx.Percent]
	HundredHourFuelMoisture  firewx.Opt[firewx.Percent]
	ThousandHourFuelMoisture firewx.Opt[firewx.Percent]

	WoodyFuelMoisture      firewx.Opt[firewx.Percent]
	HerbaceousFuelMoisture firewx.Opt[firewx.Percent]

	// KBDI is the Keetch-Byram Drought Index, 0 to 800.
	KBDI firewx.Opt[float64]
	// GSI is the Growing Season Index, 0 to 1.
	GSI firewx.Opt[float64]

	IgnitionComponent      firewx.Opt[float64]
	EnergyReleaseComponent firewx.Opt[float64]
	SpreadComponent        firewx.Opt[float64]
	BurningIndex           firewx.Opt[float64]
}

NFDROutput is one hour of computed NFDRS output for one station. Each value is optional, because a station may not report every field. The fuel moistures are a percentage; the four indices and the two drought and greenness measures are dimensionless.

type Option

type Option func(*Client)

Option sets one field of a Client. Give a list of Option values to New.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL sets the base URL. The default is DefaultBaseURL. Give a test server URL to test without the real API.

func WithHTTPClient

func WithHTTPClient(d Doer) Option

WithHTTPClient sets the HTTP client. The default is a standard client with a 60 second timeout, because a FEMS download can be large. Give a stub to test without a network.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header for every request.

type Request

type Request struct {
	Stations   []string
	Start, End time.Time
}

Request asks for the data of one or more stations over a time range. Start and End are in any time zone; the client converts them to UTC for the API.

type StationSeries

type StationSeries struct {
	Station      firewx.Station
	Observations []firewx.Obs
}

StationSeries is the observations of one station, with the station metadata. The weather download does not include the station coordinates, so the Latitude, Longitude, and Elevation of the Station are zero. Use the FEMS site metadata for the coordinates.