Base function to get events stats from API and convert response to data frame

get_event_stats(
  event_type,
  encounter_types = NULL,
  vessels = NULL,
  vessel_types = NULL,
  start_date = "2012-01-01",
  end_date = "2024-12-31",
  region_source = NULL,
  region = NULL,
  interval = NULL,
  duration = 1,
  confidences = c(2, 3, 4),
  key = gfw_auth(),
  quiet = FALSE,
  print_request = FALSE,
  ...
)

Arguments

event_type: Type of event to get data of. A vector with any combination of "ENCOUNTER", "FISHING", "GAP", "LOITERING", "PORT_VISIT"
encounter_types: Filters for types of vessels during the encounter. A vector with any combination of: "CARRIER-FISHING", "FISHING-CARRIER", "FISHING-SUPPORT", "SUPPORT-FISHING"
vessels: A vector of vesselIds, obtained via the get_vessel_info() function
vessel_types: Optional. A vector of vessel types, any combination of: "FISHING", "CARRIER", "SUPPORT", "PASSENGER", "OTHER_NON_FISHING", "SEISMIC_VESSEL", "BUNKER_OR_TANKER", "CARGO"
start_date: Start of date range to search events, in YYYY-MM-DD format and including this date
end_date: End of date range to search events, in YYYY-MM-DD format and excluding this date
region_source: Optional but mandatory if using the argument region. Source of the region. If 'EEZ','MPA', 'RFMO', then the value for the argument region must be the code for that region. If 'USER_SHAPEFILE', then region has to be an sf object
region: GFW region code (such as an EEZ, MPA or RFMO code) or a formatted geojson shape. See Details about formatting the geojson.
interval: Time series granularity. Must be a string. Possible values: 'HOUR', 'DAY', 'MONTH', 'YEAR'.
duration: duration, in minutes, of the event, ex. 30
confidences: Confidence levels (1-4) of events (port visits only)
key: Authorization token. Can be obtained with gfw_auth() function
quiet: Boolean. Whether to print the number of events returned by the request
print_request: Boolean. Whether to print the request, for debugging purposes. When contacting the GFW team it will be useful to send this string
...: Other arguments

Details

There are currently four available event types and these events are provided for three vessel types - fishing, carrier, and support vessels. Fishing events (event_type = "FISHING") are specific to fishing vessels and loitering events (event_type = "LOITERING") are specific to carrier vessels. Port visits (event_type = "PORT_VISIT") and encounters (event_type = "ENCOUNTER") are available for all vessel types. For more details about the various event types, see the GFW API documentation.

The user-defined geojson has to be surrounded by a geojson tag, that can be created using a simple paste:

geojson_tagged <- paste0('{"geojson":', your_geojson,'}').

If you have an sf shapefile, you can also use function sf_to_geojson() to obtain the correctly-formatted geojson.

Examples

if (FALSE) {
library(gfwr)
 # stats for encounters involving Russian carriers in given time range
get_event_stats(event_type = 'ENCOUNTER',
encounter_types = c("CARRIER-FISHING","FISHING-CARRIER"),
vessel_types = 'CARRIER',
start_date = "2018-01-01",
end_date = "2023-01-31",
flags = 'RUS',
duration = 60,
interval = "YEAR",
key = gfw_auth())
 # port visits stats in a region (Senegal)
 get_event_stats(event_type = 'PORT_VISIT',
start_date = "2018-01-01",
end_date = "2019-01-31",
confidences = c('3','4'),
region = 8371,
region_source = 'EEZ',
interval = "YEAR")
}