gfwr 2.0.4
Aug 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 whenregion_source = "EEZ"
.Fixes issue #208 with
marine_regions
. This should not pose any breaking change on the user side.Improves documentation for
filter_by
inget_raster()
(#209)
gfwr 2.0.3
No breaking changes
Bug fixes
-
geartypes
andshiptypes
will be unnested only when they are returned in the responses–this was causing an error reported in #193 -
get_region_id()
:- MPA, EEZ, RFMO ids are no longer enforced to be numeric, this was causing errors for character and alphanumeric ids in RFMOS and MPAs
-
get_region_id()
can now process empty id strings (""
) and returnNA
tibbles instead of returning an error, this allows to process events happening in the high-seas (#201)
Documentation improvements
-
get_event()
can receive a string of severalvesselIds
(not twenty as previously stated). However, requests that are too long in character length will fail with error HTTP422: Unprocessable entity
. This means around 2,000vesselIDs
can be sent per request. - RFMO documentation was improved to clarify that we have the complete list of RFMOs #194
- The readme has more subsections for easier reference and explicit calls to
gfw_auth()
are no longer suggested.
gfwr 2.0.2
Minor updates in documentation, parameter reordering and improving descriptions. No breaking changes.
gfwr 2.0.1
2024-11-28
Major change - bug fix
- We updated the parsing of the output of
get_vessel_info()
. For some advanced queries usingwhere
, 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)
Breaking changes
-
Some fields in the response were renamed across outputs (addressing issue #146):
-
get_vessel_info()
: in$registryInfo
we renamedid
toregistryId
-
get_event()
: we renamedid
toeventId
andtype
toeventType
-
New features
get_vessel_info()
: We added anindex
column to indicate whichvesselIds
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.
Minor changes
- We updated the
get_event()
section in the README to improve the workflow and send groups ofvesselIds
corresponding to one or multiple vessels.
gfwr 2.0.0
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.
Endpoints
- Same endpoints as in
v1.1.0
-
get_raster()
communicates with the 4Wings API to get fishing effort -
get_vessel_info()
communicates with the Vessels API -
get_event()
communicates with the Events API
-
- New endpoints:
-
get_events_stats()
to get events statistics worldwide or for a specific region -
get_last_report()
to check status of last API request toget_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/:z
Major changes and new features
- General
- Improved documentation in-package, including two vignettes that can be accessed in our website https://globalfishingwatch.github.io/gfwr/
- Functions have a new parameter
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. - The
region
argument forget_raster()
andget_event()
now acceptssf
polygons rather than GeoJSON strings
-
get_vessel_info()
- Incorporated non-fishing vessel types to the datasets. A simple search will return vessels of all vessel types (“CARRIER”, “SUPPORT”, “PASSENGER”, “OTHER_NON_FISHING”, “SEISMIC_VESSEL”, “BUNKER_OR_TANKER”, and “CARGO” in addition to “FISHING”)
-
search_type = search
replacessearch type = "basic"
and"advanced"
. Instead, use parameterquery
for basic search or parameterwhere
for advanced search (i.e. when using SQL expressions) - Registry information is now available: Parameter
includes
allows the search to include ownership information, public authorizations from public registries, and the criteria for matching with AIS data
-
get_event()
- Vessel types supported now include non-fishing vessels: “FISHING”, “CARRIER”, “SUPPORT”, “PASSENGER”, “OTHER_NON_FISHING”, “SEISMIC_VESSEL”, “BUNKER_OR_TANKER”, and “CARGO”
- Event types now include fishing, gaps in AIS transmission, encounters, loitering events and port visits. Fishing events are specific to fishing vessels, loitering events are specific to carrier vessels. Port visits and encounters are available for all vessel types. Parameter
confidence
(1 to 4) allows filtering for high confidence port visits. - All parameters must now be specified using UPPER CASE (ex.
event_type = "FISHING"
instead ofevent_type = "fishing"
) - A user-defined shapefile can now be sent in the requests, as an
sf
object
-
get_raster()
- All parameters must now be specified using UPPER CASE (ex.
spatial_resolution = "LOW"
instead ofspatial_resolution = "low"
) - The
region
argument now acceptssf
polygons rather than a GeoJSON string - Parameters
start_date
andend_date
replacedate_range
for consistency with other functions
- All parameters must now be specified using UPPER CASE (ex.
Additional changes
- Option
USER_JSON
has been renamed toUSER_SHAPEFILE
for clarity (addresses #161)
gfwr 1.1.0
New features:
In addition to your own JSON region, can now pass EEZ or MPA id to
get_raster()
function to query specific regionget_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
Bug fixes:
-
get_event()
prints"Your request returned zero results"
and returnsNULL
when the API response contains no results instead of causing an error.
Other news:
Updated documentation
get_raster()
: requiresgroup_by
and appropriate parameter name isgearType
Added a
NEWS.md
file to track changes to the package.