geeViz.getSummaryAreasLib

Functions for retrieving common summary and study area FeatureCollections.

geeViz.getSummaryAreasLib provides helpers that return filtered ee.FeatureCollection objects for political boundaries, USFS administrative units, census geographies, buildings, roads, protected areas, and more. Every public function accepts an area parameter (an ee.FeatureCollection, ee.Feature, or ee.Geometry) that is used to spatially filter the result.

Functions

getAdminBoundaries([area, level, source, name])

Return administrative boundaries at a given level.

getAdminNameProperty([level, source])

Return the feature property name that contains the admin unit name.

getBuildings(area[, source])

Return building footprints that intersect area.

getProtectedAreas([area, iucn_cat, ...])

Return WDPA protected area polygons.

getRoads(area[, source, year])

Return road features that intersect area.

getUSBlockGroups([area])

Return TIGER 2020 census block groups.

getUSCensusBlocks([area])

Return TIGER 2020 census blocks.

getUSCensusTracts([area])

Return TIGER 2020 census tracts.

getUSCounties([area, state_fips, ...])

Return US county boundaries, with flexible filtering.

getUSFSDistricts([area, forest_name, ...])

Return USFS Ranger District boundaries.

getUSFSForests([area, region, forest_name])

Return USFS National Forest boundaries.

getUSFSRegions([area, region])

Return USFS region boundaries.

getUSNationalParks([area, name, park_names, ...])

Return US National Park polygons (IUCN II + ISO3=USA).

getUSStates([area, state_abbr, state_fips])

Return US state boundaries (TIGER 2018).

getUSUrbanAreas([area])

Return TIGER 2024 urban area boundaries.

simple_buffer(geom[, size])

Create a square buffer around a point using simple coordinate arithmetic.
geeViz.getSummaryAreasLib.simple_buffer(geom, size=15000)[source]

Create a square buffer around a point using simple coordinate arithmetic.

A lightweight alternative to ee.Geometry.buffer() that avoids the server-side geodesic circle computation. Transforms the point to EPSG:3857 (Web Mercator), applies a latitude-corrected offset so that size represents true ground meters, and returns the polygon in EPSG:3857.

Accepts a point in any projection — it will be transformed to EPSG:3857 internally.

Parameters:

  • geom (ee.Geometry) – A point geometry in any projection.

  • size (int or float, optional) – Half-width of the square in meters on the ground. The resulting square spans 2 * size on each side. Defaults to 15000 (producing a 30 km x 30 km square).

Returns:

A square polygon centered on the input point, defined in EPSG:3857.

Return type:

ee.Geometry.Polygon

Example

>>> pt = ee.Geometry.Point([-111.5, 40.5])
>>> square = simple_buffer(pt, size=5000)  # 10 km x 10 km
geeViz.getSummaryAreasLib.getAdminBoundaries(area=None, level=0, source='geob', name=None)[source]

Return administrative boundaries at a given level.

When area is provided, results are filtered to boundaries that intersect it. When None, all boundaries at the level are returned. When name is provided, results are filtered to the boundary whose name (per the source’s name property) equals or contains name.

Levels follow the standard admin hierarchy:

  • 0 — Countries

  • 1 — States / provinces

  • 2 — Districts / counties / municipalities

  • 3 — Sub-districts / wards (FieldMaps only)

  • 4 — Neighborhoods / localities (FieldMaps only)

Available sources and their level coverage:

  • "geob" — geoBoundaries v6.0 (official GEE catalog, levels 0–2). Name property: shapeName.

  • "gaul" — FAO GAUL 2015 (official GEE catalog, levels 0–2). Name property: ADM{level}_NAME (e.g. ADM0_NAME).

  • "gaul2024" — FAO GAUL 2024 (community catalog, levels 0–2). Name property: gaul{level}_name.

  • "fieldmaps" — FieldMaps humanitarian edge-matched boundaries (community catalog, levels 1–4). Name property: adm{level}_name. Includes parent admin names and ISO codes.

For levels 3–4, if the requested source doesn’t support them the function automatically falls back to FieldMaps.

Parameters:

  • area – ee.FeatureCollection, ee.Feature, or ee.Geometry to filter by.

  • level (int) – Administrative level (0–4). Default 0.

  • source (str) – Boundary source. Default "geob".

  • name (str, optional) – Filter to the admin unit with this name. Uses the source’s name property automatically (e.g. shapeName for geob, ADM1_NAME for gaul). Exact match preferred, falls back to case-insensitive substring contains.

Returns:

ee.FeatureCollection of admin boundary polygons.

Example

>>> countries = getAdminBoundaries(my_area, level=0)
>>> states = getAdminBoundaries(my_area, level=1)
>>> districts = getAdminBoundaries(my_area, level=2, source="gaul")
>>> wards = getAdminBoundaries(my_area, level=3)  # auto-uses FieldMaps
>>> brazil = getAdminBoundaries(level=0, name="Brazil")
>>> mt_state = getAdminBoundaries(level=1, name="Montana")
geeViz.getSummaryAreasLib.getAdminNameProperty(level=0, source='geob')[source]

Return the feature property name that contains the admin unit name.

Useful for setting feature_label in summarize_and_chart or selectLayerNameProperty in Map.addSelectLayer.

Parameters:

  • level (int) – Administrative level (0–4).

  • source (str) – Boundary source (same options as getAdminBoundaries()).

Returns:

The property name (e.g. "shapeName", "ADM1_NAME").

Return type:

str

Example

>>> prop = getAdminNameProperty(level=1, source="gaul")  # "ADM1_NAME"
geeViz.getSummaryAreasLib.getUSStates(area=None, state_abbr=None, state_fips=None)[source]

Return US state boundaries (TIGER 2018).

All parameters are optional. When none are provided, all US states are returned.

Properties include NAME, STUSPS (abbreviation), STATEFP (FIPS code), REGION, DIVISION.

Parameters:

  • area (optional) – ee.FeatureCollection, ee.Feature, ee.Geometry, or None. Spatial filter.

  • state_abbr (str or list, optional) – Postal abbreviation(s) (e.g. "MT" or "MT,ID").

  • state_fips (str or list, optional) – FIPS code(s).

Returns:

ee.FeatureCollection.

geeViz.getSummaryAreasLib.getUSCounties(area=None, state_fips=None, state_abbr=None, county_names=None)[source]

Return US county boundaries, with flexible filtering.

All parameters are optional. When none are provided, all US counties are returned. Filters are combined (AND logic).

Properties include NAME, FULL_NAME, STATEFP, STUSPS, COUNTYFP, GEOID.

Parameters:

  • area (optional) – ee.FeatureCollection, ee.Feature, ee.Geometry, or None. When provided, results are filtered to counties that intersect this geometry.

  • state_fips (str or list, optional) – Two-digit state FIPS code(s) (e.g. "49" or ["49", "30"]). A comma-separated string is split automatically.

  • state_abbr (str or list, optional) – Two-letter postal abbreviation(s) (e.g. "UT", ["UT", "MT"], or "UT,MT").

  • county_names (str or list, optional) – County name(s) to match against the NAME property (e.g. "Missoula", ["Missoula", "Ravalli"], or "Missoula,Ravalli"). Note: county names may exist in multiple states — combine with state_abbr to disambiguate.

Returns:

ee.FeatureCollection.

Examples:

# All counties in Montana
getUSCounties(state_abbr='MT')

# Specific counties by name in a specific state
getUSCounties(state_abbr='MT', county_names='Missoula,Ravalli')

# Counties by name across all states (may return duplicates)
getUSCounties(county_names='Washington')

# Counties intersecting a geometry, filtered to one state
getUSCounties(area=my_point, state_abbr='CO')

# All US counties (no filters)
getUSCounties()
geeViz.getSummaryAreasLib.getUSUrbanAreas(area=None)[source]

Return TIGER 2024 urban area boundaries.

Properties include NAME20, NAMELSAD20, ALAND20, AWATER20.

Parameters:

area (optional) – ee.FeatureCollection, ee.Feature, ee.Geometry, or None. Spatial filter.

Returns:

ee.FeatureCollection.

geeViz.getSummaryAreasLib.getUSCensusBlocks(area=None)[source]

Return TIGER 2020 census blocks.

Warning

Census blocks are extremely numerous. Provide a small area or the query may be slow / exceed memory limits.

Parameters:

area (optional) – ee.FeatureCollection, ee.Feature, ee.Geometry, or None. Spatial filter. Strongly recommended for this dataset.

Returns:

ee.FeatureCollection.

geeViz.getSummaryAreasLib.getUSBlockGroups(area=None)[source]

Return TIGER 2020 census block groups.

Parameters:

area (optional) – ee.FeatureCollection, ee.Feature, ee.Geometry, or None. Spatial filter.

Returns:

ee.FeatureCollection.

geeViz.getSummaryAreasLib.getUSCensusTracts(area=None)[source]

Return TIGER 2020 census tracts.

Parameters:

area (optional) – ee.FeatureCollection, ee.Feature, ee.Geometry, or None. Spatial filter.

Returns:

ee.FeatureCollection.

geeViz.getSummaryAreasLib.getUSFSForests(area=None, region=None, forest_name=None)[source]

Return USFS National Forest boundaries.

All parameters are optional.

Properties include FORESTNAME, FORESTNUMB, REGION, FORESTORGC, GIS_ACRES.

Parameters:

  • area (optional) – Spatial filter.

  • region (str or list, optional) – USFS region number(s) (e.g. "01" or "01,04").

  • forest_name (str or list, optional) – Forest name(s) (e.g. "Lolo" or "Lolo,Bitterroot").

Returns:

ee.FeatureCollection.

geeViz.getSummaryAreasLib.getUSFSDistricts(area=None, forest_name=None, region=None, district_name=None)[source]

Return USFS Ranger District boundaries.

All parameters are optional.

Properties include DISTRICTNA, FORESTNAME, FORESTNUMB, REGION, GIS_ACRES.

Parameters:

  • area (optional) – Spatial filter.

  • forest_name (str or list, optional) – National Forest name(s).

  • region (str or list, optional) – USFS region number(s).

  • district_name (str or list, optional) – District name(s) (matches DISTRICTNA).

Returns:

ee.FeatureCollection.

geeViz.getSummaryAreasLib.getUSFSRegions(area=None, region=None)[source]

Return USFS region boundaries.

Properties include REGION, REGIONNAME, REGIONHEAD (headquarters city), FS_ADMINAC (admin acres).

Parameters:

  • area (optional) – Spatial filter.

  • region (str or list, optional) – USFS region number(s).

Returns:

ee.FeatureCollection with one feature per USFS region.

geeViz.getSummaryAreasLib.getRoads(area, source='tiger', year=2024)[source]

Return road features that intersect area.

Supports two road data sources covering different geographies and classification schemes.

Parameters:

  • area – ee.FeatureCollection, ee.Feature, or ee.Geometry.

  • source (str) –

    Road data source:

    • "tiger" (default) — US Census TIGER roads. Detailed classification via MTFCC codes. Available 2012-2025 via the community catalog, plus 2016 in the official GEE catalog. US only. Properties: FULLNAME, MTFCC, RTTYP, LINEARID.

    • "grip" — GRIP4 (Global Roads Inventory Project). Global coverage across 7 regional shards. Road type classification via GP_RTP (1=Highway, 2=Primary, 3=Secondary, 4=Tertiary, 5=Local). Based on OpenStreetMap and other sources. CC-BY 4.0.

  • year (int) – Year for TIGER roads (2012-2025). Ignored for other sources. Years other than 2016 use the community catalog (projects/sat-io/open-datasets/TIGER/{year}/Roads). Defaults to 2024.

Returns:

ee.FeatureCollection of road line features.

Common TIGER MTFCC codes:

  • S1100 — Primary road (interstate)

  • S1200 — Secondary road (US/state highway)

  • S1400 — Local road

  • S1500 — Vehicular trail (4WD)

  • S1630 — Ramp

  • S1640 — Service drive

  • S1730 — Alley

  • S1780 — Parking lot road

  • S1820 — Bike path / trail

GRIP4 GP_RTP road types:

  • 1 — Highway

  • 2 — Primary road

  • 3 — Secondary road

  • 4 — Tertiary road

  • 5 — Local / residential

Examples

>>> # US interstates from TIGER 2024
>>> interstates = getRoads(my_area).filter(ee.Filter.eq('MTFCC', 'S1100'))
>>> # Global highways from GRIP4
>>> highways = getRoads(my_area, source='grip').filter(ee.Filter.eq('GP_RTP', 1))
>>> # TIGER roads from a specific year
>>> roads_2020 = getRoads(my_area, year=2020)
geeViz.getSummaryAreasLib.getBuildings(area, source='vida')[source]

Return building footprints that intersect area.

This function determines which countries intersect the given area, then loads and merges per-country building footprint collections.

Parameters:

  • area – ee.FeatureCollection, ee.Feature, or ee.Geometry.

  • source (str) –

    Building footprint source.

    • "vida" — VIDA Combined Building Footprints (179 countries, ISO-3 keyed). Properties: area_in_meters, confidence, bf_source.

    • "ms" — Microsoft Building Footprints (202 countries, country-name keyed). Properties vary by country.

    • "google" — Google Open Buildings v3 (Africa, South/Southeast Asia). Properties: area_in_meters, confidence, full_plus_code.

Returns:

ee.FeatureCollection of building footprint polygons.

Note

Building collections are very large. Use a small study area or the query may be slow / exceed memory limits.

Example

>>> buildings = getBuildings(ee.Geometry.Point([-111, 40.7]).buffer(1000))
geeViz.getSummaryAreasLib.getProtectedAreas(area=None, iucn_cat=None, desig_type=None, name=None)[source]

Return WDPA protected area polygons.

Filter modes (combine freely):

  • area — intersect with an ee.Geometry / Feature / FeatureCollection

  • name — match the NAME field (e.g. "Yellowstone").

    Falls back to ORIG_NAME if the English NAME does not match, and finally to a case-insensitive substring contains. With no other filters this is the canonical “look up a park by name” path.

  • iucn_cat — IUCN category ("II" = National Park,

    "Ia" = Strict Nature Reserve, etc.)

  • desig_type — Designation type ("National", "Regional",

    "International", "Not Applicable").

Properties on each feature: NAME, DESIG_ENG, IUCN_CAT, STATUS, STATUS_YR, GOV_TYPE, DESIG_TYPE, REP_AREA, GIS_AREA, ISO3.

Parameters:

  • area – ee.FeatureCollection, ee.Feature, or ee.Geometry. Optional.

  • iucn_cat (str, optional) – Filter by IUCN category.

  • desig_type (str, optional) – Filter by designation type.

  • name (str, optional) – Filter by NAME (exact match preferred; falls back to ORIG_NAME, then case-insensitive contains).

Returns:

ee.FeatureCollection.

Examples

Yellowstone by name:

yellowstone = sal.getProtectedAreas(name="Yellowstone")

All US national parks intersecting a study area:

parks = sal.getProtectedAreas(area=my_aoi, iucn_cat="II")
geeViz.getSummaryAreasLib.getUSNationalParks(area=None, name=None, park_names=None, park_name=None)[source]

Return US National Park polygons (IUCN II + ISO3=USA).

Convenience wrapper over getProtectedAreas() for the lookup the agent reaches for most often. Filters WDPA to IUCN category II (the UN’s “National Park” designation) AND ISO3=USA, optionally restricted by area or by name / park_names (Yellowstone, Glacier, etc.).

Parameters:

  • area – Optional ee.Geometry / Feature / FeatureCollection.

  • name (str, optional) – Single park name. Passed through to getProtectedAreas() (exact → ORIG_NAME → substring).

  • park_names (str | list[str], optional) – Alias for name; accepts a single string OR a list of names (returns the union). Mirrors the county_names= convention on getUSCounties().

  • park_name (str, optional) – Alias for name (singular).

Returns:

ee.FeatureCollection.

Examples

>>> yellowstone = sal.getUSNationalParks(name="Yellowstone")
>>> yellowstone = sal.getUSNationalParks(park_names="Yellowstone")
>>> several = sal.getUSNationalParks(park_names=["Yellowstone", "Glacier"])