GlobalFishingWatch/gfwr: 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 to get_raster()

Note: Some APIs will not be implemented because they were primarily designed for a front-end 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 script and copy the string of the request when filling an issue.

  • Improved documentation in-package, including two vignettes that can be accessed on 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
  • The region argument for get_raster() and get_event() now accepts sf 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 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)
  • 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 of event_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 of spatial_resolution = "low")
  • The region argument now accepts sf polygons rather than a GeoJSON string
  • Parameters start_date and end_date replace date_range for consistency with other functions