geeViz.fsInsights.lcms¶

LCMS API client — Landscape Change Monitoring System.

Wall-to-wall 30 m maps of land cover, land use, and change across the conterminous US, Alaska, Hawaii and Puerto Rico, currently spanning 1985-2025. Public, no authentication.

Three things about this API shape the client:

It answers errors with HTTP 200. An unknown summary area returns a ParameterError inside a 200 body, so a client checking .ok reads failure as success and returns nothing. geeViz.fsInsights._http inspects the payload; that check is the reason it exists.

Trailing slashes matter. /release 301-redirects while /release/ returns data. Every path here carries its slash.

Products carry their own palettes. Each class comes back with a ClassValue and a ClassPalette, which means visualization parameters can be built from the API rather than from constants that drift out of sync at every release. See lcms_vis_params().

Areas are precomputed — 3,643 of them (counties, ranger districts, plus CONUS and All-Lands rollups). There is no runtime zonal-statistics engine behind this API: bbox, geojson and geometry are all rejected, and POST returns 403. For an arbitrary polygon, use the Earth Engine copies of the same products, which is what lcms_summary() does when handed a geometry.

Functions

`latest_release`([product])	Resolve to a concrete version string, e.g. `2025-11`.
`lcms_classes`(product[, release])	Class table for one product — name, pixel value, and palette hex.
`lcms_products`([release, refresh])	Products in a release, each with its full class list.
`lcms_releases`(*[, product, refresh])	Every published LCMS release, newest first.
`lcms_summary`([product, state, county, ...])	Class areas for an area and period, as a tidy frame.
`lcms_summary_areas`([release, type, refresh])	The precomputed areas this API can summarize.
`lcms_vis_params`(product[, release])	Build geeViz/Earth Engine visualization parameters for a product.
`release_products`([release])	Product names published by one release (default: newest overall).

geeViz.fsInsights.lcms.lcms_releases(*, product: str = '', refresh: bool = False) → List[dict][source]¶

Every published LCMS release, newest first.

Each entry carries VersionNumber, StartYear, EndYear, Products and StudyAreas.

Releases are not interchangeable, in two ways that bite:

Products differ. 2025-11 carries Change / Land_Cover / Land_Use; 2025-6 is a tree-canopy release carrying only NLCD_Percent_Tree_Canopy_Cover. “The latest release” is therefore ambiguous unless you say latest of what — see latest_release().
Study areas differ, and not monotonically. 2024-10 covers CONUS, AK, HAWAII and PRUSVI; 2025-11 covers only CONUS and AK. Work in Hawaii or Puerto Rico has to pin an older release, which is the opposite of the usual advice.

Note also that 2022-8 reports SummaryAreaCount = 0 — it has no summary areas, so the API cannot answer area queries against it even though it lists products.

Parameters:: product – Keep only releases that publish this product.

geeViz.fsInsights.lcms.release_products(release: str = '') → List[str][source]¶: Product names published by one release (default: newest overall).

geeViz.fsInsights.lcms.latest_release(product: str = '') → str[source]¶

Resolve to a concrete version string, e.g. 2025-11.

Parameters:: product – Resolve to the newest release carrying this product. Without it you get the newest release overall, which may not publish what you are about to ask for — 2025-6 is newer than 2024-10 but has no Land_Cover.

Pinning matters beyond that. Caching under the key latest means a new release silently changes the answer to a question asked last year; resolving to a version once keeps an old analysis reproducible.

geeViz.fsInsights.lcms.lcms_products(release: str = '', *, refresh: bool = False) → List[dict][source]¶

Products in a release, each with its full class list.

Currently Change, Land_Cover and Land_Use.

geeViz.fsInsights.lcms.lcms_classes(product: str, release: str = '') → Any[source]¶

Class table for one product — name, pixel value, and palette hex.

Returns a pandas.DataFrame with class_name, class_value and palette.

Raises:: ValueError – The release does not publish this product, naming the releases that do.

geeViz.fsInsights.lcms.lcms_vis_params(product: str, release: str = '') → dict[source]¶

Build geeViz/Earth Engine visualization parameters for a product.

Returns a dict with min, max, palette and classLegendDict, ready to hand to Map.addLayer:

Map.addLayer(lcms_change, fs.lcms_vis_params("Change"), "LCMS Change")

Taking the palette from the API rather than a hardcoded constant means the legend cannot drift out of sync with the release — the classes and their colors arrive from the same place as the data.

The palette is emitted as a dense, value-ordered list so it lines up with a contiguous min..``max`` range. Gaps in the class values are filled with a neutral grey rather than silently shifting every subsequent color, which is the failure mode that makes a legend look right and read wrong.

geeViz.fsInsights.lcms.lcms_summary_areas(release: str = '', *, type: str = '', refresh: bool = False) → Any[source]¶

The precomputed areas this API can summarize.

3,643 of them in release 2025-11: 3,137 US counties, 502 ranger districts, and four rollups (political and Forest Service, CONUS and All-Lands).

Parameters:

release – Release version; defaults to latest.
type – Filter on area type, e.g. "US-COUNTIES" or "RANGER-DISTRICTS".

geeViz.fsInsights.lcms.lcms_summary(product: str = 'Land_Cover', *, state: str = '', county: str = '', region: str = '', forest: str = '', district: str = '', year: int | None = None, startyear: int | None = None, endyear: int | None = None, geometry: Any = None, scale: int = 30, release: str = '') → Any[source]¶

Class areas for an area and period, as a tidy frame.

Dispatches on what it is given:

A named area (state/county, or region/forest/ district) goes to the LCMS API — instant, precomputed, and no Earth Engine authentication required.
A geometry goes to Earth Engine, computing the same class areas over an arbitrary polygon. Slower, needs EE initialized, and only available when geometry is passed.

The returned frame records which backend produced it, because the two are not guaranteed to agree to the pixel and a reader should not have to guess.

Parameters:

product – "Land_Cover", "Land_Use" or "Change".
state – State name. Required when county is given.
county – County name.
region – Forest Service units. district requires forest.
forest – Forest Service units. district requires forest.
district – Forest Service units. district requires forest.
year – Single year. Omit for the full time series — the whole 1985-2025 range is ~64 KB, small enough to fetch eagerly.
startyear – Inclusive year range.
endyear – Inclusive year range.
geometry – An ee.Geometry / ee.Feature / ee.FeatureCollection. Routes to the Earth Engine backend.
scale – Reduction scale in meters for the EE backend. LCMS is a 30 m product; coarsening trades accuracy for speed.
release – Release version; defaults to latest.

Returns:

pandas.DataFrame with year, class_name, square_meters, acres, hectares, product, area, source.