ERDDAP class API

Pythonic way to access ERDDAP data.

class erddapy.erddapy.ERDDAP(server, protocol=None, response='html')

Bases: object

Creates an ERDDAP instance for a specific server endpoint.

Parameters:

• server (str) – an ERDDAP server URL or an acronym for one of the builtin servers.

• protocol (str | None) – tabledap or griddap.

• response (str) –

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:

the ERDDAP URL builder.

Return type:

instance

Parameters:

• server (str) –

• protocol (str | None) –

• response (str) –

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/'}

get_categorize_url(categorize_by, value=None, response=None)

Build the categorize URL for the server endpoint.

Parameters:

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

• value (str | None) – an attribute value.

• response (str | None) – default is HTML.

Returns:

the categorized URL for the response chosen.

Return type:

url

get_download_url(dataset_id=None, protocol=None, variables=None, dim_names=None, response=None, constraints=None, distinct=False)

Build the download URL for the server endpoint.

Parameters:

• dataset_id (str | None) – a dataset unique id.

• protocol (str | None) – tabledap or griddap.

• variables (list/tuple) – a list of the variables to download.

• response (str) – default is HTML.

• constraints (dict) – download constraints, default None (opendap-like url)

• 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’,}

• {'time>' (One can also use relative constraints like) – ‘now-7days’, ‘latitude<’: ‘min(longitude)+180’, ‘depth>’: ‘max(depth)-23’,}

• dim_names (List[str] | Tuple[str] | None) –

Returns:

the download URL for the response chosen.

Return type:

url (str)

get_info_url(dataset_id=None, response=None)

Build the info URL for the server endpoint.

Parameters:

• dataset_id (str | None) – a dataset unique id.

• response (str | None) – default is HTML.

Returns:

the info URL for the response chosen.

Return type:

url

get_search_url(response=None, search_for=None, protocol=None, items_per_page=1000, page=1, **kwargs)

Build the search URL for the server endpoint provided.

Parameters:

• search_for (str | None) –

  “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 (str | None) – default is HTML.

• items_per_page (int) – how many items per page in the return, default is 1000 for HTML, 1e6 (hopefully all items) for CSV, JSON.

• page (int) – which page to display, default is the first page (1).

• kwargs – extra search constraints based on metadata and/or coordinates ke/value. metadata: cdm_data_type, institution, ioos_category, keywords, long_name, standard_name, and variableName. coordinates: minLon, maxLon, minLat, maxLat, minTime, and maxTime.

• protocol (str | None) –

Returns:

the search URL.

Return type:

url

get_var_by_attr(dataset_id=None, **kwargs)

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

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

Parameters:

dataset_id (str | None) –

Return type:

List[str]

griddap_initialize(dataset_id=None, step=1)

Fetch metadata of dataset and initialize constraints and variables.

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

Parameters:

• dataset_id (str | None) –

• step (int) –

to_iris(**kw)

Load the data request into an iris.CubeList.

Accepts any iris.load_raw keyword arguments.

to_ncCF(protocol=None, **kw)

Load the data request into a Climate and Forecast compliant netCDF4-python object.

Parameters:

protocol (str) –

to_pandas(requests_kwargs=None, **kw)

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 documentation 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:

requests_kwargs (Dict | None) –

Return type:

DataFrame

to_xarray(requests_kwargs=None, **kw)

Load the data request into a xarray.Dataset.

Accepts any xr.open_dataset keyword arguments.

Parameters:

requests_kwargs (Dict | None) –

erddapy.erddapy.parse_dates(date_time, dayfirst=False, yearfirst=False)

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) –

Return type:

float

erddapy.erddapy.urlopen(url, requests_kwargs=None)

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