This is a major release of the package, with several changes and additions.
Prefix change: All gfwr functions are now prefixed with gfw_ to make a
direct reference to the package. This replaces the prefix get_.
This allows functions from the package to appear together in searches and menus, and avoids possible confusion with other functions starting with "get_" in other R packages
In addition to the prefix change, get_raster() was renamed to
gfw_ais_fishing_hours() to avoid confusion with the new incoming "raster"
datasets implemented in this version and to be consistent with the output of the
model, which is expressed in (apparent) fishing hours.
The two datasets in the package were also renamed to gfw_: gfw_marine_regions and gfw_test_shape
In gfw_region_id(), the parameter region_name was renamed to region for precision, since it accepts both region names and ISO codes. (#196)
gfw_ais_presence() implements the AIS-based Vessel presence dynamic
dataset, which can be found in the Global Fishing Watch map.
This dataset aggregates the presence of all vessels (fishing and non-fishing), expressed in hours of activity in each cell.gfw_sar_vessel_detections() incorporates the SAR-based vessel detections
(presence), also found in the map. See Paolo et al 2024 for more details.gfw_event() has no longer the gap_intentional_disabling parameter because all gaps returned are high confidence and considered to be intentional:
gfw_event_stats() (previously get_event_stats()) filter by flag (#215)gfw_marine_regions dataset (previously marine_regions) is available without attaching gfwr (thanks to @jaseeverett)includes parameter of gfw_vessel_info(), reported in #231Aug 5 2025
No breaking changes
Adds a new dataset, marine_regions, an in-package version of the modified
Marine Regions v12 table to retrieve IDs when region_source = "EEZ".
Fixes issue #208 with marine_regions. This should not pose any breaking change
on the user side.
Improves documentation for filter_by in get_raster() (#209)
No breaking changes
geartypes and shiptypes will be unnested only when they are returned in the
responses--this was causing an error reported in #193get_region_id():
get_region_id() can now process empty id strings ("") and return NA
tibbles instead of returning an error, this allows to process events happening
in the high-seas (#201)get_event() can receive a string of several vesselIds (not twenty as
previously stated). However, requests that are too long in character length will
fail with error HTTP 422: Unprocessable entity. This means around 2,000
vesselIDs can be sent per request.gfw_auth() are no longer suggested.Minor updates in documentation, parameter reordering and improving descriptions. No breaking changes.
2024-11-28
get_vessel_info(). For some advanced
queries using where, the function was returning only a subset of the vessels.
This issue is now solved and the number of results should be equal to the number
of vessels returned by Vessel Viewer on our map. (solves #176)Some fields in the response were renamed across outputs (addressing issue #146):
get_vessel_info(): in $registryInfo we renamed id to registryIdget_event(): we renamed id to eventId and type to eventTypeget_vessel_info(): We added an index column to indicate which vesselIds
are grouped together and belong to the same vessel. This should help associate
information from the returned datasets and guide the user when requesting events
for a single vessel or a group of vessels.
get_event(): We unnested the column-list "vessel" to give more visibility to
the vessels each event corresponds to.
get_event() section in the README to improve the workflow and
send groups of vesselIds corresponding to one or multiple vessels.gfwr was updated to work with version 3 of our APIs. This results in various breaking changes in
parameter names and output formats. We aim to list here the major modifications but please also
check the API documentation
and the migration guide
if anything is new or missing.
Same endpoints as in v1.1.0
get_raster() communicates with the 4Wings API to get fishing effortget_vessel_info() communicates with the Vessels APIget_event() communicates with the Events APINew endpoints:
get_events_stats() to get events statistics worldwide or for a specific
regionget_last_report() to check status of last API request to get_raster()Note: Some APIs were not implemented because they were primarily designed for a frontend application rather than for data download. These APIs are:
/v3/4wings/generate-png/v3/4wings/tile/:type/:z/:x/:y/v3/4wings/interaction/{z}/{x}/{y}/{cells}/v3/4wings/bins/:zGeneral
print_request that will print the API request and
will be useful when requesting support. Please describe the problem, send a simplified
script and copy the string of the request when filling an issue.region argument for get_raster() and get_event() now accepts sf polygons rather than GeoJSON stringsget_vessel_info()
search_type = search replaces search type = "basic" and "advanced". Instead, use parameter query for basic search or parameter where for advanced search (i.e. when using SQL expressions)includes allows the search to include ownership information, public authorizations from public registries, and the criteria for matching with AIS dataget_event()
confidence (1 to 4) allows filtering for high confidence port visits.event_type = "FISHING" instead of event_type = "fishing")sf objectget_raster()
spatial_resolution = "LOW" instead of spatial_resolution = "low")region argument now accepts sf polygons rather than a GeoJSON stringstart_date and end_date replace date_range for consistency with other functionsUSER_JSON has been renamed to USER_SHAPEFILE for clarity (addresses #161)In addition to your own JSON region, can now pass EEZ or MPA id to get_raster() function to query specific region
get_region_id() now takes id and returns label. This allows you to get the label for the id values returned by certain endpoints (e.g. get_event())
Considerable speed increases in get_event() function
get_event() prints "Your request returned zero results" and returns NULL when the API response contains no results instead of causing an error.get_raster(): requires group_by and appropriate parameter name is gearType
Added a NEWS.md file to track changes to the package.
gfwr package. It includes functions to access three GFW APIs - Vessels API, Events API, and Map Visualization (4Wings) API.