or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-conversion.mderddap-client.mdindex.mdmulti-server-search.mdserver-management.md
tile.json

tessl/pypi-erddapy

Python interface for ERDDAP data servers that simplifies accessing scientific datasets

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/erddapy@2.2.x

To install, run

npx @tessl/cli install tessl/pypi-erddapy@2.2.0

index.mddocs/

erddapy

Python interface for ERDDAP (Environmental Research Division's Data Access Program) servers that simplifies accessing scientific datasets. Provides a clean, Pythonic API for searching datasets, acquiring metadata, and downloading scientific data with constraint-based querying and seamless integration with pandas, xarray, netCDF4, and iris for data analysis workflows.

Package Information

  • Package Name: erddapy
  • Language: Python
  • Installation: pip install erddapy or conda install -c conda-forge erddapy

Core Imports

from erddapy import ERDDAP, servers

# For multi-server search functions
from erddapy.multiple_server_search import search_servers, advanced_search_servers

# For direct access to core functions  
from erddapy.core import get_search_url, get_info_url, get_categorize_url, get_download_url
from erddapy.core.interfaces import to_pandas, to_xarray, to_ncCF, to_iris

Basic Usage

from erddapy import ERDDAP

# Create ERDDAP instance with server URL
e = ERDDAP(
    server="https://gliders.ioos.us/erddap",
    protocol="tabledap",
)

# Set dataset and response format
e.dataset_id = "whoi_406-20160902T1700"
e.response = "csv"

# Add constraints to filter data
e.constraints = {
    'time>=': '2016-07-10T00:00:00Z',
    'time<=': '2016-07-20T00:00:00Z',
    'latitude>=': 38.0,
    'latitude<=': 41.0,
    'longitude>=': -72.0,
    'longitude<=': -69.0,
}

# Download data as pandas DataFrame
df = e.to_pandas()
print(df.head())

# Or as xarray Dataset
ds = e.to_xarray()
print(ds)

Using built-in server shortcuts:

from erddapy import ERDDAP, servers  

# List available servers
print(list(servers.keys()))

# Use server shortcut instead of full URL
e = ERDDAP(server="SECOORA", protocol="tabledap")
print(e.server)  # "http://erddap.secoora.org/erddap"

Architecture

erddapy is built around URL construction and data format conversion:

  • ERDDAP Class: Main interface that builds ERDDAP URLs and handles data requests
  • URL Builders: Functions to construct search, info, categorize, and download URLs
  • Data Interfaces: Converters that transform ERDDAP responses into Python data objects
  • Server Management: Built-in catalog of ERDDAP servers with shortcut names
  • Multi-Server Search: Parallel searching across multiple ERDDAP servers

The library handles ERDDAP's RESTful web services, automatically constructing appropriate URLs for different data requests and supporting both tabledap (tabular data) and griddap (gridded data) protocols.

Capabilities

ERDDAP Client

Core functionality for connecting to ERDDAP servers, searching datasets, and downloading data with flexible constraint-based filtering.

class ERDDAP:
    def __init__(self, server: str, protocol: str = None, response: str = "html"): ...
    def get_search_url(self, **kwargs) -> str: ...
    def get_info_url(self, dataset_id: str = None, response: str = None) -> str: ...
    def get_download_url(self, **kwargs) -> str: ...
    def to_pandas(self, **kwargs): ...
    def to_xarray(self, **kwargs): ...

ERDDAP Client

Server Management

Built-in catalog of ERDDAP servers with shortcuts and utilities for managing server connections.

servers: dict  # Dictionary of server name -> Server objects

class Server:
    description: str  # Server description
    url: str  # Server URL

def servers_list() -> dict: ...

Server Management

Multi-Server Search

Search capabilities across multiple ERDDAP servers simultaneously with optional parallel processing.

def search_servers(
    query: str,
    *,
    servers_list: list = None,
    parallel: bool = False,
    protocol: str = "tabledap"
) -> DataFrame: ...

def advanced_search_servers(
    servers_list: list = None,
    *,
    parallel: bool = False,
    protocol: str = "tabledap",
    **kwargs
) -> DataFrame: ...

Multi-Server Search

Data Format Conversion

Convert ERDDAP data URLs and responses into various Python data analysis formats including pandas DataFrames, xarray Datasets, netCDF4 objects, and iris CubeLists.

def to_pandas(url: str, **kwargs): ...
def to_xarray(url: str, response: str, **kwargs): ...
def to_ncCF(url: str, **kwargs): ...
def to_iris(url: str, **kwargs): ...

Data Format Conversion

Core URL Functions

Direct access to ERDDAP URL building functions from the core module, useful for advanced URL construction.

from erddapy.core import (
    get_search_url, get_info_url, get_categorize_url, get_download_url
)

def get_search_url(server: str, **kwargs) -> str: ...
def get_info_url(server: str, dataset_id: str = None, response: str = None) -> str: ...
def get_categorize_url(server: str, categorize_by: str, value: str = None, response: str = None) -> str: ...
def get_download_url(server: str, *, dataset_id: str = None, protocol: str = None, **kwargs) -> str: ...

Utility Functions

Core utility functions for URL handling, date parsing, and constraint formatting that are exposed in the main package API.

def parse_dates(date_time, *, dayfirst: bool = False, yearfirst: bool = False) -> float: ...
def urlopen(url: str, requests_kwargs: dict = None): ...
def _check_substrings(constraint) -> bool: ...
def _distinct(url: str, *, distinct: bool = False) -> str: ...
def _format_constraints_url(kwargs: dict) -> str: ...
def _quote_string_constraints(kwargs: dict) -> dict: ...

Types

from typing import Union, BinaryIO
from pandas import DataFrame
import pandas as pd
import xarray as xr
import netCDF4
import iris.cube
from datetime import datetime

# Type aliases used throughout erddapy
OptionalStr = Union[str, None]
OptionalBool = Union[bool, None]
OptionalDict = Union[dict, None] 
OptionalList = Union[list[str], tuple[str], None]

# Return types for major functions
DataFrame = pd.DataFrame
Dataset = xr.Dataset  
CubeList = iris.cube.CubeList
NetCDFDataset = netCDF4.Dataset