# Analyzing Apparent Fishing Effort in a Region and Retrieving Vessel Details (/docs/api-workflows/analyzing-fishing-effort-in-a-region)
This workflow guides you through querying fishing effort data using the [4Wings Report API](/docs/v3/4wings) and retrieving vessel information using the [Vessels API](/docs/v3/vessels).
## Use Case: A Port Inspector Monitoring Vessel Activity [#use-case-a-port-inspector-monitoring-vessel-activity]
Mamadou, a port inspector in **Dakar, Senegal**, monitors vessel activity within Senegal's **Exclusive Economic Zone (EEZ)**. His role includes:
* ✅ Analyzing apparent fishing effort, specifically for trawlers in Senegal's EEZ.
* ✅ Identifying vessels involved in apparent trawling activity and determining their reported flag states.
* ✅ Checking vessel history, including prior encounters (or potential transshipment) or port visits.
* ✅ Generating reports for enforcement authorities to assess risks.
To do this, Mamadou will use **two Global Fishing Watch APIs**:
* **[4Wings API](/docs/v3/4wings)** — To retrieve **apparent** fishing effort data for trawlers operating in Senegal's EEZ over the past 3 months.
* **[Vessels API](/docs/v3/vessels)** — To retrieve **detailed vessel information**, including flag, ownership history, and authorizations.
## Step 0: Identify the Region of Interest (ROI) — Senegal EEZ [#step-0-identify-the-region-of-interest-roi--senegal-eez]
Before making API requests, Mamadou 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](/docs/v3/datasets).
* For Senegal's EEZ, the region ID is **8371** (`public-eez-areas` dataset).
## Step 1: Retrieve Apparent Fishing Effort in Senegal's EEZ [#step-1-retrieve-apparent-fishing-effort-in-senegals-eez]
**API Used:** 4Wings API — `/v3/4wings/report`
**Filters applied:**
* Region ID = Senegal EEZ (8371)
* Gear Type = Trawlers
* Date Range = Last 3 months
### Explanation of parameters & considerations [#explanation-of-parameters--considerations]
**How is the gear type retrieved?**
* Gear types, such as **trawlers**, are inferred based on Global Fishing Watch's vessel classification system, which relies on AIS data and vessel public registries. The gear type associated with each vessel is not always 100% accurate, as it may be derived from historical sources or inferred from movement patterns.
* Please also review the caveats regarding **vessel types** and their classification.
**How is the Region ID retrieved?**
* The Region ID corresponds to Senegal's **Exclusive Economic Zone (EEZ)**. Each region has a unique identifier within the `public-eez-areas` dataset. Users can retrieve Region IDs from GFW's API by querying the Regions dataset to find the corresponding ID for a given EEZ, RFMO, or other geographic area.
> **IMPORTANT:** To avoid any misinterpretation of Global Fishing Watch data, please refer to our data caveats for Apparent Fishing Effort, Region source, Vessel ID, and Vessel identity data.
**API Request:** POST
```shell
# Make sure to replace [TOKEN] with your API Access Token.
curl --location --globoff 'https://gateway.api.globalfishingwatch.org/v3/4wings/report?spatial-resolution=HIGH&temporal-resolution=MONTHLY&group-by=VESSEL_ID&datasets[0]=public-global-fishing-effort%3Alatest&date-range=2024-11-01%2C2025-01-31&format=JSON&filters[0]=geartype%20in%20(%27trawlers%27)' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [TOKEN]' \
--data '{
"region": {
"dataset": "public-eez-areas",
"id": 8371
}
}'
```
```python
result = await gfw_client.fourwings.create_report(
datasets=["public-global-fishing-effort:latest"],
spatial_resolution="HIGH",
temporal_resolution="MONTHLY",
group_by="VESSEL_ID",
start_date="2024-11-01",
end_date="2025-01-31",
filters=["geartype in ('trawlers')"],
region={"dataset": "public-eez-areas", "id": 8371},
)
```
```r
gfw_ais_fishing_hours(
spatial_resolution = "HIGH",
temporal_resolution = "MONTHLY",
start_date = "2024-11-01",
end_date = "2025-01-31",
region_source = "EEZ",
region = 8371,
group_by = "VESSEL_ID",
filter_by = "geartype in ('trawlers')"
)
```
```js
// Make sure to replace [TOKEN] with your API Access Token.
const res = await fetch(
'https://gateway.api.globalfishingwatch.org/v3/4wings/report?spatial-resolution=HIGH&temporal-resolution=MONTHLY&group-by=VESSEL_ID&datasets[0]=public-global-fishing-effort%3Alatest&date-range=2024-11-01%2C2025-01-31&format=JSON&filters[0]=geartype%20in%20(%27trawlers%27)',
{
method: 'POST',
headers: {
Authorization: 'Bearer [TOKEN]',
'Content-Type': 'application/json',
},
body: JSON.stringify({
region: {
dataset: 'public-eez-areas',
id: 8371,
},
}),
}
)
const data = await res.json()
```
**Why use `group-by=VESSEL_ID`?**
Grouping by VESSEL\_ID allows **individual vessel identification** in the response. This is crucial for **tracking vessel activity** and, more importantly, linking each detected vessel to 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 2 below.
**API Parameters:**
* `spatial-resolution` (e.g., `HIGH`, `LOW`)
* `temporal-resolution` (e.g., `DAILY`, `MONTHLY`, `YEARLY`)
* For additional parameters, please refer to the [4Wings API documentation](/docs/v3/4wings).
**4Wings API Response:**
```json
{
"total": 2,
"entries": [
{
"public-global-fishing-effort:v3.0": [
{
"callsign": "DAK1142",
"dataset": "public-global-vessel-identity:v3.0",
"date": "2025-01",
"entryTimestamp": "2024-11-01T11:00:00Z",
"exitTimestamp": "2025-01-30T23:00:00Z",
"firstTransmissionDate": "2022-08-19T15:17:37Z",
"flag": "SEN",
"geartype": "TRAWLERS",
"hours": 1.8858333333333333,
"imo": "",
"lastTransmissionDate": "2025-02-17T23:59:25Z",
"lat": 15.68,
"lon": -17.059999465942383,
"mmsi": "663103000",
"shipName": "RIA DE DAKAR",
"vesselId": "90ab31dfb-bcab-a05f-d12f-2544e1869205",
"vesselType": "FISHING"
},
{
"callsign": "6WFI",
"dataset": "public-global-vessel-identity:v3.0",
"date": "2025-01",
"entryTimestamp": "2024-11-12T03:00:00Z",
"exitTimestamp": "2025-01-30T23:00:00Z",
"firstTransmissionDate": "2021-05-01T11:49:43Z",
"flag": "SEN",
"geartype": "TRAWLERS",
"hours": 1.0191666666666663,
"imo": "",
"lastTransmissionDate": "2025-02-17T23:59:49Z",
"lat": 14.19,
"lon": -17.559999465942383,
"mmsi": "663131000",
"shipName": "KANBAL II",
"vesselId": "6eb0b555f-fa62-7cb1-4135-2d0eeb6b4baa",
"vesselType": "FISHING"
}
]
}
]
}
```
> **What we've learned from Step 1**
>
> Two vessels appear to have been engaged in potential trawling activity in Senegal's EEZ over the past 3 months:
>
> * KANBAL II (MMSI: 663131000, Flag: Senegal)
> * RIA DE DAKAR (MMSI: 663103000, Flag: Senegal)
>
> We will retrieve these vessels' ownership, flag history, and authorizations in **Step 2 to validate them**.
**Data source & considerations**
The values returned in this response are primarily derived from **Automatic Identification System (AIS) self-reported data**.
* **Self-Reported Information:** The vessel name, MMSI, and flag are broadcast by the vessel's AIS transponder and may not always reflect official registry data. Some vessels may report incorrect or outdated information, either mistakenly or deliberately.
* **Gear Type Classification Caveats:** Gear type (e.g., Trawlers) is often inferred based on vessel behavior, registries, and historical data rather than explicitly transmitted via AIS. Some vessels may switch gear types or misreport their actual fishing methods.
## Step 2: Retrieve Vessel Details Using the Vessels API [#step-2-retrieve-vessel-details-using-the-vessels-api]
**API Used:** Vessels API — `/v3/vessels/{vessel_id}`
**Filters applied:**
* **vessel id** = Retrieved from Step 1
* **includes:** `POTENTIAL_RELATED_SELF_REPORTED_INFO` — Vessels may change identifiers over time, such as their MMSI, IMO number, call sign, or even their name. These changes can occur due to re-registration, changes in ownership, or other operational reasons. 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. Global Fishing Watch's authorization data relies on publicly available information. The absence of an authorization record in our data does not necessarily indicate a vessel is operating without authorization. We recommend consulting additional sources, such as national registries, to verify authorization status.
**API Request:** GET
```shell
# 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]=90ab31dfb-bcab-a05f-d12f-2544e1869205&ids[1]=6eb0b555f-fa62-7cb1-4135-2d0eeb6b4baa&includes[0]=POTENTIAL_RELATED_SELF_REPORTED_INFO' \
--header 'Authorization: Bearer [TOKEN]'
```
```python
result = await gfw_client.vessels.get_vessels_by_ids(
ids=[
"90ab31dfb-bcab-a05f-d12f-2544e1869205",
"6eb0b555f-fa62-7cb1-4135-2d0eeb6b4baa",
],
datasets=["public-global-vessel-identity:latest"],
includes=["POTENTIAL_RELATED_SELF_REPORTED_INFO"],
)
```
```r
gfw_vessel_info(
search_type = "id",
ids = c(
"90ab31dfb-bcab-a05f-d12f-2544e1869205",
"6eb0b555f-fa62-7cb1-4135-2d0eeb6b4baa"
),
includes = "POTENTIAL_RELATED_SELF_REPORTED_INFO"
)
```
```js
// Make sure to replace [TOKEN] with your API Access Token.
const res = await fetch(
'https://gateway.api.globalfishingwatch.org/v3/vessels?datasets[0]=public-global-vessel-identity%3Alatest&ids[0]=90ab31dfb-bcab-a05f-d12f-2544e1869205&ids[1]=6eb0b555f-fa62-7cb1-4135-2d0eeb6b4baa&includes[0]=POTENTIAL_RELATED_SELF_REPORTED_INFO',
{ headers: { Authorization: 'Bearer [TOKEN]' } }
)
const data = await res.json()
```
**Example API Response:**
```json
{
"entries": [
{
"registryInfoTotalRecords": 1,
"registryInfo": [
{
"id": "a07fa455e1d1d5c2da2a09320ef17f3f",
"sourceCode": ["IMO"],
"ssvid": "663103000",
"flag": "SEN",
"shipname": "RIA DE DAKAR",
"nShipname": "RIADEDAKAR",
"callsign": "DAK1142",
"imo": "9003342",
"latestVesselInfo": true,
"transmissionDateFrom": "2020-03-16T18:40:10Z",
"transmissionDateTo": "2022-08-20T11:00:16Z",
"geartypes": ["FISHING"],
"lengthM": null,
"tonnageGt": 173,
"vesselInfoReference": "1e76d3c121ec222a32aed42622129adc",
"extraFields": []
}
]
// ... additional entries (e.g. KANBAL II) follow the same structure
}
]
}
```
> **What we've learned from Step 2**
>
> * **Vessel Identity:** KANBAL II (MMSI: 663131000, IMO: 8708464) appears to be registered under Senegal (SEN).
> * **Ownership & Historical Changes:** "SOPERKA" appears to be listed as the registered owner.
>
> **Next steps:**
>
> * Further, **validate ownership history** using official registry sources.
> * Assess whether any historical changes in flag, name, or ownership are relevant for enforcement.
> * Generate an apparent activity report with all available details.
### Understanding the response objects [#understanding-the-response-objects]
* **registryInfoTotalRecords** — The number of registry records found for the vessels.
* **registryInfo** — Contains public registry data, sourced from official vessel registries.
* **registryOwners** — Lists the registered owners of the vessel based on public sources.
* **registryPublicAuthorizations** — Represents known fishing authorizations from public sources. Users should verify against national registries and RFMO records for additional context.
* **combinedSourcesInfo** — Provides Vessel Type and Gear Type inferred from multiple sources. It is calculated from our neural network model, which uses registry, AIS information, and track behavior to estimate these identity values.
* **selfReportedInfo** — Contains AIS self-reported data, including MMSI, ship name, and flag as broadcast by the vessel itself. Self-reported data may not always align with registry data and should be cross-checked.
## Summary of the API Flow [#summary-of-the-api-flow]
* **4Wings API** — Retrieve apparent fishing effort for trawlers within Senegal's EEZ.
* **Vessels API** — Fetch detailed vessel identity, ownership history, and public authorizations for vessels detected in Step 1.
* **Analyze vessel history** — Compare registry records, AIS self-reported data, and inferred information to identify potential flag-hopping or historical changes in vessel identity.
* **Assess authorizations** — Cross-check whether vessels have publicly available fishing authorizations and consider external official sources for further verification.
* **Generate an analysis report** — Provide enforcement authorities with a structured report highlighting vessel activity, identity records, and any notable discrepancies for further investigation.