API Release Notes
Dated log of Global Fishing Watch API releases: new endpoints, dataset versions, deprecations and behavior changes.
Check more detail on how our API versioning process here.
Version 3 Key dates:
-
26 October 2023: v3 was released in production, you can start using it. Version 3 is our 🟢 CURRENT version. Check the Migration Guide here. Version 2 is in 🟠 MAINTENANCE.
-
Originally released in October 2023, version 3 introduced several enhancements and features to improve performance, consistency, and integration possibilities.
-
30 April 2024: v2 is 🔴 DEPRECATED: The endpoint is not operational. No improvements or bug fixing are added.
For questions, please write to apis@globalfishingwatch.org
| Change | API impacted | Description |
|---|
| Updated data available in API and packages | N/A | We updated our document comparing the data available through the API Portal, the R package gfwr, the Python package… View the comparison PDF. |
| Change | API impacted | Description |
|---|
| New vessel registry data sources | Vessels API | New registry sources are now contributing to vessel identity records. S&P Global Ships Data appears as SNP and builds on the IMO source, expanding fields such as ownership, year built, length and gross tonnage (where available); due to licensing, only records where S&P is combined with at least one other source are distributed. Three new TMT compliance sources — the US Treasury OFAC sanctioned vessel list, the ILO seafarer-abandonment list, and Paris MOU detention records — appear under the existing TMT_Other_Official code. See Registry Codes - Data Sources. |
| IMO source partially retired | Vessels API | As of June 2026, manually ingested IMO records (IMO1, IMO2, IMO3) for fishing and fishing support vessels are being retired and superseded by S&P Global (SNP), where available. A limited set of static IMO records is retained for selected non-fishing vessels, so users may notice a shift in the registry sources listed on vessel profiles. |
| Change | API impacted | Description |
|---|
| Added API Dataset filtering and response field | Bulk Download API | The Get All Bulk Reports by User endpoint now supports filtering reports by API Dataset, including an alias such as public-fixed-infrastructure-data:latest or the resolved versioned value returned in the report response. Bulk report responses now include the dataset field, making it easier to identify and retrieve reports generated for a specific API Dataset. See the Bulk Download API for usage details. |
| Change | API impacted | Description |
|---|
| Rate limit improvements | All | Added proper error code, custom headers and updated rate limits to enable users to monitor usage properly. Check more details here |
| Change | API impacted | Description |
|---|
| New AIS data released - version 4 | All APIs | New API datasets v4 were creating based on the new version of the AIS data pipeline version 4. For more details check the API dataset section here and find version 4 release notes here. |
| Change | API impacted | Description |
|---|
| New Resource | All APIs | Added comprehensive API Workflows Guide - A detailed PDF guide showing practical examples of how to combine Global Fishing Watch APIs to build powerful workflows and applications. The guide covers common use cases including vessel activity analysis, regional monitoring, fleet management, and dark vessel detection. Access the guide here. |
| Change | API impacted | Description |
|---|
| Updated region logic | 4Wings, Events API | The logic for populating the iso3 field in the public-eez-areas dataset has been updated to reflect more accurate geopolitical boundaries based on Marine Regions data. This includes specific rules for handling joint regimes, overlapping claims, and 200NM zones. Additional fields (isoSov1, isoSov2, isoSov3, territory1) are now exposed in the response. See details and examples in the Regions section. |
| Change | API impacted | Description |
|---|
Added distance_from_port_km filter | 4Wings API Report | You can now filter fishing activity by distance from port using the distance_from_port_km filter within the filters[] parameter. This allows users to remove low-speed activity close to port areas, improving accuracy. This filter is particularly useful for example, in dynamic reports in order to remove nearshore apparent fishing effort false positives. See details and usage in the 4Wings API. |
| Change | API impacted | Description |
|---|
| Included Response details | 4Wings report | Added detail of the response fields for the 4wings report endpoint |
Removed param gap-intentional-disabling and gapIntentionalDisabling | Events API Get All Events (GET and POST endpoint) | We’ve removed the gap-intentional-disabling and gapIntentionalDisabling parameters from the Events API. This is because all current AIS-off events are only intentional gaps, making these parameters unnecessary. There is currently no way to filter for unintentional gaps. This dataset is still in the prototype stage, but we are working on a production version. If you are interested in this dataset, please contact us at apis@globalfishingwatch.org. For more information about prototype stage or available datasets, please see the API Datasets page. |
| Change | API impacted | Description |
|---|
| Bulk Download API released for SAR Fixed infrastructure data | Bulk Download API | We've launched a new API: Bulk Download. This new API is designed to provide researchers and developers with a new asynchronous method for efficiently accessing and downloading larger volumes of data. We will be releasing several datasets for this new API. This time we are releasing with global offshore infrastructure detections from 2017 to approximately 3 months ago, using Sentinel-1 and Sentinel-2 imagery classified with deep learning. The dataset includes some noisy detections filtered out in the Map and Datasets API. See the Bulk Download API for usage examples and caveats. For more information, visit our Platform and Data Updates page. |
| Change | API impacted | Description |
|---|
| AIS Vessel Presence dataset released | 4Wings API | We’ve added the public-global-presence:v3.0 dataset to the 4Wings API. This dataset provides access to vessel presence data derived directly from AIS signals, available globally from 2012 to 96 hours ago. It is now available via all major 4Wings endpoints: /tile/heatmap, /report, /generate-png, /stats, /last-report, and /interaction. The dataset can support use cases such as maritime traffic baselining, MPA monitoring, and maritime behavior analysis. See the 4Wings API documentation for full usage details and parameters. For more information, visit our Platform and Data Updates page. |
| Change | API impacted | Description |
|---|
| New Python client package released | Vessels API, Events API, 4Wings API, Insights API | The official release of gfw-api-python-client — a lightweight, open-source Python package to access GFW APIs with built-in functions for apparent fishing effort, vessel identity, SAR vessel detections and vessel events data. Read more. |
| Data differences between API, gfwr, Python client, and Data Downloads portal | N/A | We updated our document comparing the data available through the API Portal, the R package gfwr, the Python package gfw-api-python-client, and the Data Downloads portal. View the comparison PDF. |
| Change | API impacted | Description |
|---|
| More detail in TMT sources | Vessels API | The Vessel API now offers more detailed source information from TMT. We've broken down the TMT source into granular categories like TMT_National. See more details in the list of sources here. Learn more about this release here |
| Change | API impacted | Description |
|---|
| Old AIS dataset v20231026 deprecated | All APIs | As of January 28, 2025, the latest AIS data version is v3 (details about v3 are available here). The previous version, v20231026, has been deprecated. While originally scheduled for deprecation in February 2025, this was accelerated due to low usage and high maintenance costs. Please note that comparing data outputs between v20231026 and v3 is currently not possible. Find more information here. |
| Change | API impacted | Description |
|---|
| minLat,maxLat,minLon,maxLon changes | 4wings API (Stats) | The fields minLat, minLon, maxLat, maxLon fields are only supported when the endpoint is used with the vessel-groups filter applied. |
| Change | API impacted | Description |
|---|
| SAR fixed infrastructure dataset | Dataset API | The SAR fixed infrastructure MVT data response now includes more infrastructure positions, since we removed a filter on the data. It was excluding infrastructures with cluster_detections >=3, they’re mostly labeled oil and have 2 cluster detections. This may indicate that they’re moving around, since the cluster_detections filter indicates how many times that structure has been detected in that location. Now they are added in the response. |
| Change | API impacted | Description |
|---|
| SAR fixed infrastructure dataset | Dataset API | The SAR fixed infrastructure MVT data response now includes lat (latitude) and lon (longitude) fields. These coordinates provide precise geographic locations for fixed infrastructure. |
| Change | API impacted | Description |
|---|
| New TMT registry source | Vessels API | We added TMT as new source in our Vessel API which also adds new object extraFields as part of registryInfo including fields like builtYear and depthM when available. |
| Port visits updates | Events API | There are two important updates regarding port visits dataset: 1) We have resolved an issue affecting a small percentage of confidence 4 level port visit events. The data provided should now be more accurate. 2) We’ve updated the method for determining port visit locations to use the intermediate anchorage or the first Port Stop (or Port Gap if no Port Stop exists) for more accurate estimates. Therefore a new API dataset public-global-port-visits-events:v3.1 was created including this method. Previous one still exists, check API dataset section here. For more details of both of these data changes, please refer to this FAQ. |
| New param for Events Stats | Events Stats POST endpoint | We added new param includes and vesselType. For more details check Events Stats POST endpoint here |
| New postman collection | Events API and Vessel API | More examples were added to show the new changes. |
| Documents explaining what API are behind Vessel Viewer | N/A | If you want to learn which APIs are used in Vessel Viewer, you can review this document showing the exact API requests done behind each page. |
| Change | API impacted | Description |
|---|
| Vessel authorizations | Vessels API | Remove some logic that was merging authorizations if the end date of the one authorization and the start date of the next one are close and the source is the same. The new logic will return two or more authorizations instead of only one in these cases. For example, for vessel Milena A (IMO 7342287), originally the API returns on the registry object, one authorization for IATTC from May 1 2019 to Jun 1 2024. We fixed that and now it returns 2 auhorizations periods for IATTC from Mar 1, 2024 - Aug 1, 2024 and from May 1, 2019 - Nov 1, 2023 |
| Change | API impacted | Description |
|---|
| New AIS data released | All APIs | New API datasets v3 were creating based on the new version of the AIS data pipeline version 3. For more details check the API dataset section here. Additionally, we updated the this document with a detailed comparison between the data in this API Portal, gfwr 2.0.0 and Data Download Portal. |
| Change | API impacted | Description |
|---|
| SAR vessel detection dataset | All 4Wings endpoints | We added SAR vessel detections dataset, which are industrial vessels between 2017 to 5 days ago that were detected with satellite imagery and classified with deep learning. For more detail check the Paper Paolo et al. 2024, Nature.. You can find more details of the new dataset in API Dataset section. |
| Change | API impacted | Description |
|---|
| Changed bins 4wings endpoint | 4wings | Implemented same behaviour of the map to calculate bins for zoom levels greater than 0. Those levels are calculated using the values of zoom 0 and divide them by 4 ^ zoom requested. |
| Change | API impacted | Description |
|---|
| New Postman collection | All | Added a new version of our postman collection with several examples for each endpoint. |
| Change | API impacted | Description |
|---|
| New insights and counters | Insights API | Added new vessel identity insight: if the vessel is present on an RFMO IUU vessel list and added two counters in the response. |
| New field for MVT tile | 4Wings API (/tile/heatmap/) | For MVT format, added in the response a id property in each feature (cell) of the mvt that it’s a combination of {z}/{x}/{y}/{cell} which makes the id always unique. |
Error in underlying AIS data in the Global Fishing Watch platform and APIs
If you accessed Global Fishing Watch AIS data between 26 January - 10 April 2024, there may be errors in the fishing effort and fishing event data.
The AIS error has been resolved.
Our advice is to repeat any analysis completed with the correct data. We’re sorry for any inconvenience caused.
Learn more here
.
Included endpoint to obtain last report generated by the user
| Change | API impacted | Description |
|---|
| New last report endpoint | 4wing API (Reports) | New Last report endpoint to obtain the last report generated by the user (recommended specially in case of 429 error) |
| Change | API impacted | Description |
|---|
| Marine Traffic new AIS source | All | AIS data has been enhanced by the new addition of Marine Traffic terrestrial receivers. The Marine Traffic data is located in three high density areas where satellite reception can be poor around the globe, specifically the Mediterranean Sea, South China Sea, and the North Sea. Learn more here. |
New major version 3 including new version of Vessel API and Insights API for vessels
| Change | API impacted | Description |
|---|
| v3 | Vessel API - NEW VERSION | Major change in this version, it is a completely new API that includes data from regional and national registries |
| v3 | Insights API - NEW API | New API including vessel indicators like AIS off events |
| v3 | 4Wings API and Events API | All the enums in query params and body must be uppercase and other small but breaking changes |
For the full details about API Version 3 changes, check the Migration Guide here
Add 2 new APIs: 4Wings Stats API and Events Stats API
| Change | API impacted | Description |
|---|
| New Stats API | 4Wings and Events API | We added new APIs to get statistics about fishing effort 4Wings Stats API and about Events worldwide or for a custom region. Events Stats API |
Support Region ID in All Events POST endpoint
| Change | API impacted | Description |
|---|
| Support to send region id | Events API (POST) | If users don't want to send a custom polygon, now it is possible to send a specific region id based on the Reference Data. See EXAMPLE 5 in Events API POST |
Change RFMO dataset to include all RFMOs
| Change | API impacted | Description |
|---|
| Change RFMO dataset | Reference Data - Dataset | We used to have as dataset public-tuna-rfmo and we change it to public-rfmo to include all RFMOs. |
Change behavior of dates filter in events
| Change | API impacted | Description |
|---|
| Update behavior dates filter | Events | Now the startDate (start-date) and endDate(end-date) filters in list events and dateRange in get tile of events, their behavior change to filter the events that they are occurring inside of the interval ( [startDate, endDate) ) instead of filter the events that start or finish inside the interval |
Create new POST endpoint to obtain events with more filter options
| Change | API impacted | Description |
|---|
| New list events endpoint | Events | New POST endpoint to obtain list of events with more filter options |
Added limitations in reports and new endpoints and filters
| Change | API impacted | Description |
|---|
| date-range limit | Reports | Now the date range must be lower than or equal to 1 year |
| Get all Events | Events | New POST endpoint with more filters for get all events |
| New report options | Reports | New group by option (mmsi) and reports without spatial aggregation (spatial-aggregation) |
First public version including consistency changes.
| Change | API impacted | Description |
|---|
| Param names | All endpoints | Params are now in lower case between "-", for example instead of endDate in v2 we have end-date |
| Change to POST | 4wings/generate-png | Verb now is POST, it used to be in v1 GET |
| New error format and codes | All endpoints | Standard responses and status codes for all errors |
| New format for list resources | All list endpoints | New paginated format for list resources endpoints |
| Sort query params | All list endpoints | Merge sortBy and sortOrderin only one query param called sort. Example: sort=+createdAt |
| Pagination query params | All list endpoints | Pagination query (limit and offset) params are required instead of optional |
Initial alpha release.
