Get events from API and convert response to tibble
Usage
get_event(
event_type,
start_date = "2012-01-01",
end_date = "2024-12-31",
sort = "+start",
vessels = NULL,
flags = NULL,
vessel_types = NULL,
region_source = NULL,
region = NULL,
duration = 1,
encounter_types = NULL,
gap_intentional_disabling = NULL,
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"
- 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
- 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
.- vessels
A vector of
vesselIds
, obtained viaget_vessel_info()
. The maximum number ofvesselIds
depends on the character length of the whole request, the request will fail with errorHTTP 422: Unprocessable entity
when too manyvesselIds
are sent. This value is around 2,800 vessels, depending on the other parameters of the request.- 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"
.- region_source
Optional. Source of the region ('EEZ','MPA', 'RFMO' or 'USER_SHAPEFILE').
- region
Optional but required if a value for
region_source
is specified. Ifregion_source
is set to "EEZ", "MPA" or "RFMO", GFW region code (seeget_region_id()
). Ifregion_source = "USER_SHAPEFILE"
,sf
shapefile with the area of interest.- duration
Minimum duration that the event should have (in minutes). The default value is 1.
- encounter_types
Only useful when
event_type = "ENCOUNTER"
. Filters for types of vessels during the encounter. A vector with any combination of:"CARRIER-FISHING"
,"FISHING-CARRIER"
,"FISHING-SUPPORT"
,"SUPPORT-FISHING"
.- gap_intentional_disabling
Logical. Only useful when
event_type = "GAP"
. Filters intentional gap events according to Global Fishing Watch algorithms. Check the gaps API documentation for more details.- confidences
Only useful when
event_type = "PORT_VISIT"
. Confidence levels of port visits. Low-confidence port visits (confidence 1) are not available for download. See the API documentation for more details- key
Character, API token. Defaults to
gfw_auth()
.- 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) { # \dontrun{
library(gfwr)
# port visits
get_event(event_type = "PORT_VISIT",
vessels = c("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("8c7304226-6c71-edbe-0b63-c246734b3c01"),
start_date = "2012-01-30",
end_date = "2024-02-04",
key = gfw_auth())
# fishing
get_event(event_type = "FISHING",
vessels = c("9b3e9019d-d67f-005a-9593-b66b997559e5"),
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 = "2022-01-01",
end_date = "2024-01-01",
region = test_polygon,
region_source = 'USER_SHAPEFILE',
key = gfw_auth())
} # }