Title: | Access data from Global Fishing Watch APIs |
---|---|
Description: | This package connects to several Global Fishing Watch APIs to get vessel and events information in an R-friendly format. |
Authors: | Tyler Clavelle [aut, cre] , Rocío Joo [aut] , Nate Miller [aut], Andrea Sánchez-Tapia [aut] |
Maintainer: | Tyler Clavelle <[email protected]> |
License: | Apache License (>= 2) |
Version: | 2.0.0 |
Built: | 2024-10-02 05:30:04 UTC |
Source: | https://github.com/GlobalFishingWatch/gfwr |
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, ... )
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, ... )
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 |
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 |
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.
## Not run: 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()) ## End(Not run)
## Not run: 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()) ## End(Not run)
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, ... )
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, ... )
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 |
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 |
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.
## Not run: 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") ## End(Not run)
## Not run: 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") ## End(Not run)
Function to check the status of the last API request sent with get_raster().
get_last_report(key = gfw_auth())
get_last_report(key = gfw_auth())
key |
Authorization token. Can be obtained with |
The get_last_report()
function will tell you if the APIs are still processing your request and
will download the results if the request has finished successfully. You will receive an error message
if the request finished but resulted in an error or if it's been >30 minutes since the last report was
generated using get_raster()
.
For more information, see the https://globalfishingwatch.org/our-apis/documentation#get-last-report-generated.
## Not run: get_last_report(key = gfw_auth()) ## End(Not run)
## Not run: get_last_report(key = gfw_auth()) ## End(Not run)
Base function to get raster from API and convert response to data frame
get_raster( spatial_resolution = NULL, temporal_resolution = NULL, group_by = NULL, filter_by = NULL, start_date = NULL, end_date = NULL, region = NULL, region_source = NULL, key = gfw_auth(), print_request = FALSE )
get_raster( spatial_resolution = NULL, temporal_resolution = NULL, group_by = NULL, filter_by = NULL, start_date = NULL, end_date = NULL, region = NULL, region_source = NULL, key = gfw_auth(), print_request = FALSE )
spatial_resolution |
raster spatial resolution. Can be "LOW" = 0.1 degree or "HIGH" = 0.01 degree |
temporal_resolution |
raster temporal resolution. Can be 'HOURLY', 'DAILY', 'MONTHLY', 'YEARLY' |
group_by |
parameter to group by. Can be 'VESSEL_ID', 'FLAG', 'GEARTYPE', 'FLAGANDGEARTYPE' or 'MMSI'. Optional. |
filter_by |
parameter to filter by. |
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 a Marine Regions Geographic Identifier or EEZ code). |
region_source |
source of the region ('EEZ','MPA', 'RFMO' or 'USER_SHAPEFILE') |
key |
Authorization token. Can be obtained with |
print_request |
Boolean. Whether to print the request, for debugging purposes. When contacting the GFW team it will be useful to send this string |
## Not run: library(gfwr) # using region codes code_eez <- get_region_id(region_name = 'CIV', region_source = 'EEZ', key = gfw_auth()) get_raster(spatial_resolution = 'LOW', temporal_resolution = 'YEARLY', group_by = 'FLAG', start_date = "2021-01-01", end_date = "2021-10-01", region = code_eez$id, region_source = 'EEZ', key = gfw_auth(), print_request = TRUE) #using a sf from disk /loading a test sf object data(test_shape) get_raster(spatial_resolution = 'LOW', temporal_resolution = 'YEARLY', start_date = '2021-01-01', end_date = '2021-10-01', region = test_shape, region_source = 'USER_SHAPEFILE', key = gfw_auth(), print_request = TRUE) ## End(Not run)
## Not run: library(gfwr) # using region codes code_eez <- get_region_id(region_name = 'CIV', region_source = 'EEZ', key = gfw_auth()) get_raster(spatial_resolution = 'LOW', temporal_resolution = 'YEARLY', group_by = 'FLAG', start_date = "2021-01-01", end_date = "2021-10-01", region = code_eez$id, region_source = 'EEZ', key = gfw_auth(), print_request = TRUE) #using a sf from disk /loading a test sf object data(test_shape) get_raster(spatial_resolution = 'LOW', temporal_resolution = 'YEARLY', start_date = '2021-01-01', end_date = '2021-10-01', region = test_shape, region_source = 'USER_SHAPEFILE', key = gfw_auth(), print_request = TRUE) ## End(Not run)
Function to pull numeric code using region name
get_region_id(region_name, region_source = "EEZ", key = gfw_auth())
get_region_id(region_name, region_source = "EEZ", key = gfw_auth())
region_name |
string or numeric, EEZ/MPA/RFMO name or id |
region_source |
string, source of region data ('eez', 'mpa', 'rfmo') |
key |
string, API token |
dataframe, eez code and EEZ name for matching EEZs
List of available regions
get_regions(region_source = "EEZ", key = gfw_auth())
get_regions(region_source = "EEZ", key = gfw_auth())
region_source |
string, source of region data ('eez', 'mpa', 'rfmo') |
key |
string, API token |
dataframe, all region ids and names for specified region type
Base function to get vessel information from API and convert response to data frame
get_vessel_info( query = NULL, where = NULL, ids = NULL, includes = c("AUTHORIZATIONS", "OWNERSHIP", "MATCH_CRITERIA"), match_fields = NULL, registries_info_data = c("ALL"), search_type = "search", key = gfw_auth(), print_request = FALSE, ... )
get_vessel_info( query = NULL, where = NULL, ids = NULL, includes = c("AUTHORIZATIONS", "OWNERSHIP", "MATCH_CRITERIA"), match_fields = NULL, registries_info_data = c("ALL"), search_type = "search", key = gfw_auth(), print_request = FALSE, ... )
query |
When |
where |
When |
ids |
When |
includes |
Enhances the response with new information, defaults to include all.
|
match_fields |
Optional. Allows to filter by |
registries_info_data |
when
|
search_type |
Type of vessel search to perform. Can be |
key |
Authorization token. Can be obtained with |
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 parameters, such as limit and offset |
When search_type = "search"
the search takes basic identity features like
MMSI, IMO, callsign, shipname as inputs, using parameter "query"
. For more advanced
SQL searches, use parameter "where"
. You can combine logic operators like AND
,
OR
, =
, >=
, <, LIKE
(for fuzzy matching). The id
search allows the user
to search using a GFW vessel id.
## Not run: library(gfwr) # Simple searches, using includes get_vessel_info(query = 224224000, search_type = "search", key = gfw_auth()) # Advanced search with where instead of query: get_vessel_info(where = "ssvid = '441618000' OR imo = '9047271'", search_type = "search", key = gfw_auth()) # Vessel id search get_vessel_info(search_type = "id", ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01", "6583c51e3-3626-5638-866a-f47c3bc7ef7c"), key = gfw_auth()) all <- get_vessel_info(search_type = "id", ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01"), registries_info_data = c("ALL"), key = gfw_auth()) none <- get_vessel_info(search_type = "id", ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01"), registries_info_data = c("NONE"), key = gfw_auth()) delta <- get_vessel_info(search_type = "id", ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01"), registries_info_data = c("DELTA"), key = gfw_auth()) ## End(Not run)
## Not run: library(gfwr) # Simple searches, using includes get_vessel_info(query = 224224000, search_type = "search", key = gfw_auth()) # Advanced search with where instead of query: get_vessel_info(where = "ssvid = '441618000' OR imo = '9047271'", search_type = "search", key = gfw_auth()) # Vessel id search get_vessel_info(search_type = "id", ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01", "6583c51e3-3626-5638-866a-f47c3bc7ef7c"), key = gfw_auth()) all <- get_vessel_info(search_type = "id", ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01"), registries_info_data = c("ALL"), key = gfw_auth()) none <- get_vessel_info(search_type = "id", ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01"), registries_info_data = c("NONE"), key = gfw_auth()) delta <- get_vessel_info(search_type = "id", ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01"), registries_info_data = c("DELTA"), key = gfw_auth()) ## End(Not run)
Get user API token from .Renviron
gfw_auth()
gfw_auth()
An sf shapefile to show as an example of user-defined GeoJSON in get_event() and get_raster()
test_shape
test_shape
A shapefile with a single polygon.