query(*, fields=None, fire=None, version=None, start_date=None, assessment_date=None, publication_date=None, extent=None, extent_type=None, extent_relation='intersects', bbox=None, point=None, geometry=None, geometry_relation='intersects', geometry_layer=None, geometry_driver=None, geometry_encoding=None, max=None, offset=None, timeout=15, session=None)

Performs a single low-level query of the PWFDF collection and returns the ScienceBase API response as a dict.

Query API

query(...)
query(..., *, fields)

Performs a single low-level query of the PWFDF collection via the ScienceBase API and returns the response as a dict. In most cases, the output will include a total key, which reports the number of matching product records. The output will also usually include an items key, which is a list of sbJSON dicts for the assessment products included in the response. Use fields to indicate the sbJSON fields that should be included in the items.

Important

The total will exceed the number of elements in items if the total number of search results exceed the max paging parameter. In such cases, multiple queries may be required to load all the search results.

Fire Event

query(..., *, fire)

Searches for assessments whose fire matches the given name. Note that the provided fire name must exactly match an assessment’s fire name (case-insensitive). Partial matches are not supported.

Version Number

query(..., *, version)

Searches for assessments matching the provided version number.

Caution

The version must be a full 2-part version number. Major version numbers are not supported.

Date Range

query(..., *, start_date)
query(..., *, assessment_date)
query(..., *, publication_date)

Searches for assessments matching a given date range. Use start_date to filter by the fire start date, assessment_date to filter by the date the assessment was run, and publication_date to filter by the date that the assessment was published to ScienceBase.

In general, a date input may be a (1) integer year, (2) datetime.date object, (3) datetime.datetime object, (4) YYYY, YYYY-MM, or YYYY-MM-DD date string, or (5) a tuple of two such inputs. If the input is a year or a month, matches all assessments that fall within that interval. If the input is a 2-tuple, then it is interpreted as a date range and the search matches assessments that fall between the two dates. If the first date is a year or month, then the date range will begin on the first day of that interval. If the last date is a year or month, then the range will end on the final day of that interval.

Extent

query(..., *, extent)
query(..., *, extent_type)
query(..., *, extent_relation)

Searches for assessments in a spatial area with well-known coordinates, such as a country or state. The extent may be the name of a supported extent, or an integer extent ID. Use extent_relation to set the spatial relationship between the extent and the search results. Options are:

Relation	Description
intersects	(default) Matches assessments that intersect the extent at any point
within	Only matches assessments that are fully contained within the extent
disjoint	Matches assessments that do not intersect the extent at any point

Use extent_type to specify the type of extent being searched. This option is usually not necessary, but can be useful for guarding against extents with similar names.

Geometry

query(..., *, bbox)
query(..., *, point)
query(..., *, geometry)
query(..., *, geometry_relation)

Searches for assessments in a custom geospatial area. You may use one of the following search types at a time:

Search Type	Description
bbox	Searches a custom bounding box. The input may be either (1) a WGS-84 [xmin, ymin, xmax, ymax] coordinate sequence, or (2) a GIS file path. If a file, then the bounding box is calculated from the contained geometries.
point	Searches a custom geospatial point. The input may be either (1) a [lon, lat] sequence, or (2) a GIS file path. If a file, then the point is determined as the center of the bounding box of the contained geometries.
geometry	Searches a custom geospatial geometry. The input may be either (1) a WGS-84 GeoJSON-like dict (with type and coordinates keys), or (2) a GIS file path. In practice, only coarse geometries are supported (fewer than 100 coordinate points).

Note

GIS files may use any CRS. Unlike explicit coordinate points, they are not limited to WGS-84.

Use geometry_relation to set the spatial relationship between the geometry and the search results. Options are:

Relation	Description
intersects	(default) Matches assessments that intersect the geometry at any point
within	Only matches assessments that are fully contained within the geometry
disjoint	Matches assessments that do not intersect the geometry at any point

Geometry File IO

query(..., *, geometry_layer)
query(..., *, geometry_driver)
query(..., *, geometry_encoding)

Advanced options for reading a geometry from a GIS file. Use geometry_layer when the file has multiple data layers. The layer may either be a layer name, or an integer index. Reads the first layer if not otherwise specified. Use geometry_driver to specify the file format when the file uses a non-standard extension. Most drivers will automatically detect the file encoding, but you can use geometry_encoding to explicitly specify the encoding if detection fails.

Paging

query(..., *, max)
query(..., *, offset)

Paging options for the ScienceBase API. Use max to set the maximum number of ScienceBase product records that should be retrieved. Defaults to 500 and cannot exceed 1000. Use offset to specify the number of ScienceBase products to skip before retrieving search results.

Web Request

query(..., *, timeout)
query(..., *, session)

Advanced web request options. Use timeout to specify a maximum time in seconds for connecting to the ScienceBase server (default is 15 seconds). This option is typically a scalar, but may also use a vector with two elements. In this case, the first value is the timeout to connect with the server, and the second value is the time for the server to return the first byte. You can also set timeout=None, in which case server queries will never time out. This may be useful for some slow connections, but is generally not recommended as your code may hang indefinitely if the server fails to respond.

Use the session option to provide a pre-instantiated requests.Session object for querying the ScienceBase API. If not provided, the command creates (and then closes) a new Session for the request. If you provide a Session object as input, then the session is used to implement the query, but is not closed afterwards. This can be useful when calling pwfdf_api multiple times, as the Session object will preserve the underlying TCP connection, which can improve performance.

Inputs:

• fire (str) – The name of a fire event

• version (str) – A version number

• start_date (str | int | datetime.date | datetime.datetime | tuple) – A date range in which matching fire events began

• assessment_date (str | int | datetime.date | datetime.datetime | tuple) – A date range in which matching assessment were performed

• publication_date (str | int | datetime.date | datetime.datetime | tuple) – A date range in which matching assessments were published to ScienceBase

• extent (str | int) – An extent name or integer ID

• extent_type (str) – The type of extent being searched

• extent_relation (str) – The spatial relationship between the extent and the search results

• bbox (str | Path | [float, float, float, float]) – A custom bounding box to search. Either a file path, or a WGS-84 [xmin, ymin, xmax, ymax] coordinate sequence

• point (str | Path | [float, float]) – A custom geospatial point to search. Either a file path, or a [lon, lat] point.

• geometry (str | Path | dict) – A custom geospatial geometry to search. Either a file path or a WGS-84 GeoJSON geometry-like dict

• geometry_relation (str) – The spatial relationship between the geometry and the search results

• geometry_layer (str | int) – The name or index of a data layer in a geometry file

• geometry_driver (str) – The file format driver to use to read a geometry file

• geometry_encoding (str) – The file encoding to use to read a geometry file

• max (int) – The maximum number of ScienceBase records to retrieve per API query

• offset (int) – The number of ScienceBase records to skip before retrieving results

• fields (list[str]) – A list of sbJSON fields that should be included in the items response

• timeout (float | (float, float)) – The maximum allowed number of seconds to connect with the ScienceBase server

• session (requests.Session) – A pre-existing requests.Session object that should be used to connect with the ScienceBase API

Outputs:

dict – The ScienceBase API response for the query