Searching PWFDF

All the main pwfdf-api commands begin by searching the collection for assessments that match provided search criteria. For example, assessments from a specific fire event, from a given date range, or in a particular spatial region. The commands also provide options that validate the search results, ensuring they meet expected parameters. This page discusses these search options in detail. Here we will use the assessments command to illustrate search options, but the discussed options are available in all main pwfdf-api commands.

Important

You can apply multiple search filters at a time. In this case, the command will match assessments that meet all the provided criteria.

Fire

You can search for assessments from a specific fire event using the --fire option. For example:

pwfdf assessments --fire Eaton

If a fire name contains spaces or punctuation, place the name in quotes:

pwfdf assessments --fire "South Rim"

Important

A queried fire must exactly match the official fire name in order to match the assessment. For example:

pwfdf assessments --fire South

will not match an assessment whose fire’s name is South Rim. If you are not sure of a fire’s official name, you can use the start date search filter to return the names of fires that started over a given time frame. The fire’s official name can then be extracted from the output list.

Caution

It is possible for two fire events to have duplicate names. To guard against this possibility, add the fire start date to the search filters, or set the max fires option to 1:

pwfdf assessments --fire Eaton --start-date 2025-01-08
pwfdf assessments --fire Eaton --max-fires 1

You can search for assessments from a specific fire event using the fire input. For example:

assessments(fire = "Eaton")
assessments(fire = "South Rim")

Important

The name of an assessment’s fire must exactly match the provided name in order to match the assessment. For example:

assessments(fire = "South")

will not match an assessment whose fire’s name is South Rim. If you are not sure of a fire’s official name, you can use the start date search filter to return the names of fires that started over a given time frame. The fire’s official name can then be extracted from the output list.

Caution

It is possible for two fire events to have duplicate names. To guard against this possibility, add the fire start date to the search filters, or set the max fires option to 1:

assessments(fire = "Eaton", start_date = "2025-01-08")
assessments(fire = "Eaton", max_fires = 1)

Version

You can search for a specific version number using the --version option:

pwfdf assessments --version 1.0

Alternatively, provide just the major version number to match all assessments in a major version:

# Matches 1.0, 1.1, 1.2, etc
pwfdf assessments --version 1

You can also use --latest to only return the latest version of matching assessments:

pwfdf assessments --latest

Combining a major version with --latest will cause the command to only return the latest version of assessments that match the given major version number:

pwfdf assessments --version 1 --latest

You can search for a specific version number using the version input:

assessments(version = "1.0")

Alternatively, provide just the major version number to match all assessments in a major version:

# Matches 1.0, 1.1, 1.2, etc
assessments(version = 1)

You can also set latest = True to only return the latest version of matching assessments:

assessments(latest = True)

Combining a major version with latest will cause the command to only return the latest version of assessments that match the given major version number:

assessments(version = 1, latest = True)

Date Ranges

The pwfdf-api provides support for several date range search filters. These filter match assessments whose date metadata falls within a given range. The date ranges include:

Date Range

Description

--start-date

The date when the fire event began

--assessment-date

The date when the assessment was performed

--publication-date

The date when the assessment was publicly released

All these filters use the same, flexible syntax. Setting a date range to a year will match all assessments whose associated date occurs within that year:

# Matches dates between 2025-01-01 and 2025-12-31
pwfdf assessments --start-date 2025
pwfdf assessments --assessment-date 2025
pwfdf assessments --publication-date 2025

Use a YYYY-MM date string to match all dates within a given month:

# Matches dates between 2025-06-01 and 2025-06-30
pwfdf assessments --start-date 2025-06

Or use YYYY-MM-DD to only match dates from a specific day:

pwfdf assessments --start-date 2025-06-15

You can also provides two dates to match dates that fall within their range. The first date is the start of the date range, and the second date is the end:

# Matches dates between June 15 and August 3, 2025
pwfdf assessments --start-date 2025-06-15 2025-08-03

If the start of a range is a year/month, then the date is interpreted as the first day. If the end of a range is a year/month, then the date is interpreted as the last day:

# Matches dates between January 1, 2025 and August 31, 2026
pwfdf assessments --start-date 2025 2026-08

# Matches dates between August 1, 2025 and December 31, 2026
pwfdf assessments --start-date 2025-08 2026

The pwfdf-api provides support for several date range search filters. These filter match assessments whose date metadata falls within a given range. The date ranges include:

Date Range

Description

start_date

The date when the fire event began

assessment_date

The date when the assessment was performed

publication_date

The date when the assessment was publicly released

All these filters use the same, flexible syntax. Setting a date range to a year will match all assessments whose associated date occurs within that year:

# Matches dates between 2025-01-01 and 2025-12-31
assessments(start_date = 2025)
assessments(assessment_date = 2025)
assessments(publication_date = 2025)

Use a YYYY-MM date string to match all dates within a given month:

# Matches dates between 2025-06-01 and 2025-06-30
assessments(start_date = "2025-06")

Or use YYYY-MM-DD to only match dates from a specific day:

assessments(start_date = "2025-06-15")

You can also provides two dates to match dates that fall within their range. The first date is the start of the date range, and the second date is the end:

# Matches dates between June 15 and August 3, 2025
assessments(start_date = ["2025-06-15", "2025-08-03"])

If the start of a range is a year/month, then the date is interpreted as the first day. If the end of a range is a year/month, then the date is interpreted as the last day:

# Matches dates between January 1, 2025 and August 31, 2026
assessments(start_date = ["2025", "2026-08"])

# Matches dates between August 1, 2025 and December 31, 2026
assessments(start_date = ["2025-08", "2026"])

Location

The pwfdf-api also supports two filters that search for assessments within specific geospatial regions. You can use an extent search to search for assessments in a well-known spatial region with predefined coordinates. For example, to search for assessments in a given country, state, county, national park, etc. You can also use a geometry search to implement a custom geospatial search, in which you provide the coordinates for the area of interest.

Extent

Use the --extent option to search for assessments in a well-known geospatial region with pre-defined coordinates. Common extent queries include continents, countries, states, provinces, counties, and national park units:

pwfdf assessments --extent "North America"
pwfdf assessments --extent "United States"
pwfdf assessments --extent California
pwfdf assessments --extent "Los Angeles, CA"
pwfdf assessments --extent "Grand Canyon National Park"

and extent queries also support 2-8 digit hydrologic unit codes (HUCs):

pwfdf assessments --extent 18
pwfdf assessments --extent 1809
pwfdf assessments --extent 180902
pwfdf assessments --extent 18090203

Use the --extent-relation option to specify the relationship between the spatial region and the search results. Options include:

Relation

Description

intersects (default)

Returns assessments that intersect the extent at any point

within

Only returns assessments that are fully contained within the extent

disjoint

Returns assessments that do not intersect the extent at any point

For example:

# Only return assessments outside of the US
pwfdf assessments --extent "United States" --extent-relation disjoint

Caution

The polygons used to delineate extents are relatively coarse, so you may receive unexpected results when querying assessments right along the edge of an extent boundary.

Use the extent input to search for assessments in a well-known geospatial region with pre-defined coordinates. Common extent queries include continents, countries, states, provinces, counties, and national park units:

assessments(extent="North America")
assessments(extent="United States")
assessments(extent="California")
assessments(extent="Los Angeles, CA")
assessments(extent="Grand Canyon National Park")

and extent queries also support 2-8 digit hydrologic unit codes (HUCs):

assessments(extent="18")
assessments(extent="1809")
assessments(extent="180902")
assessments(extent="18090203")

Caution

Be sure to provide HUCs as strings, and not as ints. Int extents are interpreted as extent IDs, which are not equal to their associated HUCs.

Use the extent_relation input to specify the relationship between the spatial region and the search results. Options include:

Relation

Description

intersects (default)

Returns assessments that intersect the extent at any point

within

Only returns assessments that are fully contained within the extent

disjoint

Returns assessments that do not intersect the extent at any point

For example:

# Only return assessments outside of the US
assessments(extent="United States", extent_relation="disjoint")

Caution

The polygons used to delineate extents are relatively coarse, so you may receive unexpected results when querying assessments right along the edge of an extent boundary.

Extent Names

An extent query must exactly match the extent’s standard name. For example:

pwfdf assessments --extent "Grand Canyon"

would not match the standard name Grand Canyon National Park. You can use the pwfdf extents interface to determine the standard names of supported extents. This interface consists of multiple commands that all follow the syntax:

pwfdf extents <type>

where <type> is one of the following options:

Show Extent Types

Named Extents

  • canadian-provinces

  • continents

  • countries

  • hawaiian-islands

  • mexican-states

  • national-parks

  • us-counties

  • us-regions

  • us-states

HUCs

  • huc2

  • huc4

  • huc6

  • huc8

Each command returns the list of queryable names for that extent type. For example, if you want to query a national park unit, but are unsure of the standard name, you could use:

pwfdf extents national-parks

to return the list of all queryable national park unit names. The desired name can then be extracted from this list.

Tip

You can save a long list of extent names to file using standard shell redirects. For example:

pwfdf extents us-counties > my-county-list.txt

would save the list of U.S. county names to my-county-list.txt.

An extent query must exactly match the extent’s standard name. For example:

assessments(extent = "Grand Canyon")

would not match the standard name Grand Canyon National Park. You can use the extents module to determine the standard names of supported extents. This module consists of functions that follow the syntax:

from pwfdf_api import extents
extents.<type>()

where <type> is one of the following options:

Show Extent Types

Named Extents

  • canadian_provinces

  • continents

  • countries

  • hawaiian_islands

  • mexican_states

  • national_parks

  • us_counties

  • us_regions

  • us_states

HUCs

  • huc2

  • huc4

  • huc6

  • huc8

Each command returns the list of queryable names for that extent type. For example, if you want to query a national park unit, but are unsure of the standard name, you could use:

names = extents.national_parks()

to return the list of all queryable national park unit names. The desired name can then be extracted from this list.

Geometry

The pwfdf-api provides three options for implementing custom geospatial searches:

Geometry

Description

--bbox

Searches a custom bounding box

--point

Searches a custom geospatial point

--geometry

Searches a custom geospatial geometry

You may only implement one of these searches at a time. The region of interest is typically provided via a GIS file, such as a Shapefile or GeoJSON:

pwfdf assessments --bbox my-file.shp
pwfdf assessments --point my-file.shp
pwfdf assessments --geometry my-file.shp

When provided as a GIS file, the --bbox option is calculated as the bounding box over all the geometries in the file, and the --point option is calculated as the center of the bounding box. The pwfdf-api supports most standard GIS formats, and the File Formats page provides a complete list of supported formats. The default parser is sufficient for most use cases, but refer to the Geometry File IO page if your file format includes multiple data layers or non-standard encodings.

You may also provide the --bbox and --point options as explicit comma-delimited WGS-84 coordinate points. For a bounding box, use the format "XMIN, YMIN, XMAX, YMAX". For a point, use the format "LON, LAT". For example:

pwfdf assessments --bbox "-121, 32, -119, 34"
pwfdf assessments --point "-105.2, 39.8"

Important

In practice, the --geometry option only supports relatively coarse geometries. This is because the geometry cannot cause the underlying query URL to exceed 2000 characters. As a rule of thumb, geometries with fewer than 100 coordinate points are expected to usually work.

Use the --geometry-relation option to specify the relationship between the geospatial region and the search results. Options include:

Relation

Description

intersects (default)

Returns assessments that intersect the geometry at any point

within

Only returns assessments that are fully contained within the geometry

disjoint

Returns assessments that do not intersect the geometry at any point

For example:

# Only return assessments outside of the bounding box geometry
pwfdf assessments --bbox my-file.shp --geometry-relation disjoint

The pwfdf-api provides three options for implementing geospatial searches:

Geometry

Description

bbox

Searches a custom bounding box

point

Searches a custom geospatial point

geometry

Searches a custom geospatial geometry

You may only implement one of these searches at a time. The region of interest is typically provided via a GIS file, such as a Shapefile or GeoJSON:

assessments(bbox="my-file.shp")
assessments(point="my-file.shp")
assessments(geometry="my-file.shp")

When provided as a GIS file, the bbox option is calculated as the bounding box over all the geometries in the file, and the point option is calculated as the center of the bounding box. The pwfdf-api supports most standard GIS formats, and the File Formats page provides a complete list of supported formats. The default parser is sufficient for most use cases, but refer to the Geometry File IO page if your file format includes multiple data layers or non-standard encodings.

You may also provide the bbox and point options as explicit WGS-84 coordinate sequences. For a bounding box, use the format [XMIN, YMIN, XMAX, YMAX]. For a point, use the format [LON, LAT]. For example:

assessments(bbox=[-121, 32, -119, 34])
assessments(point=[-105.2, 39.8])

The geometry option may be also be provided as a WGS-84 GeoJSON geometry-like dict. For example:

geometry = {'type': 'Point', 'coordinates': [-105.2, 39.8]}
assessments(geometry=geometry)

Important

In practice, the geometry option only supports relatively coarse geometries. This is because the geometry cannot cause the underlying query URL to exceed 2000 characters. As a rule of thumb, geometries with fewer than 100 coordinate points are expected to usually work.

Use the geometry_relation option to specify the relationship between the geospatial region and the search results. Options include:

Relation

Description

intersects (default)

Returns assessments that intersect the geometry at any point

within

Only returns assessments that are fully contained within the geometry

disjoint

Returns assessments that do not intersect the geometry at any point

For example:

# Only return assessments outside of the bounding box geometry
assessments(bbox="my-file.shp", geometry_relation="disjoint")

Saving Search Results

You can save search results to file using standard shell redirects. For example:

pwfdf assessments --start-date 2025 > my-search-results.txt

would save the output list of assessments to a file named my-search-results.txt.

There are many ways you can save search results to file in Python. One method is using Python’s standard open command:

from pwfdf_api import assessments
results = assessments(start_date=2025)
with open('my-search-results.txt', 'w') as file:
    file.write('\n'.join(results))

Validate Results

The pwfdf-api provides several options to check that search results do not exceed an expected number of fire events or assessments. These options are useful for ensuring that search filters are behaving as expected. When a search exceeds one of these limits, the command raises an error and exits immediately. For example, the download command will not download assessment data if its search results contain more than the expected number of fires or assessments.

Use --max-fires to specify a maximum allowed number of fire events in the search results. For example:

pwfdf assessments --max-fires 10

This option is particularly useful for guarding against fire events with duplicate names:

pwfdf assessments --fire Eaton --max-fires 1

Similarly, use --max-assessments to specify a maximum allowed number of assessments:

pwfdf assessments --max-assessments 15

The pwfdf-api provides several options to check that search results do not exceed an expected number of fire events or assessments. These options are useful for ensuring that search filters are behaving as expected. When a search exceeds one of these limits, the command raises an error and exits immediately. For example, the download command will not download assessment data if its search results contain more than the expected number of fires or assessments.

Use the max_fires input to specify a maximum allowed number of fire events in the search results. For example:

assessments(max_fires=10)

This option is particularly useful for guarding against fire events with duplicate names:

assessments(fire="Eaton", max_fires=1)

Similarly, use max_assessments to specify a maximum allowed number of assessments:

assessments(max_assessments=15)

View Results on ScienceBase

You can use the browse command to view search results in the ScienceBase user interface on your web browser. For example:

pwfdf browse --extent California --start-date 2025-01

Advanced users can also use the --json option to view the search results as a JSON response:

pwfdf browse --extent California --start-date 2025-01 --json

You can use the browse command to view search results in the ScienceBase user interface on your web browser. For example:

from pwfdf_api import browse
browse(extent="California", start_date="2025-01")

Advanced users can also set json=True to view the search results as a JSON response:

browse(extent="California", start_date="2025-01", json=True)