Low Level API¶

The main and sbjson commands in the pwfdf-api are designed to handle the complexities of the underlying ScienceBase API automatically. However, advanced developers may wish control these low-level queries more directly. This page discusses search options and commands for controlling ScienceBase API queries.

Search Options¶

In addition to the standard search options, the commands also support several options for controlling low-level interactions with the ScienceBase API. Here we will use the assessments command to illustrate search options, but the discussed options are available in all main pwfdf-api commands.

Command Line

Use the --timeout option to specify a maximum allowed time to connect with the ScienceBase server (in seconds):

# Raises an error if the command does not connect within 30 seconds
assessments --timeout 30

The ScienceBase API implements a paging scheme wherein multiple API queries may be required to retrieve all search results. Use the --max-queries option to set a maximum allowed number of API queries. This can be useful if you need to rate limit an application:

# Raises an error if the command would require more than 5 queries
assessments --max-queries 5

You can also use --max-per-query to specify the number of search results to return per query. The default is 500 results per query, and this limit can be raised to a maximum of 1000:

# Retrieves up to 750 search results per API query
assessments --max-per-query 750

You can also implement custom paging schemes using the --max-per-query, --truncate, and --offset options. To do so, use --max-per-query to set the total number of search results retrieved per API query to N. Next, use the --truncate option to stop pwfdf-api from making multiple API calls. Finally, increment --offset by N and call the command until all records have been retrieved. For example:

pwfdf assessments --max-per-query 10 --truncate --offset 0
pwfdf assessments --max-per-query 10 --truncate --offset 10
pwfdf assessments --max-per-query 10 --truncate --offset 20
# etc

Python

Use the timeout input to specify a maximum allowed time to connect with the ScienceBase server (in seconds):

# Raises an error if the command does not connect within 30 seconds
assessments(timeout=60)

The ScienceBase API implements a paging scheme wherein multiple API queries may be required to retrieve all search results. Use the max_queries input to set a maximum allowed number of API queries. This can be useful if you need to rate limit an application:

# Raises an error if the command would require more than 5 queries
assessments(max_queries=5))

You can also use max_per_query to specify the number of search results to return per query. The default is 500 results per query, and this limit can be raised to a maximum of 1000:

# Retrieves up to 750 search results per API query
assessments(max_per_query=750)

You can also implement custom paging schemes using the max_per_query, truncate, and offset options. To do so, use max_per_query to set the total number of search results retrieved per API query to N. Next, set truncate = True to stop pwfdf-api from making multiple API calls. Finally, increment offset by N and call the command until all records have been retrieved. For example:

assessments(max_per_query=10, truncate=True, offset=0)
assessments(max_per_query=10, truncate=True, offset=10)
assessments(max_per_query=10, truncate=True, offset=20)
# etc

Commands¶

Url¶

Command Line

You can use the url command to return the URL that would be used to query the ScienceBase API with any specified criteria:

pwfdf url --extent California --start-date 2025

By default, this returns a URL to the ScienceBase user interface. Use the --json option to return the URL for a JSON API response instead:

pwfdf url --extent California --json

This url can then be passed as needed to other codes using standard shell redirects. For example:

pwfdf url --extent California --json | my-other-command

By default, the command will return a percent-encoded URL suitable for web requests. Use the --decode option to return a decoded URL, which is more human-readable:

pwfdf url --extent California --decode

Python

You can use the url command to return the URL that would be used to query the ScienceBase API with any specified criteria:

from pwfdf_api import url
url(extent="California", start_date=2025)

By default, this returns a URL to the ScienceBase user interface. Set json=True to return the URL for a JSON API response instead:

url(extent="California", json=True)

By default, the command will return a percent-encoded URL suitable for web requests. Set decode=True to return a decoded URL, which is more human-readable:

url(extent="California", decode=True)

Query¶

Command Line

You can use the query command perform a single ScienceBase API query and return the JSON response.

Warning

This command only makes a single API query. If paging is required, then the response will not contain all matching search results, and you will need to make multiple queries (with incremental offsets) to fully retrieve all results.

Note

This command only accepts full assessment version numbers. Major version numbers and the --latest option are not supported, as these filters are applied by pwfdf-api, rather than ScienceBase.

pwfdf query --extent California --start-date 2025

Tip

You can save the output JSON to file using standard shell redirects. For example:

pwfdf query --extent California > my-response.json

Python

You can use the query command perform a single ScienceBase API query and return the JSON response as a dict.

Warning

Note

This command only accepts full assessment version numbers. Major version numbers and latest are not supported, as these filters are applied by pwfdf-api, rather than ScienceBase.

from pwfdf_api import query
response = query(extent="California", start_date=2025)