`ERDDAP class API`¶

Pythonic way to access ERDDAP data.

class erddapy.erddapy.ERDDAP(server, protocol=None, response='html')[source]¶

Bases: object

Creates an ERDDAP instance for a specific server endpoint.

Args:¶

server: an ERDDAP server URL or acronym is using the builtin servers. protocol: tabledap or griddap.

Attributes:¶

dataset_id: a dataset unique id. variables: a list variables to download. response: default is HTML. constraints: download constraints, default None (opendap-like url) params and requests_kwargs: httpx.get options

Returns:¶

instance: the ERDDAP URL builder.

Examples:¶

Specifying the server URL

>>> e = ERDDAP(server="https://gliders.ioos.us/erddap")

let’s search for glider ru29 and read the csv response with pandas.

>>> import pandas as pd
>>> url = e.get_search_url(search_for="ru29", response="csv")
>>> pd.read_csv(url)["Dataset ID"]
0    ru29-20150623T1046
1    ru29-20161105T0131
Name: Dataset ID, dtype: object

there are “shortcuts” for some servers

>>> e = ERDDAP(server="SECOORA")
>>> e.server
'http://erddap.secoora.org/erddap'

to get a list of the shortcuts available servers:

>>> from erddapy import servers
>>> {k: v.url for k, v in servers.items()}
{'MDA': 'https://bluehub.jrc.ec.europa.eu/erddap/',
 'MII': 'https://erddap.marine.ie/erddap/',
 'CSCGOM': 'http://cwcgom.aoml.noaa.gov/erddap/',
 'CSWC': 'https://coastwatch.pfeg.noaa.gov/erddap/',
 'CeNCOOS': 'http://erddap.axiomalaska.com/erddap/',
 'NERACOOS': 'http://www.neracoos.org/erddap/',
 'NGDAC': 'https://gliders.ioos.us/erddap/',
 'PacIOOS': 'http://oos.soest.hawaii.edu/erddap/',
 'SECOORA': 'http://erddap.secoora.org/erddap/',
 'NCEI': 'https://ecowatch.ncddc.noaa.gov/erddap/',
 'OSMC': 'http://osmc.noaa.gov/erddap/',
 'UAF': 'https://upwell.pfeg.noaa.gov/erddap/',
 'ONC': 'http://dap.onc.uvic.ca/erddap/',
 'BMLSC': 'http://bmlsc.ucdavis.edu:8080/erddap/',
 'RTECH': 'https://meteo.rtech.fr/erddap/',
 'IFREMER': 'http://www.ifremer.fr/erddap/',
 'UBC': 'https://salishsea.eos.ubc.ca/erddap/'}

download_file(file_type)[source]¶

Download the dataset to a file in a user specified format.

Parameters:

self (ERDDAP)
file_type (str)

Return type:

str

get_categorize_url(categorize_by, value=None, response=None)[source]¶

Build the categorize URL for the server endpoint.

Args:¶

categorize_by: a valid attribute, e.g. ioos_category
or standard_name. Valid attributes are shown in http://erddap.ioos.us/erddap/categorize page.

value: an attribute value. response: default is HTML.

Returns:¶

url: the categorized URL for the response chosen.

Parameters:

self (ERDDAP)
categorize_by (str)
value (str | None)
response (str | None)

Return type:

str

get_download_url(*, dataset_id=None, protocol=None, variables=None, dim_names=None, response=None, constraints=None, distinct=False)[source]¶

Build the download URL for the server endpoint.

Args:¶

dataset_id: a dataset unique id. protocol: tabledap or griddap. variables (list/tuple): a list of the variables to download. dim_names (list/tuple): a list of the dimensions (griddap only). response (str): default is HTML. constraints (dict): download constraints, default None (opendap). distinct (bool): if true, only unique values will be downloaded.

Example:¶

constraints = {
‘latitude<=’: 41.0, ‘latitude>=’: 38.0, ‘longitude<=’: -69.0, ‘longitude>=’: -72.0, ‘time<=’: ‘2017-02-10T00:00:00+00:00’, ‘time>=’: ‘2016-07-10T00:00:00+00:00’,

}

One can also use relative constraints like: constraints = {

‘time>’: ‘now-7days’, ‘latitude<’: ‘min(longitude)+180’, ‘depth>’: ‘max(depth)-23’,

}

Returns:¶

url (str): the download URL for the response chosen.

Parameters:

self (ERDDAP)
dataset_id (str | None)
protocol (str | None)
variables (list[str] | tuple[str] | None)
dim_names (list[str] | tuple[str] | None)
response (str | None)
constraints (dict | None)
distinct (bool | None)

Return type:

str

get_info_url(dataset_id=None, response=None)[source]¶

Build the info URL for the server endpoint.

Args:¶

dataset_id: a dataset unique id. If empty the full dataset listing will be returned. response: default is HTML.

Returns:¶

url: the info URL for the response chosen.

Parameters:

self (ERDDAP)
dataset_id (str | None)
response (str | None)

Return type:

str

get_search_url(response=None, search_for=None, protocol=None, items_per_page=1000000, page=1, **kwargs)[source]¶

Build the search URL for the server endpoint provided.

Args:¶

search_for: “Google-like” search of the datasets’ metadata.

Type the words you want to search for, with spaces between the words. ERDDAP will search for the words separately, not as a phrase.

To search for a phrase, put double quotes around the phrase
(for example, “wind speed”).

To exclude datasets with a specific word use -excludedWord.

To exclude datasets with a specific phrase, use -“excluded phrase”

Searches are not case-sensitive.

You can search for any part of a word. For example,
searching for spee will find datasets with speed and datasets with WindSpeed

The last word in a phrase may be a partial word. For example,
to find datasets from a specific website (usually the start of the datasetID), include (for example) “datasetID=erd” in your search.

response: default is HTML. protocol: tabledap or griddap. items_per_page: how many items per page in the return,

default is 1_000_000 for HTML, 1e6 (hopefully all items) for CSV, JSON.

page: which page to display, default is the first page (1). kwargs: extra search constraints based on metadata and/or

coordinates key/value.

metadata: cdm_data_type, institution, ioos_category,
keywords, long_name, standard_name, and variableName. coordinates: minLon, maxLon, minLat, maxLat, minTime, and maxTime.

Returns:¶

url: the search URL.

Parameters:

self (ERDDAP)
response (str | None)
search_for (str | None)
protocol (str | None)
items_per_page (int)
page (int)
kwargs (dict)

Return type:

str

get_var_by_attr(dataset_id=None, **kwargs)[source]¶

Return a variable based on its attributes.

The get_var_by_attr method will create an info csv return, for the dataset_id, and the variables attribute dictionary, similar to netCDF4-python get_variables_by_attributes.

Examples

>>> e = ERDDAP(server_url="https://gliders.ioos.us/erddap")
>>> dataset_id = "whoi_406-20160902T1700"

Get variables with x-axis attribute.

>>> e.get_var_by_attr(dataset_id, axis="X")
['longitude']

Get variables with matching “standard_name” attribute

>>> e.get_var_by_attr(
...     dataset_id, standard_name="northward_sea_water_velocity"
... )
['v']

Get Axis variables

>>> axis = lambda v: v in ["X", "Y", "Z", "T"]
>>> e.get_var_by_attr(dataset_id, axis=axis)
['latitude', 'longitude', 'time', 'depth']

Parameters:

self (ERDDAP)
dataset_id (str | None)
kwargs (dict)

Return type:

list[str]

griddap_initialize(dataset_id=None, step=1)[source]¶

Fetch metadata of dataset and initialize constraints and variables.

Args:¶

dataset_id: a dataset unique id. step: step used to subset dataset

Parameters:

self (ERDDAP)
dataset_id (str | None)
step (int)

Return type:

None

to_iris(**kw)[source]¶

Load the data request into an iris.cube.CubeList.

Accepts any iris.load_raw keyword arguments.

Parameters:

self (ERDDAP)
kw (dict)

Return type:

iris.cube.CubeList

to_ncCF(protocol=None, **kw)[source]¶

Load the data request into a CF compliant netCDF4-python object.

Parameters:

self (ERDDAP)
protocol (OptionalStr)
kw (dict)

Return type:

netCDF4.Dataset

to_pandas(requests_kwargs=None, **kw)[source]¶

Save a data request to a pandas.DataFrame.

Accepts any pandas.read_csv keyword arguments, passed as a dictionary to pandas_kwargs.

This method uses the .csvp [1] response as the default for simplicity, please check ERDDAP’s docs for the other csv options available.

[1] Download a ISO-8859-1 .csv file with line 1: name (units).: Times are ISO 8601 strings.

requests_kwargs: kwargs to be passed to urlopen method. **kw: kwargs to be passed to third-party library (pandas).

Parameters:

self (ERDDAP)
requests_kwargs (dict | None)
kw (dict)

Return type:

DataFrame

to_xarray(requests_kwargs=None, **kw)[source]¶

Load the data request into a xarray.Dataset.

Accepts any xr.open_dataset keyword arguments.

Parameters:

self (ERDDAP)
requests_kwargs (dict | None)
kw (dict)

Return type:

xr.Dataset

Parameters:

server (str)
protocol (OptionalStr)
response (str)

erddapy.erddapy.parse_dates(date_time, *, dayfirst=False, yearfirst=False)[source]¶

Parse dates to ERDDAP internal format.

ERDDAP ReSTful API standardizes the representation of dates as either ISO strings or seconds since 1970, but internally ERDDAPY uses datetime-like objects. timestamp returns the expected strings in seconds since 1970.

Parameters:

date_time (datetime | str)
dayfirst (OptionalBool)
yearfirst (OptionalBool)

Return type:

float

erddapy.erddapy.urlopen(url, requests_kwargs=None)[source]¶

Thin wrapper around httpx get content.

See httpx.get docs for the params and kwargs options.

Parameters:

url (str)
requests_kwargs (dict | None)

Return type:

BinaryIO

erddapy

Navigation

Related Topics

`ERDDAP class API`¶

Args:¶

Attributes:¶

Returns:¶

Examples:¶

Args:¶

Returns:¶

Args:¶

Example:¶

Returns:¶

Args:¶

Returns:¶

Args:¶

Returns:¶

Args:¶

ERDDAP class API¶

Args:¶

Attributes:¶

Returns:¶

Examples:¶

Args:¶

Returns:¶

Args:¶

Example:¶

Returns:¶

Args:¶

Returns:¶

Args:¶

Returns:¶

Args:¶

`ERDDAP class API`¶