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

get_event(
  event_type,
  encounter_types = NULL,
  vessels = NULL,
  flags = NULL,
  vessel_types = NULL,
  start_date = "2012-01-01",
  end_date = "2024-12-31",
  region = NULL,
  region_source = NULL,
  gap_intentional_disabling = NULL,
  duration = 1,
  confidences = c(2, 3, 4),
  limit = 99999,
  offset = 0,
  sort = "+start",
  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
flags: ISO3 code for the flag of the vessels. Null by default.
vessel_types: 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: sf shape to filter raster or GFW region code (such as an EEZ code). See details about formatting the geojson
region_source: source of the region ('EEZ','MPA', 'RFMO' or 'USER_SHAPEFILE')
gap_intentional_disabling: Logical. Whether the Gap events are intentional, according to Global Fishing Watch algorithms
duration: duration, in minutes, of the event, ex. 30
confidences: Confidence levels (1-4) of events (port visits only)
limit: Limit
offset: Offset
sort: How to sort the events. By default, +start, which sorts the events in ascending order (+) of the start dates of the events. Other possible values are -start, +end, -end.
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.

Encounter events involve multiple vessels and one row is returned for each vessel involved in an encounter. For example, an encounter between a carrier and fishing vessel (CARRIER-FISHING) will have one row for the fishing vessel and one for the carrier vessel. The id field for encounter events has two components separated by a .. The first component is the unique id for the encounter event and will be the same for all vessels involved in the encounter. The second component is an integer used to distinguish between different vessels in the encounter.

Examples

if (FALSE) {
library(gfwr)
# port visits
get_event(event_type = "PORT_VISIT",
          vessels = c("e0c9823749264a129d6b47a7aabce377",
          "8c7304226-6c71-edbe-0b63-c246734b3c01"),
          start_date = "2017-01-26",
          end_date = "2017-12-31",
          confidence = c(3, 4), # only for port visits
          key = gfw_auth())
 #encounters
 get_event(event_type = "ENCOUNTER",
 vessels = c("e0c9823749264a129d6b47a7aabce377",
  "8c7304226-6c71-edbe-0b63-c246734b3c01"),
  start_date = "2018-01-30",
  end_date = "2023-02-04",
  key = gfw_auth())
 # fishing
 get_event(event_type = "FISHING",
 vessels = c("8c7304226-6c71-edbe-0b63-c246734b3c01"),
  start_date = "2017-01-26",
  end_date = "2023-02-04",
  key = gfw_auth())
 # GAPS
 get_event(event_type = "GAP",
 vessels = c("e0c9823749264a129d6b47a7aabce377",
  "8c7304226-6c71-edbe-0b63-c246734b3c01"),
  start_date = "2017-01-26",
  end_date = "2023-02-04",
  key = gfw_auth())
 # loitering
 get_event(event_type = "LOITERING",
 vessels = c("e0c9823749264a129d6b47a7aabce377",
  "8c7304226-6c71-edbe-0b63-c246734b3c01"),
  start_date = "2017-01-26",
  end_date = "2023-02-04",
  key = gfw_auth())
 # encounter type
 get_event(event_type = "ENCOUNTER",
 encounter_types = "CARRIER-FISHING",
 start_date = "2020-01-01",
 end_date = "2020-01-31",
 key = gfw_auth())
 # vessel types
 get_event(event_type = "ENCOUNTER",
 vessel_types = c("CARRIER", "FISHING"),
 start_date = "2020-01-01",
 end_date = "2020-01-31",
 key = gfw_auth())
# fishing events in Senegal EEZ
get_event(event_type = 'FISHING',
              start_date = "2020-10-01",
              end_date = "2020-12-31",
              region = 8371,
              region_source = 'EEZ',
              flags = 'CHN',
              key = gfw_auth())

# fishing events in user shapefile
test_polygon <- sf::st_bbox(c(xmin = -70, xmax = -40, ymin = -10, ymax = 5),
 crs = 4326) |>
 sf::st_as_sfc() |>
 sf::st_as_sf()
get_event(event_type = 'FISHING',
              start_date = "2020-10-01",
              end_date = "2020-12-31",
              region = test_polygon,
              region_source = 'USER_SHAPEFILE',
              key = gfw_auth())
              }