georest.usgs.sciencebase¶

Client for ScienceBase, the USGS catalog of data releases and science.

ScienceBase holds USGS data releases (the official, citable publication of USGS data), along with project pages, collections and the files attached to them:

https://www.sciencebase.gov/catalog

from georest.usgs import sciencebase

releases = sciencebase.search("burn severity", data_releases_only=True)
releases[["title", "published", "files", "url"]]

files = sciencebase.item_files(releases["id"].iloc[0])
files[["name", "size_mb", "url"]]

Searches return every match unless you pass limit; ScienceBase is large, so a broad query can match thousands of items. count() says how many first.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Module Attributes

PAGE_SIZE

The most items ScienceBase returns per request; larger requests get this many.

Functions

`children`(item_id)	The items inside a ScienceBase item, such as the parts of a data release.
`count`([query, data_releases_only, parent_id])	How many items a `search()` with the same arguments returns.
`get_item`(item_id)	Everything ScienceBase holds about one item.
`item_files`(item_id)	The files attached to a ScienceBase item, with download links.
`search`([query, data_releases_only, ...])	ScienceBase items matching a search.

georest.usgs.sciencebase.PAGE_SIZE = 1000¶: The most items ScienceBase returns per request; larger requests get this many.

georest.usgs.sciencebase.count(query: str = '', *, data_releases_only: bool = False, parent_id: str | None = None) → int[source]¶

How many items a search() with the same arguments returns.

Example:

from georest.usgs import sciencebase

sciencebase.count("streamflow", data_releases_only=True)

georest.usgs.sciencebase.search(query: str = '', *, data_releases_only: bool = False, parent_id: str | None = None, limit: int | None = None) → Any[source]¶

ScienceBase items matching a search.

Parameters:

query – Free text, matched against titles, summaries, keywords and more.
data_releases_only – Keep only USGS data releases.
parent_id – Keep only items inside this one (see children()).
limit – Return at most this many, best match first. By default every match is returned; ScienceBase serves 1,000 per request, and every page is fetched.

Returns:

id, title, summary, item_type (e.g. “Data Release”, “Folder”), published, last_updated, has_children, files (how many are attached) and url.

Return type:

pandas.DataFrame, one row per item

Example:

from georest.usgs import sciencebase

releases = sciencebase.search("burn severity", data_releases_only=True)
releases[["title", "published", "files", "url"]]

georest.usgs.sciencebase.children(item_id: str) → Any[source]¶

The items inside a ScienceBase item, such as the parts of a data release.

Example:

from georest.usgs import sciencebase

project = sciencebase.search("Monitoring Trends in Burn Severity", limit=1)
sciencebase.children(project["id"].iloc[0])

georest.usgs.sciencebase.get_item(item_id: str) → dict[source]¶

Everything ScienceBase holds about one item.

Returns:: the search() fields, plus body (the full description, HTML), dates (every dated event, by type), tags, contacts (names and roles), web_links, bbox (west, south, east, north, where the item has an extent) and parent_id.
Return type:: A dict

Example:

from georest.usgs import sciencebase

item = sciencebase.get_item("6331e928d34e900e86c52b9e")
item["title"], item["contacts"]

georest.usgs.sciencebase.item_files(item_id: str) → Any[source]¶

The files attached to a ScienceBase item, with download links.

Returns:: pandas.DataFrame with name, size_mb, content_type and url. Many data releases keep their files in child items; see children().

Example:

from georest.usgs import sciencebase

sciencebase.item_files("6331e928d34e900e86c52b9e")