Create a Report

Create a report aggregating activity over a region, given either an existing region id or a custom GeoJSON polygon, as JSON or CSV.

Create a report of a specified region

Report - HTTP Request

It is possible to call this endpoint using one of these two verbs:

POST https://gateway.api.globalfishingwatch.org/v3/4wings/report
GET https://gateway.api.globalfishingwatch.org/v3/4wings/report

Verb Usage Notes:

POST: Use this method to send a custom polygon. This functionality is not available with the GET method.
GET: This method supports caching, which is highly beneficial for frontend/UI applications to prevent redundant requests. Cached requests can be stored and reused, significantly improving response times. Additionally, Global Fishing Watch caches GET requests at the gateway level. If a user is expected to call the same URL multiple times, this can result in a substantial performance improvement.

This endpoint only supports geojson or region object in the same request.

The value of the data of the report is aggregated using the sum function.

Example 429 Error Response

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "messages": [
    {
      "title": "Too Many Requests",
      "detail": "Your application token is not currently enabled to perform more than one concurrent report. If you need to generate more than one report concurrently, contact us at apis@globalfishingwatch.org",
      "metadata": {
        "currentReportBody": {
          "geojson": null,
          "region": {
            "dataset": "public-mpa-all",
            "id": "555635930"
          }
        },
        "currentReportUrl": "/v3/4wings/report?format=csv&datasets%5B0%5D=public-global-fishing-effort%3Av20201001&date-range=2023-05-01T00%3A00%3A00.000Z%2C2023-06-01T00%3A00%3A00.000Z&spatial-aggregation=true&temporal-resolution=entire&group-by=vessel_id"
      }
    }
  ]
}

This endpoint only support one report by user at the same time. If you send more than 1 request at the same time, you will receive a 429 error. The error contains the information of the current executing report for the user.

This endpoint could throw a 524 error (Gateway timeout) if the report takes more than 100s in obtain the data. In that case, you can recover the report using the endpoint last-report.

Report - AIS Apparent Fishing Effort examples

These examples are available:

Example 1 (POST) - Generate fishing effort report grouped By Year and by Custom Polygon In JSON Format
Example 2 (POST) - Generate fishing effort report grouped By Gear Type, Using existing Regions (Russian Eez) In CSV Format.
Example 3 (GET) - same as Example 2 but using GET.
Example 4 (POST) - Generate report with total fishing hours per Lat/Lon grid cell (no grouping) using existing Regions (MPA Dorsal De Nasca) In JSON Format
Example 5 (GET) - same as Example 4 but using GET.
Example 6 (POST) - Generate report with total fishing hours per Lat/Lon grid cell (no grouping) using existing Regions (MPA Dorsal De Nasca) In JSON Format and buffer of 4 NAUTICAL MILES
Example 7 (GET) - same as Example 6 but using GET.

Report - SAR vessel detection examples

These examples are available:

Example 8 (POST) - Report REGION ID (Chile) DAILY grided data and filter by unmatched detections (JSON)
Example 9 (POST) - Report Indonesia Filter by matched detections - Example of Noisy Vessel

Report - AIS Vessel Presence examples

These examples are available:

Example 10 (POST) - Report vessel presence by region - grouped by vessel type (JSON)
Example 11 (GET) - Report vessel presence - cargo and carrier vessels only (JSON)

Report - POST

Authorization

ApiKeyAuth

AuthorizationBearer <token>

In: header

Query Parameters

spatial-resolution?string

Low means at 10th degree resolution and High means at 100th degree resolution. Only required if spatial-aggregation is false or it's not sent

Value in

"LOW"
"high"

vessel-groups[0]?string

Vessel group ids to filter (separated by comma). Vessel groups applied at dataset with index 0. At the same as datasets, this query param could be send with different index to apply filters to other datasets.

format*string

As result you get a zip file that contains caveat information and also the actual file including the results that could be in different results

Value in

"CSV"
"TIF"
"JSON"

group-by*string

The report data can be grouped by different criteria, for example a CSV by vessel_id means that you get on row for each vessel id

Value in

"VESSEL_ID"
"FLAG"
"GEARTYPE"
"FLAGANDGEARTYPE"
"MMSI"

temporal-resolution*string

You can decide the level of detail regarding time. For example if you request CSV, group by VESSEL_ID and DAILY, you get one row per vessel id per day

Value in

"HOURLY"
"DAILY"
"MONTHLY"
"YEARLY"
"ENTIRE"

datasets[0]*string

Specify the datasets that will be used to create the style. You can learn more about which are the possible datasets here. The parameters should be defined using an index, in case only one dataset is going to be sent: ?dataset[0]=xxxxx, in case of multiple datasets: ?dataset[0]=xxxxx&dataset[1]=yyyyy

filters[0]?string

Filters are applied to the dataset parameter with the corresponding index. For example if we want to apply a filter to dataset[0], we should apply the filter attributes to filter[0].For AIS fishing effort, the possible filters are: flag, geartype

date-range?string

Start date and end date to filter the data

spatial-aggregation?string

Aggregates spatially the data in the report. With value true, the formats supported are only csv and json. Default value: false

Header Parameters

Content-Language?string

The content returned is available is this language, the API will returned it. If the request does not contain the header, the default value is en-EN. In case that the request has an invalid value, the default value is en-EN as well.

Value in

"es-ES"
"en-EN"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

geojson*

curl -X POST "https://example.com/v3/4wings/report?spatial-resolution=LOW&vessel-groups%5B0%5D=1%2C2&format=CSV&group-by=VESSEL_ID&temporal-resolution=YEARLY&datasets%5B0%5D=public-global-fishing-effort%3Alatest&filters%5B0%5D=flag+in+%28%27ESP%27%29&date-range=2021-01-01%2C2021-03-01&spatial-aggregation=false" \  -H "Content-Language: en-EN" \  -H "Content-Type: application/json" \  -d '{    "geojson": "{\\"type\\":\\"FeatureCollection\\",\\"features\\":[{\\"type\\":\\"Feature\\",\\"properties\\":{},\\"geometry\\":{\\"type\\":\\"Polygon\\",\\"coordinates\\":[[[29,43],[32,43],[32,43],[29,43],[29,43]]]}}]}"  }'

{  "entries": [    {      "callsign": "UBSS9",      "dataset": "public-global-vessel-identity:v3.0",      "date": "2022-01-13",      "detections": 12,      "entryTimestamp": "2022-01-14T14:00:00Z",      "exitTimestamp": "2022-01-14T16:00:00Z",      "firstTransmissionDate": "2019-07-12T12:08:27Z",      "flag": "ESP",      "geartype": "FISHING",      "hours": 26.6,      "imo": "8602866",      "lastTransmissionDate": "2025-03-01T23:55:50Z",      "lat": 49.33,      "lon": 141.15,      "mmsi": "273453380",      "shipName": "ALSEY",      "vesselIDs": 3,      "vesselId": "e6154b2e7-7762-4889-fb46-976ec72875e1",      "vesselType": "FISHING"    }  ],  "limit": 0,  "metadata": {},  "nextOffset": 0,  "offset": 0,  "total": 0}

{  "error": "Unauthorized",  "messages": [    {      "detail": "string",      "title": "string"    }  ],  "statusCode": 401}

{  "error": "Forbidden",  "messages": [    {      "detail": "string",      "title": "string"    }  ],  "statusCode": 403}

{  "error": "UnprocessableEntity",  "messages": [    {      "detail": "string",      "title": "string"    }  ],  "statusCode": 422}

{  "error": "Too Many Requests",  "messages": [    {      "detail": "string",      "metadata": {        "currentReportBody": {          "geojson": "string",          "region": {}        },        "currentReportUrl": "string"      },      "title": "string"    }  ],  "statusCode": 429}

{  "error": "Service Unavailable",  "messages": [    {      "detail": "string",      "title": "string"    }  ],  "statusCode": 503}

Report - GET

Authorization

ApiKeyAuth

AuthorizationBearer <token>

In: header

Query Parameters

spatial-resolution?string

Low means at 10th degree resolution and High means at 100th degree resolution. Only required if spatial-aggregation is false or it's not sent

Value in

"LOW"
"HIGHT"

vessel-groups[0]?string

format*string

As result you get a zip file that contains caveat information and also the actual file including the results that could be in different results

Value in

"CSV"
"TIF"
"JSON"

group-by*string

The report data can be grouped by different criteria, for example a csv by vessel_id means that you get on row for each vessel id

Value in

"VESSEL_ID"
"FLAG"
"GEARTYPE"
"FLAGANDGEARTYPE"
"MMSI"

temporal-resolution*string

You can decide the level of detail regarding time. For example if you request csv, group by vessel_id and daily, you get one row per vessel id per day

Value in

"HOURLY"
"DAILY"
"MONTHLY"
"YEARLY"
"ENTIRE"

datasets[0]*string

filters[0]?string

date-range?string

Start date and end date to filter the data

spatial-aggregation?string

Aggregates spatially the data in the report. With value true, the formats supported are only csv and json. Default value: false

buffer-value?number

Distance to draw the buffer (negative values are allowed)

buffer-unit?string

Unit of the buffer value. Possible values (MILES, NAUTICALMILES, KILOMETERS, RADIANS, DEGREES)

Value in

"MILES"
"NAUTICALMILES"
"KILOMETERS"
"RADIANS"
"DEGREES"

buffer-operation?string

Operation to apply to the region after the buffer. Only works join with buffer-value and buffer-unit query param. If not send, the default operation is dissolve

Value in

"DIFFERENCE"
"DISSOLVE"

region-id*number

Id of the region

region-dataset*string

Id of the dataset to obtain the region

Header Parameters

Content-Language?string

Value in

"es-ES"
"en-EN"

curl -X GET "https://example.com/v3/4wings/report?spatial-resolution=LOW&vessel-groups%5B0%5D=1%2C2&format=CSV&group-by=VESSEL_ID&temporal-resolution=YEARLY&datasets%5B0%5D=public-global-fishing-effort%3Alatest&filters%5B0%5D=flag+in+%28%27ESP%27%29&date-range=2021-01-01%2C2021-03-01&spatial-aggregation=false&buffer-value=100&buffer-unit=nauticalmiles&buffer-operation=true&region-id=555635930&region-dataset=public-mpa-all" \  -H "Content-Language: en-EN"

{  "entries": [    {      "callsign": "UBSS9",      "dataset": "public-global-vessel-identity:v3.0",      "date": "2022-01-13",      "detections": 12,      "entryTimestamp": "2022-01-14T14:00:00Z",      "exitTimestamp": "2022-01-14T16:00:00Z",      "firstTransmissionDate": "2019-07-12T12:08:27Z",      "flag": "ESP",      "geartype": "FISHING",      "hours": 26.6,      "imo": "8602866",      "lastTransmissionDate": "2025-03-01T23:55:50Z",      "lat": 49.33,      "lon": 141.15,      "mmsi": "273453380",      "shipName": "ALSEY",      "vesselIDs": 3,      "vesselId": "e6154b2e7-7762-4889-fb46-976ec72875e1",      "vesselType": "FISHING"    }  ],  "limit": 0,  "metadata": {},  "nextOffset": 0,  "offset": 0,  "total": 0}

{  "error": "Unauthorized",  "messages": [    {      "detail": "string",      "title": "string"    }  ],  "statusCode": 401}

{  "error": "Forbidden",  "messages": [    {      "detail": "string",      "title": "string"    }  ],  "statusCode": 403}

{  "error": "UnprocessableEntity",  "messages": [    {      "detail": "string",      "title": "string"    }  ],  "statusCode": 422}

{  "error": "Too Many Requests",  "messages": [    {      "detail": "string",      "metadata": {        "currentReportBody": {          "geojson": "string",          "region": {}        },        "currentReportUrl": "string"      },      "title": "string"    }  ],  "statusCode": 429}

{  "error": "Service Unavailable",  "messages": [    {      "detail": "string",      "title": "string"    }  ],  "statusCode": 503}

4Wings Report Response Fields

The 4Wings report endpoint returns different fields depending on the dataset, temporal-resolution, and group-by parameters used in your request.

Field	Type	Dataset	Description
date	string	All	Date or date range for the aggregated data. Format depends on temporal resolution: monthly (YYYY-MM), daily (YYYY-MM-DD), yearly (YYYY), entire (date-range query param value)
hours	number	Fishing Effort	Apparent fishing hours that the vessel associated with this vessel_id was fishing in the grid cell over the selected time range
hours	number	Vessel Presence	Vessel presence hours that the vessel associated with this vessel_id was present in the grid cell over the selected time range
detections	number	SAR Vessel Detections	Detections present in the grid cell over the selected time range
lat	number	All	Latitude of the center of the grid cell, in 10ths or 100th of a degree (depending on spatial resolution selection)
lon	number	All	Longitude of the center of the grid cell, in 10ths or 100th of a degree (depending on spatial resolution selection)
vessel_id	string	All	A unique vessel identity developed for internal use by Global Fishing Watch and API users, that combines available vessel identifiers such as name, callsign, and Maritime Mobile Service Identity (MMSI). See more details on vessel id
vesselIDs	number	All	Number of different vessel ids in the aggregated data
entryTimestamp	string (ISO 8601)	All	Timestamp when the vessel entered the region within the requested time range
exitTimestamp	string (ISO 8601)	All	Timestamp when the vessel exited the region within the requested time range
mmsi	string	All	Maritime Mobile Service Identity of the vessel, AIS identifier
flag	string	All	Flag state (ISO3 value) for the vessel as determined by the first three digits (MID) of the MMSI number. See more details on flag assignment
shipName	string	All	AIS reported name of the vessel
geartype	string	All	Vessel gear types estimated by GFW developed by aggregating available vessel registry records, reported AIS identity information, and estimated classification using machine learning. See more details on how we identify our gear types here
vessel_type	string	All	Vessel types from GFW include fishing vessels, carrier vessels, and support vessels. See more details on how we identify vessel types here
imo	string	All	AIS reported IMO (International Maritime Organization) of the vessel
callsign	string	All	Also known as IRCS (International Radio Call Sign) of the vessel, as reported on AIS
firstTransmissionDate	string	All	First date when there is a position transmitted on AIS by the vessel
lastTransmissionDate	string	All	Last date when there is a position transmitted on AIS by the vessel
dataset	string	All	Dataset version information when matched with AIS

Report running. The report continues executing. It returns a json response with the info of the report running. Example:

{
  "uri": "/v3/4wings/report?format=JSON&datasets%5B0%5D=public-global-fishing-effort%3Av3.0&date-range=2023-12-31T00%3A00%3A00.000Z%2C2024-01-10T00%3A00%3A00.000Z&spatial-aggregation=true&temporal-resolution=ENTIRE&region-dataset=public-eez-areas&group-by=VESSEL_ID",
  "status": "running",
  "lastUpdate": "2024-02-05T13:34:06+0000"
}

Report finished correctly. In this case the response will be the same that the original request sent (See possibles responses of the report endpoint).
Report finished with error. In this case the response will be a json with the info of the error. Example:

{
  "message": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "messages": [
      {
        "title": "region-id",
        "detail": "region-id query param is required"
      }
    ]
  },
  "status": 422
}

Report not found. In this case the endpoint return a 404 error. This can occurr because the last report response is only saved during 30 min after the report finished.

Create a report of a specified region

Report - HTTP Request

Report - AIS Apparent Fishing Effort examples

Report - SAR vessel detection examples

Report - AIS Vessel Presence examples

Report - POST

Authorization

Query Parameters

Header Parameters

Request Body

Report - GET

Authorization

Query Parameters

Header Parameters

4Wings Report Response Fields

Get last report generated

Get last report - HTTP Request

Report - Responses

On this page