Skip to content

NASA Earthdata

obstore.auth.earthdata

Credential providers for accessing NASA Earthdata.

DEFAULT_EARTHDATA_HOST module-attribute 

DEFAULT_EARTHDATA_HOST = 'urs.earthdata.nasa.gov'

Hostname of the NASA Earthdata Login primary operational (OPS) system.

This is the default host used during credential authorization.

NasaEarthdataCredentialProvider

A credential provider for accessing NASA Earthdata data resources with an S3Store.

This credential provider uses requests, and will error if that cannot be imported.

NASA Earthdata supports public in-region direct S3 access. This credential provider automatically manages the S3 credentials.

Note

You must be in the same AWS region (us-west-2) to use the credentials returned from this provider.

Examples:

from obstore.store import S3Store
from obstore.auth.earthdata import NasaEarthdataCredentialProvider

# Obtain an S3 credentials URL and an S3 data/download URL, typically
# via metadata returned from a NASA CMR collection or granule query.
credentials_url = "https://data.ornldaac.earthdata.nasa.gov/s3credentials"
data_url = (
    "s3://ornl-cumulus-prod-protected/gedi/GEDI_L4A_AGB_Density_V2_1/data/"
    "GEDI04_A_2024332225741_O33764_03_T01289_02_004_01_V002.h5"
)
data_prefix_url, filename = data_url.rsplit("/", 1)

# Since no NASA Earthdata credentials are specified in this example,
# environment variables or netrc will be used to locate them in order to
# obtain S3 credentials from the URL.
cp = NasaEarthdataCredentialProvider(credentials_url)

store = S3Store.from_url(data_prefix_url, credential_provider=cp)

# Download the file by streaming chunks
try:
    result = obstore.get(store, filename)
    with open(filename, "wb") as f:
        for chunk in iter(result):
            f.write(chunk)
finally:
    cp.close()

session property 

session: Session

Return the underlying session used for HTTP requests.

Return either the session supplied at construction, or the default session created during initialization, if no session was supplied.

Returns:

  • Session –

    The session used for HTTP requests.

Raises:

  • ValueError –

    If the credential provider has been closed and the session is unavailable.

__init__ 

__init__(
    credentials_url: str,
    *,
    host: str | None = None,
    auth: str | tuple[str, str] | None = None,
    session: Session | None = None,
) -> None

Construct a new NasaEarthdataCredentialProvider.

Parameters:

  • credentials_url (str) –

    Endpoint for obtaining S3 credentials from a NASA DAAC hosting data of interest. NASA Earthdata credentials are required for obtaining S3 credentials from this endpoint.

Other Parameters:

  • host (str | None) –

    Hostname for NASA Earthdata authentication.

    Precedence is as follows:

    1. Uses the specified value, if not None.
    2. Uses the environment variable EARTHDATA_HOST, if set.
    3. Uses the NASA Earthdata operational host: DEFAULT_EARTHDATA_HOST
  • auth (str | tuple[str, str] | None) –

    Authentication information; can be a NASA Earthdata token (str), NASA Earthdata username/password (tuple), or None. Defaults to None, in which case, environment variables are used, if set.

    Precedence is as follows:

    1. Uses the specified value, if not None.
    2. Uses the environment variable EARTHDATA_TOKEN, if set.
    3. Uses the environment variables EARTHDATA_USERNAME and EARTHDATA_PASSWORD, if both are set.
    4. Uses netrc to locate a username and password for host. Uses the environment variable NETRC, if set, to locate a netrc file; otherwise, uses the default netrc file location (~/.netrc on non-Windows OS or ~/_netrc on Windows).
  • session (Session | None) –

    The requests session to use for making requests to obtain S3 credentials. Defaults to None, in which case a default session is created internally. In this case, use this credential provider's close method to release resources when you are finished with it.

__call__ 

__call__() -> S3Credential

Request updated credentials.

close 

close() -> None

Release resources created by this credential provider.

NasaEarthdataAsyncCredentialProvider

A credential provider for accessing NASA Earthdata data resources with an S3Store.

This credential provider uses aiohttp, and will error if that cannot be imported.

NASA Earthdata supports public in-region direct S3 access. This credential provider automatically manages the S3 credentials.

Note

You must be in the same AWS region (us-west-2) to use the credentials returned from this provider.

Examples:

import obstore
from obstore.auth.earthdata import NasaEarthdataCredentialProvider

# Obtain an S3 credentials URL and an S3 data/download URL, typically
# via metadata returned from a NASA CMR collection or granule query.
credentials_url = "https://data.ornldaac.earthdata.nasa.gov/s3credentials"
data_url = (
    "s3://ornl-cumulus-prod-protected/gedi/GEDI_L4A_AGB_Density_V2_1/data/"
    "GEDI04_A_2024332225741_O33764_03_T01289_02_004_01_V002.h5"
)
data_prefix_url, filename = data_url.rsplit("/", 1)

# Since no NASA Earthdata credentials are specified in this example,
# environment variables or netrc will be used to locate them in order to
# obtain S3 credentials from the URL.
cp = NasaEarthdataAsyncCredentialProvider(credentials_url)

store = obstore.store.from_url(data_prefix_url, credential_provider=cp)

# Download the file by streaming chunks
try:
    result = await obstore.get_async(store, filename)
    with open(filename, "wb") as f:
        async for chunk in aiter(result):
            f.write(chunk)
finally:
    await cp.close()

session property 

session: ClientSession | RetryClient

Return the underlying session used for HTTP requests.

Return either the session supplied at construction, or the default session created during initialization, if no session was supplied.

Returns:

  • ClientSession | RetryClient –

    The session used for HTTP requests.

Raises:

  • ValueError –

    If the credential provider has been closed and the session is unavailable.

__init__ 

__init__(
    credentials_url: str,
    *,
    host: str | None = None,
    auth: str | tuple[str, str] | None = None,
    session: ClientSession | RetryClient | None = None,
) -> None

Construct a new NasaEarthdataAsyncCredentialProvider.

This credential provider uses aiohttp, and will error if that cannot be imported.

Refer to NasaEarthdataCredentialProvider for argument explanations.

__call__ async 

__call__() -> S3Credential

Request updated credentials.

close async 

close() -> None

Release resources created by this credential provider.