0
# Server Management
1

2
Built-in catalog of ERDDAP servers with shortcuts and utilities for managing server connections. erddapy maintains a curated list of public ERDDAP servers that can be accessed using shortcut names instead of full URLs.
3

4
## Capabilities
5

6
### Server Dictionary
7

8
Access the built-in catalog of ERDDAP servers using shortcut names.
9

10
```python { .api }
11
servers: dict[str, Server]  # Dictionary mapping server names to Server objects
12
```
13

14
**Usage Examples:**
15

16
```python
17
from erddapy import servers
18

19
# List all available servers
20
print(list(servers.keys()))
21
# ['mda', 'mii', 'cscgom', 'cswc', 'cencos', 'neracoos', 'ngdac', ...]
22

23
# Get server information
24
secoora = servers['secoora']
25
print(secoora.description)  # "Southeast Coastal Ocean Observing Regional Association"
26
print(secoora.url)          # "http://erddap.secoora.org/erddap"
27

28
# Use in ERDDAP constructor
29
from erddapy import ERDDAP
30
e = ERDDAP(server="secoora")  # Automatically resolves to full URL
31
```
32

33
### Server Class
34

35
Container for server metadata including description and URL.
36

37
```python { .api }
38
from typing import NamedTuple
39

40
class Server(NamedTuple):
41
    """
42
    Container for server short description and URL.
43
    
44
    Attributes:
45
    - description: Human-readable server description
46
    - url: Full ERDDAP server URL
47
    """
48
    description: str
49
    url: str
50
```
51

52
**Usage Examples:**
53

54
```python
55
from erddapy.servers.servers import Server
56

57
# Create custom server
58
custom_server = Server(
59
    description="My Institution ERDDAP",
60
    url="https://data.myinstitution.edu/erddap"
61
)
62

63
print(custom_server.description)
64
print(custom_server.url)
65
```
66

67
### Server List Function
68

69
Download and cache the latest list of public ERDDAP servers from the awesome-erddap repository.
70

71
```python { .api }
72
def servers_list() -> dict[str, Server]:
73
    """
74
    Download updated server list from awesome-erddap repository.
75
    
76
    First attempts to load the latest list from GitHub. If that fails,
77
    falls back to the default server list shipped with the package.
78
    Uses LRU cache to avoid repeated downloads.
79
    
80
    Returns:
81
    - Dictionary mapping server shortcut names to Server objects
82
    """
83
```
84

85
**Usage Examples:**
86

87
```python
88
from erddapy.servers.servers import servers_list
89

90
# Get fresh server list (cached)
91
current_servers = servers_list()
92

93
# Check if new servers are available
94
print(f"Total servers: {len(current_servers)}")
95

96
# Access specific server
97
if 'noaa_coastwatch' in current_servers:
98
    server = current_servers['noaa_coastwatch']
99
    print(f"URL: {server.url}")
100
    print(f"Description: {server.description}")
101
```
102

103
## Built-in Server Shortcuts
104

105
The following server shortcuts are commonly available (updated from awesome-erddap):
106

107
**Major Oceanographic Data Centers:**
108
- `'cswc'` - NOAA CoastWatch West Coast
109
- `'ncei'` - NOAA National Centers for Environmental Information  
110
- `'osmc'` - NOAA Observing System Monitoring Center
111
- `'ngdac'` - IOOS National Glider Data Assembly Center
112

113
**Regional Associations:**
114
- `'secoora'` - Southeast Coastal Ocean Observing Regional Association
115
- `'neracoos'` - Northeastern Regional Association of Coastal Ocean Observing Systems
116
- `'pacioos'` - Pacific Islands Ocean Observing System
117
- `'cencos'` - Central and Northern California Ocean Observing System
118

119
**International:**
120
- `'mda'` - European Marine Data Archive (JRC)
121
- `'mii'` - Marine Institute Ireland
122
- `'ifremer'` - French Research Institute for Exploitation of the Sea
123

124
**Research Institutions:**
125
- `'uaf'` - University of Alaska Fairbanks
126
- `'onc'` - Ocean Networks Canada
127
- `'ubc'` - University of British Columbia
128

129
**Usage with Server Shortcuts:**
130

131
```python
132
from erddapy import ERDDAP
133

134
# Use any server shortcut
135
e = ERDDAP(server="secoora", protocol="tabledap")
136
print(e.server)  # "http://erddap.secoora.org/erddap"
137

138
e = ERDDAP(server="ngdac", protocol="tabledap") 
139
print(e.server)  # "https://gliders.ioos.us/erddap"
140

141
e = ERDDAP(server="pacioos", protocol="griddap")
142
print(e.server)  # "http://oos.soest.hawaii.edu/erddap"
143
```
144

145
## Custom Server Configuration
146

147
For servers not in the built-in catalog, use the full URL:
148

149
```python
150
from erddapy import ERDDAP
151

152
# Use custom server URL
153
e = ERDDAP(
154
    server="https://my-institution.edu/erddap",
155
    protocol="tabledap"
156
)
157

158
# Or with authentication
159
e = ERDDAP(server="https://private-server.org/erddap")
160
e.auth = ('username', 'password')
161
```
162

163
## Server Discovery
164

165
Find servers with specific characteristics:
166

167
```python
168
from erddapy import servers
169

170
# Find servers by description keywords
171
coastal_servers = {
172
    name: server for name, server in servers.items() 
173
    if 'coastal' in server.description.lower()
174
}
175

176
# Find NOAA servers
177
noaa_servers = {
178
    name: server for name, server in servers.items()
179
    if 'noaa' in server.description.lower()
180
}
181

182
print("Coastal servers:", list(coastal_servers.keys()))
183
print("NOAA servers:", list(noaa_servers.keys()))
184
```
185

186
## Error Handling
187

188
The server management system handles various failure modes:
189

190
```python
191
from erddapy import ERDDAP
192

193
# Invalid server shortcut - raises KeyError during initialization
194
try:
195
    e = ERDDAP(server="nonexistent_server")
196
except Exception as ex:
197
    print(f"Server not found: {ex}")
198

199
# If servers_list() fails to download from GitHub, 
200
# it automatically falls back to the bundled server list
201
from erddapy.servers.servers import servers_list
202
servers = servers_list()  # Always returns a valid server dictionary
203
```