search

search

PDS-wide product discovery via the NASA PDS Registry search API.

Thin wrapper over NASA’s pds.api-client (the PDS Engineering Node’s REST client for the registry-wide search API at https://pds.nasa.gov/api/search/1, 80M+ products). Build a query from keyword filters, get back a :class:pandas.DataFrame, and download any product’s files by LIDVID.

Requires the optional [search] extra::

pip install "planetarypy[search]"

Scope: this is the NASA PDS4 registry. It covers Cassini, Voyager, Magellan, MRO, LRO, … (including products planetarypy’s catalog can’t otherwise resolve), but not non-NASA national archives such as Chang’e (CNSA) or Chandrayaan-2/3 (ISRO).

Functions

Name	Description
bbox_from_point	Build a (west, south, east, north) box of ±radius_deg around a point.
count	Number of products matching the filters, without fetching any rows.
fetch_pds_product	Download every file (data + label) for one PDS product by LIDVID.
get_product	Return one product’s registry properties by LIDVID (or LID).
product_file_urls	Extract data + label download URLs from a product.
search_products	Search the NASA PDS registry; return one row per matching product.

bbox_from_point

search.bbox_from_point(lon, lat, radius_deg)

Build a (west, south, east, north) box of ±radius_deg around a point.

Convenience for the bbox= filter of :func:search_products — e.g. “data within 1° of Jezero”. Latitude is clamped to [-90, 90]; longitude is returned as-is (no anti-meridian wrapping), so use small radii near ±180°.

[source]

count

search.count(
    target=None,
    instrument=None,
    instrument_host=None,
    investigation=None,
    processing_level=None,
    before=None,
    after=None,
    observationals=False,
    lidvid=None,
    query=None,
    bbox=None,
    host=_DEFAULT_HOST,
)

Number of products matching the filters, without fetching any rows.

Takes the same filter keywords as :func:search_products; issues a single limit=0 request and reads the registry’s total-hit count. Useful to size a result set (which :func:search_products would otherwise truncate at limit) before deciding how to page through it.

[source]

fetch_pds_product

search.fetch_pds_product(
    lidvid,
    dest=None,
    *,
    skip_online_check=False,
    host=_DEFAULT_HOST,
)

Download every file (data + label) for one PDS product by LIDVID.

Files land under {storage_root}/pds_search/<sanitized-lidvid>/ unless dest is given. Existing files are skipped. Returns the local paths. The downloaded files can be opened with :func:planetarypy.open.

[source]

get_product

search.get_product(lidvid, *, host=_DEFAULT_HOST)

Return one product’s registry properties by LIDVID (or LID).

Raises :class:KeyError if no product matches.

[source]

product_file_urls

search.product_file_urls(product_or_props)

Extract data + label download URLs from a product.

Accepts a product object (with a .properties mapping) or a properties dict (as returned by :func:get_product or a DataFrame row). Skips the registry’s "null" sentinel for absent files.

[source]

search_products

search.search_products(
    target=None,
    instrument=None,
    instrument_host=None,
    investigation=None,
    processing_level=None,
    before=None,
    after=None,
    observationals=False,
    lidvid=None,
    query=None,
    bbox=None,
    fields=None,
    limit=100,
    host=_DEFAULT_HOST,
)

Search the NASA PDS registry; return one row per matching product.

Parameters

Name	Type	Description	Default
target	str	Filter by the LID of a context object (e.g. target="urn:nasa:pds: context:target:planet.saturn").	None
instrument	str	Filter by the LID of a context object (e.g. target="urn:nasa:pds: context:target:planet.saturn").	None
instrument_host	str	Filter by the LID of a context object (e.g. target="urn:nasa:pds: context:target:planet.saturn").	None
investigation	str	Filter by the LID of a context object (e.g. target="urn:nasa:pds: context:target:planet.saturn").	None
processing_level	str	One of "telemetry", "raw", "partially-processed", "calibrated", "derived".	None
before	str | datetime	Restrict to products whose observation window starts before / ends after the given time.	None
after	str | datetime	Restrict to products whose observation window starts before / ends after the given time.	None
observationals	bool	If True, restrict to Product_Observational products.	False
lidvid	str	Match a single product by LIDVID (urn:…::1.0) or LID.	None
query	str	Raw PDS API query clause, AND-combined with the other filters — the escape hatch for anything the keyword filters don’t cover (e.g. query='lid like "urn:nasa:pds:cassini_iss_saturn*"').	None
bbox	(west, south, east, north)	Spatial filter: keep products whose footprint overlaps this longitude/latitude box (degrees), via the cart:Bounding_Coordinates fields. Order matches shapely’s .bounds / GeoJSON bbox. Note: only products whose archive populated those fields can match (often present for derived/calibrated products, absent for many raw/EDR), and a product’s bounding box can be degenerate for polar/long-track or anti-meridian-crossing footprints.	None
fields	list[str]	Restrict the returned columns to these registry property names.	None
limit	int	Maximum number of products to return (a single API request). Default 100. Very large result sets are not auto-paginated in this release.	100

Returns

Name	Type	Description
	pandas.DataFrame	Columns are the registry’s property names (e.g. ops:Data_File_Info.ops:file_ref); the index is the product LIDVID. Single-element list cells are flattened to scalars.

[source]