0
# erddapy
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: erddapy
7
- **Language**: Python  
8
- **Installation**: `pip install erddapy` or `conda install -c conda-forge erddapy`
9

10
## Core Imports
11

12
```python
13
from erddapy import ERDDAP, servers
14

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

18
# For direct access to core functions  
19
from erddapy.core import get_search_url, get_info_url, get_categorize_url, get_download_url
20
from erddapy.core.interfaces import to_pandas, to_xarray, to_ncCF, to_iris
21
```
22

23
## Basic Usage
24

25
```python
26
from erddapy import ERDDAP
27

28
# Create ERDDAP instance with server URL
29
e = ERDDAP(
30
    server="https://gliders.ioos.us/erddap",
31
    protocol="tabledap",
32
)
33

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

38
# Add constraints to filter data
39
e.constraints = {
40
    'time>=': '2016-07-10T00:00:00Z',
41
    'time<=': '2016-07-20T00:00:00Z',
42
    'latitude>=': 38.0,
43
    'latitude<=': 41.0,
44
    'longitude>=': -72.0,
45
    'longitude<=': -69.0,
46
}
47

48
# Download data as pandas DataFrame
49
df = e.to_pandas()
50
print(df.head())
51

52
# Or as xarray Dataset
53
ds = e.to_xarray()
54
print(ds)
55
```
56

57
Using built-in server shortcuts:
58

59
```python
60
from erddapy import ERDDAP, servers  
61

62
# List available servers
63
print(list(servers.keys()))
64

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

70
## Architecture
71

72
erddapy is built around URL construction and data format conversion:
73

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

80
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.
81

82
## Capabilities
83

84
### ERDDAP Client
85

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

88
```python { .api }
89
class ERDDAP:
90
    def __init__(self, server: str, protocol: str = None, response: str = "html"): ...
91
    def get_search_url(self, **kwargs) -> str: ...
92
    def get_info_url(self, dataset_id: str = None, response: str = None) -> str: ...
93
    def get_download_url(self, **kwargs) -> str: ...
94
    def to_pandas(self, **kwargs): ...
95
    def to_xarray(self, **kwargs): ...
96
```
97

98
[ERDDAP Client](./erddap-client.md)
99

100
### Server Management
101

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

104
```python { .api }
105
servers: dict  # Dictionary of server name -> Server objects
106

107
class Server:
108
    description: str  # Server description
109
    url: str  # Server URL
110

111
def servers_list() -> dict: ...
112
```
113

114
[Server Management](./server-management.md)
115

116
### Multi-Server Search
117

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

120
```python { .api }
121
def search_servers(
122
    query: str,
123
    *,
124
    servers_list: list = None,
125
    parallel: bool = False,
126
    protocol: str = "tabledap"
127
) -> DataFrame: ...
128

129
def advanced_search_servers(
130
    servers_list: list = None,
131
    *,
132
    parallel: bool = False,
133
    protocol: str = "tabledap",
134
    **kwargs
135
) -> DataFrame: ...
136
```
137

138
[Multi-Server Search](./multi-server-search.md)
139

140
### Data Format Conversion
141

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

144
```python { .api }
145
def to_pandas(url: str, **kwargs): ...
146
def to_xarray(url: str, response: str, **kwargs): ...
147
def to_ncCF(url: str, **kwargs): ...
148
def to_iris(url: str, **kwargs): ...
149
```
150

151
[Data Format Conversion](./data-conversion.md)
152

153
### Core URL Functions
154

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

157
```python { .api }
158
from erddapy.core import (
159
    get_search_url, get_info_url, get_categorize_url, get_download_url
160
)
161

162
def get_search_url(server: str, **kwargs) -> str: ...
163
def get_info_url(server: str, dataset_id: str = None, response: str = None) -> str: ...
164
def get_categorize_url(server: str, categorize_by: str, value: str = None, response: str = None) -> str: ...
165
def get_download_url(server: str, *, dataset_id: str = None, protocol: str = None, **kwargs) -> str: ...
166
```
167

168
### Utility Functions
169

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

172
```python { .api }
173
def parse_dates(date_time, *, dayfirst: bool = False, yearfirst: bool = False) -> float: ...
174
def urlopen(url: str, requests_kwargs: dict = None): ...
175
def _check_substrings(constraint) -> bool: ...
176
def _distinct(url: str, *, distinct: bool = False) -> str: ...
177
def _format_constraints_url(kwargs: dict) -> str: ...
178
def _quote_string_constraints(kwargs: dict) -> dict: ...
179
```
180

181
## Types
182

183
```python { .api }
184
from typing import Union, BinaryIO
185
from pandas import DataFrame
186
import pandas as pd
187
import xarray as xr
188
import netCDF4
189
import iris.cube
190
from datetime import datetime
191

192
# Type aliases used throughout erddapy
193
OptionalStr = Union[str, None]
194
OptionalBool = Union[bool, None]
195
OptionalDict = Union[dict, None] 
196
OptionalList = Union[list[str], tuple[str], None]
197

198
# Return types for major functions
199
DataFrame = pd.DataFrame
200
Dataset = xr.Dataset  
201
CubeList = iris.cube.CubeList
202
NetCDFDataset = netCDF4.Dataset
203
```