USNAN Python SDK/Getting Started

Getting Started with the USNAN Python SDK

Creating a Client

The core entry point is the USNANClient class.

import usnan
client = usnan.USNANClient()

By default, it connects to the public API at:

https://dev.api.nmrhub.org

Optional parameters:

• base_url – override the API endpoint
• timeout – request timeout in seconds
• num_retries – automatic retry attempts

Listing Facilities

for fac in client.facilities.list():
    print(fac.identifier, fac.long_name)

Each facility exposes linked spectrometers and probes.

Searching for Datasets

cfg = (
    usnan.models.SearchConfig(records=50)
      .add_filter("is_knowledgebase", value=True, match_mode="equals")
      .add_filter("num_dimension", value=2, match_mode="equals")
)

for ds in client.datasets.search(cfg):
    print(ds.id, ds.title, ds.num_dimension)

Downloading Datasets

client.datasets.download([363067], location="data/")

Files are stored in a directory structure mirroring dataset identifiers.

Caching and Error Handling

The SDK caches facilities, spectrometers, and probes for efficiency. To refresh the cache:

client.clear_cache()

Common exceptions:

• TypeError – invalid argument types
• KeyError – missing entity ID
• ValueError – inconsistent filter operators