0
# ERDDAP Client
1

2
Core functionality for connecting to ERDDAP servers, searching datasets, and downloading data with flexible constraint-based filtering. The ERDDAP class serves as the main interface for all data operations.
3

4
## Capabilities
5

6
### ERDDAP Class Constructor
7

8
Creates an ERDDAP instance for a specific server endpoint, supporting both direct URLs and server shortcuts.
9

10
```python { .api }
11
class ERDDAP:
12
    def __init__(
13
        self,
14
        server: str,
15
        protocol: str | None = None,
16
        response: str = "html"
17
    ):
18
        """
19
        Create ERDDAP instance for server endpoint.
20
        
21
        Parameters:
22
        - server: ERDDAP server URL or shortcut name from servers dictionary
23
        - protocol: 'tabledap' or 'griddap' data protocol
24
        - response: default response format ('html', 'csv', 'json', etc.)
25
        """
26
```
27

28
**Usage Examples:**
29

30
```python
31
# Using full server URL
32
e = ERDDAP(server="https://gliders.ioos.us/erddap")
33

34
# Using server shortcut
35
e = ERDDAP(server="SECOORA", protocol="tabledap")
36

37
# Setting default response format
38
e = ERDDAP(server="NGDAC", protocol="tabledap", response="csv")
39
```
40

41
### Dataset and Configuration Properties
42

43
Configure the ERDDAP instance with dataset ID, variables, constraints, and other settings.
44

45
```python { .api }
46
class ERDDAP:
47
    @property
48
    def dataset_id(self) -> str: ...
49
    
50
    @dataset_id.setter  
51
    def dataset_id(self, value: str) -> None: ...
52
    
53
    # Configuration attributes
54
    server: str  # ERDDAP server URL
55
    protocol: str  # 'tabledap' or 'griddap'
56
    response: str  # Default response format
57
    constraints: dict  # Download constraints
58
    variables: list  # Variables to download
59
    dim_names: list  # Dimension names (griddap only)
60
    requests_kwargs: dict  # HTTP request options
61
    auth: tuple  # Authentication credentials
62
```
63

64
**Usage Examples:**
65

66
```python
67
e = ERDDAP(server="SECOORA", protocol="tabledap")
68

69
# Set dataset
70
e.dataset_id = "edu_fau_himb_5a99_50c5_adb4"
71

72
# Configure constraints
73
e.constraints = {
74
    'time>=': '2020-01-01T00:00:00Z',
75
    'time<=': '2020-01-31T23:59:59Z',
76
    'latitude>=': 25.0,
77
    'latitude<=': 30.0,
78
}
79

80
# Set variables to download  
81
e.variables = ['temperature', 'salinity', 'time', 'latitude', 'longitude']
82

83
# Configure authentication if needed
84
e.auth = ('username', 'password')
85
```
86

87
### URL Building Methods
88

89
Generate ERDDAP URLs for different types of data requests including search, metadata, categorization, and data download.
90

91
```python { .api }
92
class ERDDAP:
93
    def get_search_url(
94
        self,
95
        response: str = None,
96
        search_for: str = None,
97
        protocol: str = None,
98
        items_per_page: int = 1000000, 
99
        page: int = 1,
100
        **kwargs
101
    ) -> str:
102
        """
103
        Build search URL for datasets.
104
        
105
        Parameters:
106
        - search_for: Search terms (supports Google-like syntax)
107
        - response: Response format ('html', 'csv', 'json')
108
        - protocol: 'tabledap' or 'griddap' 
109
        - items_per_page: Results per page
110
        - page: Page number
111
        - **kwargs: Additional search constraints (minLon, maxLon, etc.)
112
        
113
        Returns:
114
        - Search URL string
115
        """
116
    
117
    def get_info_url(
118
        self,
119
        dataset_id: str = None,
120
        response: str = None
121
    ) -> str:
122
        """
123
        Build info URL for dataset metadata.
124
        
125
        Parameters:
126
        - dataset_id: Dataset ID (uses instance dataset_id if None)
127
        - response: Response format ('html', 'csv', 'json')
128
        
129
        Returns:
130
        - Info URL string
131
        """
132
        
133
    def get_categorize_url(
134
        self,
135
        categorize_by: str,
136
        value: str = None,
137
        response: str = None
138
    ) -> str:
139
        """
140
        Build categorize URL for browsing by attributes.
141
        
142
        Parameters: 
143
        - categorize_by: Attribute to categorize by ('ioos_category', 'standard_name', etc.)
144
        - value: Specific attribute value
145
        - response: Response format
146
        
147
        Returns:
148
        - Categorize URL string
149
        """
150
        
151
    def get_download_url(
152
        self,
153
        dataset_id: str = None,
154
        protocol: str = None, 
155
        variables: list = None,
156
        dim_names: list = None,
157
        response: str = None,
158
        constraints: dict = None,
159
        distinct: bool = False
160
    ) -> str:
161
        """
162
        Build download URL with constraints.
163
        
164
        Parameters:
165
        - dataset_id: Dataset ID 
166
        - protocol: 'tabledap' or 'griddap'
167
        - variables: List of variables to download
168
        - dim_names: Dimension names (griddap only)
169
        - response: Response format
170
        - constraints: Constraint dictionary
171
        - distinct: Return only unique values
172
        
173
        Returns:
174
        - Download URL string
175
        """
176
```
177

178
**Usage Examples:**
179

180
```python
181
# Search for glider datasets
182
search_url = e.get_search_url(
183
    search_for="glider temperature",
184
    response="csv",
185
    minLat=38.0,
186
    maxLat=42.0
187
)
188

189
# Get dataset metadata
190
info_url = e.get_info_url(dataset_id="whoi_406-20160902T1700", response="csv")
191

192
# Browse by category
193
cat_url = e.get_categorize_url("ioos_category", "Temperature")
194

195
# Build download URL with constraints
196
download_url = e.get_download_url(
197
    response="csv",
198
    constraints={'time>=': '2020-01-01T00:00:00Z'},
199
    distinct=True
200
)
201
```
202

203
### GridDAP Initialization
204

205
Initialize constraints and variables for gridded datasets using GridDAP protocol.
206

207
```python { .api }
208
class ERDDAP:
209
    def griddap_initialize(
210
        self,
211
        dataset_id: str = None,
212
        step: int = 1
213
    ) -> None:
214
        """
215
        Fetch dataset metadata and initialize griddap constraints.
216
        
217
        Parameters:
218
        - dataset_id: Dataset ID (uses instance dataset_id if None)
219
        - step: Step size for subsetting dataset
220
        """
221
```
222

223
**Usage Example:**
224

225
```python
226
e = ERDDAP(server="SECOORA", protocol="griddap") 
227
e.dataset_id = "HYCOM_Region_7_Aggregation_best"
228
e.griddap_initialize()  # Automatically sets constraints and variables
229

230
# Check what was initialized
231
print("Available constraints:", e.constraints)
232
print("Available variables:", e.variables)
233
print("Dimension names:", e.dim_names)
234
```
235

236
### Data Conversion Methods
237

238
Convert ERDDAP data directly to various Python data analysis formats.
239

240
```python { .api }
241
class ERDDAP:
242
    def to_pandas(
243
        self,
244
        requests_kwargs: dict = None,
245
        **kwargs
246
    ):
247
        """
248
        Download data as pandas DataFrame.
249
        
250
        Parameters:
251
        - requests_kwargs: HTTP request options
252
        - **kwargs: Additional pandas.read_csv arguments
253
        
254
        Returns:
255
        - pandas.DataFrame with downloaded data
256
        """
257
        
258
    def to_xarray(
259
        self,
260
        requests_kwargs: dict = None,
261
        **kwargs
262
    ):
263
        """
264
        Download data as xarray Dataset.
265
        
266
        Parameters:
267
        - requests_kwargs: HTTP request options  
268
        - **kwargs: Additional xarray.open_dataset arguments
269
        
270
        Returns:
271
        - xarray.Dataset with downloaded data
272
        """
273
        
274
    def to_ncCF(
275
        self,
276
        protocol: str = None,
277
        **kwargs
278
    ):
279
        """
280
        Download data as netCDF4 Dataset.
281
        
282
        Parameters:
283
        - protocol: Override protocol ('tabledap' or 'griddap')
284
        - **kwargs: Additional netCDF4 arguments
285
        
286
        Returns:
287
        - netCDF4.Dataset with downloaded data
288
        """
289
        
290
    def to_iris(
291
        self,
292
        **kwargs
293
    ):
294
        """
295
        Download data as iris CubeList.
296
        
297
        Parameters:
298
        - **kwargs: Additional iris.load_raw arguments
299
        
300
        Returns:
301
        - iris.cube.CubeList with downloaded data
302
        """
303
```
304

305
### Variable Discovery Methods
306

307
Discover and filter dataset variables by their attributes.
308

309
```python { .api }
310
class ERDDAP:
311
    def get_var_by_attr(
312
        self,
313
        dataset_id: str = None,
314
        **kwargs
315
    ) -> list[str]:
316
        """
317
        Get variables matching specified attributes.
318
        
319
        Parameters:
320
        - dataset_id: Dataset ID (uses instance dataset_id if None)
321
        - **kwargs: Attribute name-value pairs to match
322
        
323
        Returns:
324
        - List of variable names matching criteria
325
        """
326
```
327

328
**Usage Examples:**
329

330
```python
331
# Find variables by standard_name
332
temp_vars = e.get_var_by_attr(
333
    dataset_id="whoi_406-20160902T1700",
334
    standard_name="sea_water_temperature"
335
)
336

337
# Find coordinate variables
338
axis_vars = e.get_var_by_attr(
339
    dataset_id="whoi_406-20160902T1700", 
340
    axis=lambda v: v in ["X", "Y", "Z", "T"]
341
)
342

343
print("Temperature variables:", temp_vars)
344
print("Axis variables:", axis_vars)
345
```
346

347
### File Download
348

349
Download datasets directly to files in various formats.
350

351
```python { .api }
352
class ERDDAP:
353
    def download_file(
354
        self,
355
        file_type: str
356
    ) -> str:
357
        """
358
        Download dataset to file.
359
        
360
        Parameters:
361
        - file_type: File format extension (csv, netcdf, etc.)
362
        
363
        Returns:
364
        - Path to downloaded file
365
        """
366
```
367

368
**Usage Example:**
369

370
```python
371
e.dataset_id = "whoi_406-20160902T1700"
372
e.constraints = {'time>=': '2020-01-01T00:00:00Z'}
373

374
# Download as CSV file
375
csv_file = e.download_file("csv")
376
print(f"Downloaded: {csv_file}")
377

378
# Download as NetCDF file  
379
nc_file = e.download_file("nc")
380
print(f"Downloaded: {nc_file}")
381
```
382

383
## Constraint Format Examples
384

385
ERDDAP constraints use a dictionary format with comparison operators:
386

387
```python
388
# Time constraints
389
constraints = {
390
    'time>=': '2020-01-01T00:00:00Z',
391
    'time<=': '2020-12-31T23:59:59Z',
392
}
393

394
# Spatial constraints  
395
constraints = {
396
    'latitude>=': 25.0,
397
    'latitude<=': 30.0,
398
    'longitude>=': -90.0,
399
    'longitude<=': -80.0,
400
}
401

402
# Relative constraints
403
constraints = {
404
    'time>': 'now-7days',
405
    'latitude<': 'min(longitude)+180',
406
    'depth>': 'max(depth)-23',
407
}
408

409
# Value constraints
410
constraints = {
411
    'station_id=': 'KBDI1',
412
    'sensor_depth<=': 100.0,
413
}
414
```