Global Fishing Watch API
API Workflows

Analyzing a Fleet (a Group of Vessels)

Combine the 4Wings, Vessels and Events APIs to analyze a fleet of vessels across fishing activity, identity and event history.

This workflow shows how to analyze a fleet — a group of vessels — by combining the 4Wings API, the Vessels API, and the Events API across multiple vessel IDs.

Use Case: Monitoring a Fleet of Tuna Purse Seiners for Compliance

Kwame is a fisheries compliance officer in Ghana, responsible for monitoring a fleet of tuna purse seiners operating within Ghana's Exclusive Economic Zone (EEZ). His goal is to:

  • ✅ Track apparent fishing activity for tuna purse seiners over the last 12 months.
  • ✅ Identify potential vessels in this fleet, their operational patterns, and their activity levels.
  • ✅ Retrieve vessel details, including flag state, ownership history, and authorizations.
  • ✅ Analyze events such as port visits and encounters (potential transshipment) activities.

APIs Used:

  1. 4Wings API — Retrieve apparent fishing activity grouped by vessel ID in Ghana's EEZ, using spatial-aggregation=true.
  2. Vessels API — Get vessel identity, ownership, and compliance details.
  3. Events API — Identify port visits and potential transshipment activities for vessels in the fleet.

Step 0: Identify the Region of Interest (ROI) — Ghana EEZ

Before making API requests, Kwame must specify the geographic area for analysis using a Region ID:

Options to define the region:

  • Using Region ID — Each EEZ has a unique ID in the public-eez-areas dataset.
  • Custom Geometries — Users can define a custom area using GeoJSON.
  • Find EEZ Region IDs using the Regions dataset — see the Datasets documentation.
  • For the Ghanaian EEZ, the region ID is 8400 (public-eez-areas dataset).

The 4Wings Report API provides flexible output formats, including TIFF (GeoTIFF) for geospatial mapping, JSON for raw data analysis, and CSV.

Important Caveats

  • 🚨 The 4Wings API only supports one active report per user at a time.
  • 🔴 Sending multiple requests simultaneously results in a 429 Too Many Requests error.
  • Report Generation Time & Timeout Risks:
    • If a report takes over 100 seconds to generate, it may return a 524 Gateway Timeout error.
    • To retrieve a previously requested report, use the last-report endpoint instead. For details, see the 4Wings API documentation.

Step 1: Retrieve Fishing Activity in Ghana's EEZ

Kwame first queries the 4Wings API to get fishing activity for all vessels, grouping them by gear type.

Endpoint: /v3/4wings/report

Filters used:

  • Region ID = 8400 (Ghana EEZ)
  • Date Range = Last 12 Months
  • Grouped by Gear Type

API Request: POST

# Make sure to replace [TOKEN] with your API Access Token.
curl --location --globoff 'https://gateway.api.globalfishingwatch.org/v3/4wings/report?format=JSON&datasets[0]=public-global-fishing-effort%3Alatest&temporal-resolution=ENTIRE&spatial-resolution=LOW&spatial-aggregation=true&group-by=GEARTYPE&date-range=2024-01-01%2C2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer [TOKEN]' \
  --data '{
    "region": {
      "dataset": "public-eez-areas",
      "id": 8400
    }
  }'

Example API Response:

{
  "entries": [
    {
      "public-global-fishing-effort:v5.0": [
        {
          "date": "2024-01-01,2025-01-01",
          "geartype": "fishing",
          "hours": 2517.5647222222215,
          "vesselIDs": 9
        },
        {
          "date": "2024-01-01,2025-01-01",
          "geartype": "tuna_purse_seines",
          "hours": 3422.9147222222214,
          "vesselIDs": 20
        },
        {
          "date": "2024-01-01,2025-01-01",
          "geartype": "trawlers",
          "hours": 63320.47722222223,
          "vesselIDs": 56
        }
      ]
    }
  ]
}

What we've learned from Step 1: Kwame now has apparent fishing activity data for Ghana's EEZ in 2024. Tuna purse seiners show apparent fishing activity from 20 vessels, so he continues with this part of the fleet.

You can filter fishing activity or other data by gear type. For more details, check our data caveats and the 4Wings API documentation for the supported gear types.

Step 2: Retrieve Vessel IDs for Tuna Purse Seiners

Kwame refines his 4Wings API request to group by vessel ID, filtering only for tuna purse seiners.

Endpoint: /v3/4wings/report

Filters used:

  • Region ID = Ghana EEZ
  • Gear Type = Tuna Purse Seiners
  • Group by = Vessel ID
  • Spatial aggregation = true
  • Date Range = Last 12 Months

Why use group-by=VESSEL_ID?

Grouping by VESSEL_ID allows getting the vessel ID in the response, which is crucial for connecting with the Vessels API in the next step. By structuring the query this way, we can fetch vessel details such as flag, name, and ownership records in Step 3 below.

Why use spatial-aggregation=true?

For the AIS apparent fishing activity (public-global-fishing-effort) and AIS vessel presence (public-global-presence) datasets, group-by=VESSEL_ID is only available when spatial-aggregation=true. The report is then aggregated over the whole region, so it returns the vessel ID and hours but no latitude or longitude. spatial-aggregation=false is the default, so it has to be sent explicitly.

API Parameters:

  • spatial-aggregation (true, required with group-by=VESSEL_ID)
  • spatial-resolution (e.g., HIGH, LOW)
  • temporal-resolution (e.g., ENTIRE, MONTHLY, YEARLY)
  • For additional parameters, please refer to the 4Wings API documentation.

API Request: POST

# Make sure to replace [TOKEN] with your API Access Token.
curl --location --globoff 'https://gateway.api.globalfishingwatch.org/v3/4wings/report?format=JSON&datasets[0]=public-global-fishing-effort%3Alatest&temporal-resolution=ENTIRE&spatial-resolution=LOW&spatial-aggregation=true&group-by=VESSEL_ID&date-range=2024-01-01%2C2025-01-01&filters[0]=geartype%20in%20(%27tuna_purse_seines%27)' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer [TOKEN]' \
  --data '{
    "region": {
      "dataset": "public-eez-areas",
      "id": 8400
    }
  }'

Note: The R package gfwr does not support spatial-aggregation, so this vessel-level request is not available in R.

Example API Response (abridged to the three vessels with the most apparent fishing hours; the full response lists 20 vessels):

{
  "entries": [
    {
      "public-global-fishing-effort:v5.0": [
        {
          "callsign": "9GEW",
          "dataset": "public-global-vessel-identity:v5.0",
          "date": "2024-01-01,2025-01-01",
          "entryTimestamp": "2024-03-14T11:00:00Z",
          "exitTimestamp": "2024-12-31T13:00:00Z",
          "firstTransmissionDate": "2018-05-02T06:35:05Z",
          "flag": "GHA",
          "geartype": "TUNA_PURSE_SEINES",
          "hours": 1246.0636111111114,
          "imo": "7437202",
          "lastTransmissionDate": "2026-11-01T23:59:50Z",
          "mmsi": "627887000",
          "shipName": "AGNES1",
          "vesselId": "e0de330e1-17d1-a6f5-01f1-3b2dad5226de",
          "vesselType": "FISHING"
        },
        {
          "callsign": "9GJD",
          "dataset": "public-global-vessel-identity:v5.0",
          "date": "2024-01-01,2025-01-01",
          "entryTimestamp": "2024-03-14T22:00:00Z",
          "exitTimestamp": "2024-12-18T07:00:00Z",
          "firstTransmissionDate": "2015-07-19T09:02:07Z",
          "flag": "GHA",
          "geartype": "TUNA_PURSE_SEINES",
          "hours": 890.632222222222,
          "imo": "8214310",
          "lastTransmissionDate": "2026-11-01T23:58:47Z",
          "mmsi": "627066000",
          "shipName": "IRIS-J",
          "vesselId": "64254bdf9-92ff-30aa-3186-169ca16bc136",
          "vesselType": "FISHING"
        },
        {
          "callsign": "9GBU2",
          "dataset": "public-global-vessel-identity:v5.0",
          "date": "2024-01-01,2025-01-01",
          "entryTimestamp": "2024-03-15T11:00:00Z",
          "exitTimestamp": "2024-12-27T09:00:00Z",
          "firstTransmissionDate": "2019-07-08T16:48:04Z",
          "flag": "GHA",
          "geartype": "TUNA_PURSE_SEINES",
          "hours": 454.53305555555545,
          "imo": "8210493",
          "lastTransmissionDate": "2026-11-01T23:58:47Z",
          "mmsi": "627250000",
          "shipName": "IRIS-QUEEN",
          "vesselId": "9eab37595-5bf1-471e-2e38-c070ebb00a7a",
          "vesselType": "FISHING"
        }
      ]
    }
  ]
}

What we've learned from Step 2

  • Kwame identifies 20 vessels operating as tuna purse seiners within Ghana's EEZ in 2024.
  • AGNES1 shows the most apparent fishing activity, with about 1,246 hours.
  • IRIS-J and IRIS-QUEEN follow, with about 891 and 455 hours.
  • This response is based on AIS self-reported data and should be further validated.

Step 3: Retrieve Vessel Details

Kwame queries the Vessels API to get detailed vessel identity and ownership records.

Endpoint: /v3/vessels/{vessel_id}

Filters used:

  • vessel id from 4Wings API
  • dataset = public-global-vessel-identity:latest
  • includes = POTENTIAL_RELATED_SELF_REPORTED_INFO — Vessels may change identifiers over time, such as their MMSI, IMO number, call sign, or even their name. This parameter helps users group all vessel ids that are potentially related as part of the same physical vessel based on publicly available registry information.

IMPORTANT: To avoid any misinterpretation of Global Fishing Watch data, please refer to our data caveats for Apparent Fishing Activity, Region source, Vessel ID, and Vessel identity data.

API Request: GET

# Make sure to replace [TOKEN] with your API Access Token.
curl --location --globoff 'https://gateway.api.globalfishingwatch.org/v3/vessels?datasets[0]=public-global-vessel-identity%3Alatest&ids[0]=e0de330e1-17d1-a6f5-01f1-3b2dad5226de&includes[0]=POTENTIAL_RELATED_SELF_REPORTED_INFO' \
  --header 'Authorization: Bearer [TOKEN]'

Example API Response (abridged to the first record of each list):

{
  "entries": [
    {
      "registryInfoTotalRecords": 2,
      "registryInfo": [
        {
          "id": "c2896e579dbb59f85f253382aa28f528",
          "sourceCode": [
            "ICCAT",
            "IMO",
            "ISSF",
            "KOR",
            "SNP"
          ],
          "ssvid": "627887000",
          "flag": "GHA",
          "shipname": "AGNES1",
          "nShipname": "AGNES1",
          "callsign": "9GEW",
          "imo": "7437202",
          "latestVesselInfo": true,
          "transmissionDateFrom": "2013-12-18T00:23:19Z",
          "transmissionDateTo": "2026-09-30T22:44:50Z",
          "geartypes": [
            "TUNA_PURSE_SEINES"
          ],
          "lengthM": 63.3,
          "tonnageGt": 1217,
          "vesselInfoReference": "018f07547375efe0fd7d1622fb4a5b3e",
          "extraFields": []
        }
      ],
      "registryOwners": [
        {
          "name": "AGNES PARK FISHERIES",
          "flag": "GHA",
          "ssvid": "627887000",
          "sourceCode": [
            "IMO",
            "SNP",
            "ICCAT"
          ],
          "dateFrom": "2013-12-18T00:23:19Z",
          "dateTo": "2026-09-30T22:44:50Z"
        }
      ],
      "registryPublicAuthorizations": [
        {
          "dateFrom": "2015-01-01T00:00:00Z",
          "dateTo": "2019-09-01T00:00:00Z",
          "ssvid": "627887000",
          "sourceCode": [
            "ICCAT"
          ]
        }
      ],
      "combinedSourcesInfo": [
        {
          "vesselId": "1a1519b8f-f857-b0fa-9807-14b323073d89",
          "geartypes": [
            {
              "name": "TUNA_PURSE_SEINES",
              "source": "SECONDARY_CLASSIFIER_MODEL",
              "yearFrom": 2014,
              "yearTo": 2016
            }
          ],
          "shiptypes": [
            {
              "name": "FISHING",
              "source": "SECONDARY_CLASSIFIER_MODEL",
              "yearFrom": 2014,
              "yearTo": 2016
            }
          ],
          "bestLengthM": [
            {
              "value": 64.2,
              "source": "SECONDARY_CLASSIFIER_MODEL",
              "yearFrom": 2014,
              "yearTo": 2016
            }
          ],
          "bestTonnageGt": [
            {
              "value": 1328,
              "source": "SECONDARY_CLASSIFIER_MODEL",
              "yearFrom": 2014,
              "yearTo": 2016
            }
          ]
        }
      ],
      "selfReportedInfo": [
        {
          "id": "e0de330e1-17d1-a6f5-01f1-3b2dad5226de",
          "ssvid": "627887000",
          "shipname": "AGNES1",
          "nShipname": "AGNES1",
          "flag": "GHA",
          "callsign": "9GEW",
          "imo": "7437202",
          "messagesCounter": 6176987,
          "positionsCounter": 2168200,
          "sourceCode": [
            "AIS"
          ],
          "matchFields": "SEVERAL_FIELDS",
          "transmissionDateFrom": "2018-05-02T06:35:05Z",
          "transmissionDateTo": "2026-11-01T23:59:50Z"
        }
      ],
      "dataset": "public-global-vessel-identity:v5.0"
    }
  ]
}

What we've learned from Step 3

  • The vessel AGNES1 (MMSI 627887000, IMO 7437202) is a tuna purse seiner flagged to Ghana, about 63 m long.
  • Public registries in the GFW database list AGNES PARK FISHERIES as the owner.
  • ICCAT authorization periods are listed for this vessel.
  • The self-reported AIS identity has been active since 2018.
  • Registry and AIS information can differ, so the data should be further validated against official public sources.

Understanding the response objects

  • registryInfoTotalRecords — Number of public registry records found in the GFW database for this vessel. If 0, no public official registry records were found in the GFW database for this vessel.
  • registryInfo — Vessel records from public registries in the GFW database. Empty if none were found.
  • registryOwners — Known ownership records from public registries in the GFW database. Empty if none were found.
  • registryPublicAuthorizations — Known public authorizations in the GFW database. Empty if no public known authorizations were found in the GFW database.
  • combinedSourcesInfo — Provides inferred data based on AIS and other data sources.
  • selfReportedInfo — The vessel's self-reported flag, identity, and activity timestamps.

Note: A public registry or authorization can be missing from the GFW database even if it is publicly available elsewhere, for example because of issues collecting the source.

Step 4: Detect Fleet Activity (Port Visits)

Now that Kwame has identified vessels in the fleet, he examines their activity further by querying the Events API. This allows him to detect port visits, encounters (potential transshipment) and apparent fishing activity based on vessel movement patterns.

Endpoint: /v3/events

Filters used:

  • Vessel ID from 4Wings API (multiple vessels in the fleet)
  • Event Types = PORT_VISIT, ENCOUNTER, FISHING. To obtain other event types, please visit the Events API documentation.
  • Time Range = Last 6 months.
  • encounter-types = FISHING-FISHING.
  • Datasets:
    • public-global-port-visits-events:latest (Port Visits)
    • public-global-encounters-events:latest (Encounters between vessels)
    • public-global-fishing-events:latest (Fishing activity)

API Request: GET

# Make sure to replace [TOKEN] with your API Access Token.
curl --location --globoff 'https://gateway.api.globalfishingwatch.org/v3/events?vessels[0]=e0de330e1-17d1-a6f5-01f1-3b2dad5226de&vessels[1]=64254bdf9-92ff-30aa-3186-169ca16bc136&vessels[2]=9eab37595-5bf1-471e-2e38-c070ebb00a7a&encounter-types[0]=FISHING-FISHING&sort=-start&start-date=2024-08-01&end-date=2025-01-31&limit=200&offset=0&datasets[0]=public-global-encounters-events%3Alatest&datasets[1]=public-global-fishing-events%3Alatest&datasets[2]=public-global-port-visits-events%3Alatest&include-regions=false&types[0]=ENCOUNTER&types[1]=FISHING&types[2]=PORT_VISIT' \
  --header 'Authorization: Bearer [TOKEN]'

Example API Response (abridged to one fishing event and one port visit; the full response has 174 events):

{
  "metadata": {
    "datasets": [
      "public-global-port-visits-events:v5.0",
      "public-global-encounters-events:v5.0",
      "public-global-fishing-events:v5.0"
    ],
    "vessels": [
      "e0de330e1-17d1-a6f5-01f1-3b2dad5226de",
      "64254bdf9-92ff-30aa-3186-169ca16bc136",
      "9eab37595-5bf1-471e-2e38-c070ebb00a7a"
    ],
    "dateRange": {
      "from": "2024-08-01",
      "to": "2025-01-31"
    },
    "encounterTypes": [
      "FISHING-FISHING"
    ]
  },
  "limit": 200,
  "offset": 0,
  "nextOffset": null,
  "total": 174,
  "entries": [
    {
      "start": "2025-01-23T20:34:45.000Z",
      "end": "2025-01-24T05:54:44.000Z",
      "id": "e9a8d06ea24b26c27f0d5f14dc9a39a6",
      "type": "fishing",
      "position": {
        "lat": 5.3867,
        "lon": 0.1106
      },
      "regions": {
        "eez": [
          "8400"
        ],
        "majorFao": [
          "34"
        ]
      },
      "distances": {
        "startDistanceFromShoreKm": 65,
        "endDistanceFromShoreKm": 11,
        "startDistanceFromPortKm": 55.3892578125,
        "endDistanceFromPortKm": 1.106727294921875
      },
      "vessel": {
        "id": "64254bdf9-92ff-30aa-3186-169ca16bc136",
        "name": "IRIS-J",
        "ssvid": "627066000",
        "flag": "GHA",
        "type": "fishing",
        "publicAuthorizations": [
          {
            "hasPubliclyListedAuthorization": "true",
            "rfmo": "ICCAT"
          }
        ],
        "nextPort": null
      },
      "fishing": {
        "totalDistanceKm": 60.655277834745064,
        "averageSpeedKnots": 3.076470592497466,
        "averageDurationHours": null,
        "potentialRisk": false,
        "vesselPublicAuthorizationStatus": "publicly_authorized"
      }
    },
    {
      "start": "2025-01-29T08:42:39.000Z",
      "end": "2025-02-03T10:04:58.000Z",
      "id": "fec38f59d9675b9f9fd6d6e439e44b3e",
      "type": "port_visit",
      "position": {
        "lat": 5.559,
        "lon": 0.0763
      },
      "regions": {
        "eez": [
          "8400"
        ],
        "majorFao": [
          "34"
        ]
      },
      "distances": {
        "startDistanceFromShoreKm": 11,
        "endDistanceFromShoreKm": 11,
        "startDistanceFromPortKm": 0,
        "endDistanceFromPortKm": 0
      },
      "vessel": {
        "id": "64254bdf9-92ff-30aa-3186-169ca16bc136",
        "name": "IRIS-J",
        "ssvid": "627066000",
        "flag": "GHA",
        "type": "fishing",
        "nextPort": null
      },
      "port_visit": {
        "visitId": "37c8959fc871cf123a4f9f6a54be6692",
        "confidence": "4",
        "durationHrs": 121.37194444444444,
        "startAnchorage": {
          "anchorageId": "102070ab",
          "atDock": false,
          "distanceFromShoreKm": "11",
          "flag": "GHA",
          "id": "gha-tema",
          "lat": 5.559031995449072,
          "lon": 0.07633715751117509,
          "name": "TEMA",
          "topDestination": "TEMA"
        },
        "endAnchorage": {
          "anchorageId": "10207715",
          "atDock": false,
          "distanceFromShoreKm": "11",
          "flag": "GHA",
          "id": "gha-tema",
          "lat": 5.5380165225309685,
          "lon": 0.05339939659964179,
          "name": "TEMA",
          "topDestination": "TEMA"
        }
      }
    }
  ]
}

Response objects

  • metadata — Specifies the datasets queried, vessel IDs, date range, and event types.
  • limit — Maximum number of results returned per request.
  • total — Number of events found matching the criteria.
  • entries — List of detected events, each with its type, start and end time, position, regions, and the vessel involved.

What we've learned from Step 4

  • Kwame finds 174 events for the three vessels between August 2024 and January 2025: 152 fishing events and 22 port visits, with no encounters.
  • The port visits in the sample are at Tema, Ghana.
  • Events can be used to follow where and when each vessel of the fleet fished and which ports it used.

Caveats & Considerations

  • 🚨 A lack of recorded encounters or port visits does not confirm the absence of such activities — AIS coverage, reporting behavior, and dataset updates can impact results.
  • 🚨 Further investigation may be required, including manual validation using historical data or consulting additional sources.

Summary of the API Flow

  1. 4Wings API — Identify fishing activity by gear type in Ghana's EEZ.
  2. 4Wings API — Retrieve vessel IDs for tuna purse seiners, with spatial-aggregation=true.
  3. Vessels API — Fetch detailed vessel identity & ownership.
  4. Events API — Detect fleet activity (port visits, encounters, and apparent fishing events).

Analyzing Apparent Fishing Activity for Trawlers in an EEZ

Identify trawlers fishing in an EEZ, retrieve their identity, then check their port visits and encounters.

SDKs

Official Global Fishing Watch API v3 client libraries for Python and R, and guidance on which one to use.

On this page

Use Case: Monitoring a Fleet of Tuna Purse Seiners for ComplianceStep 0: Identify the Region of Interest (ROI) — Ghana EEZStep 1: Retrieve Fishing Activity in Ghana's EEZStep 2: Retrieve Vessel IDs for Tuna Purse SeinersStep 3: Retrieve Vessel DetailsUnderstanding the response objectsStep 4: Detect Fleet Activity (Port Visits)Response objectsSummary of the API Flow