get_tides: Retrieves tide extremes data

In CamiloCarneiro/eneRgetics: Estimates the Maintenance Metabolism of shorebirds

Retrieves tide extremes data

Description

get_tides retrieves information on low and high tides (time and height) for a given location and time period from www.worldtides.info.

Usage

get_tides(lat, lon, start_date, end_date, tzone = "GMT", API_key,
  stationDistance = 5)

Arguments

lat	latitude coordinates in decimal degrees.
lon	longitude coordinates in decimal degress.
start_date	starting date of sampling period in 'yyyy-mm-dd' format.
end_date	ending date of sampling period in 'yyyy-mm-dd' format.
tzone	time zone for the sampling location. Default is "GMT".
API_key	a string with the API key obtained from www.worldtides.info.
stationDistance	maximum distance (in kilometers) from a tidal station. See Details.

Details

get_tides returns information on measurement location, date and time (GMT) of tide extreme occurrence, type of tide extreme (*i.e.* low or high tide peak) and height of extreme (meters) for the period requested.

To obtain an API key, registration on www.worldtides.info is required. Each account provides a monthly trial period with 100 API calls; any further requests require the purchase of credits or a subscription. Please see https://www.worldtides.info/billing for more details.

A single API call retrieves up to 7 days of tide extremes data. If more than 7 days of tide extremes data are required, the number of API calls will be specified accordingly internally. Take care while selecting dates to ensure control over API usage. To help doing so, the number of API calls is printed in the console with each function call.

The parameter stationDistance defines the maximum distance from which to return tidal data from a tidal station instead of using the global background data. When this parameter is set to 0 no results from stations will be returned but only global background data.

Note that tzone is required to ensure data is returned for the appropriate time period at the given location as the API works with UTC time (which is equal to the GMT time zone). This also ensures compatibility with data retrieved by get_weather. For details on accepted timezones, see OlsonNames.

For more details regarding API usage and data quality, please visit https://www.worldtides.info/apidocs.

Value

A dataframe with sampling location, date and time, height and type of tide extremes at the requested location.

Examples

## Pass a standard request to WorldTides API
get_tides(52.000, 3.283, "2018-01-01", "2018-01-03", "example_API_key")

## Obtaining data for a longer time period
get_tides(52.000, 3.283, "2018-01-01", "2018-01-31", "example_API_key")

## Obtaining data for a different time zone
## Change the acceptable station distance to within 10km
get_tides(-9.494, -35.567, "2018-01-01", "2018-01-03", "example_API_key",
tz="Brazil/East", stationDistance=10)

CamiloCarneiro/eneRgetics documentation built on April 23, 2023, 4:20 p.m.