NAV
cURL

Introduction

Welcome to the Global Fishing Watch Application Programming Interfaces (API) Documentation site!

Global Fishing Watch has created a technology portal that provides application programming interfaces, or APIs, to revolutionize the way we research and monitor human impacts across the world’s ocean.

Our APIs provide software instructions that enable automatic connection of our data and products to other systems so users can easily download and integrate our datasets, code, and models to power their own platforms. By providing streamlined access to information on current fishing vessel activity, identity and history, we are helping create solutions for a resilient, sustainable ocean.

Global Fishing Watch APIs are only available for non-commercial purposes. They are used by researchers, governments and technology companies.

Global Fishing Watch offers modern, low latency, secure and scalable REST APIs. Global Fishing Watch APIs use resource-oriented URLS, support HTTPS authentication and HTTPS verbs and leverage JSON in all responses.

We combine tracking data from the publicly available automatic identification system (AIS) and integrate that with information acquired through vessel monitoring systems that are operated by governments and made available to us through partnerships that we secure. Both AIS and VMS combine global positioning with a transmitter to regularly broadcast vessel location.

Harvesting big data from satellites and other sources

We combine tracking data from the publicly available automatic identification system (AIS) and integrate that with information acquired through vessel monitoring systems that are operated by governments and made available to us through partnerships that we secure. Both AIS and VMS combine global positioning with a transmitter to regularly broadcast vessel location.

Data available

You can find the following APIs and data:

We are planning to expand the list in the near future, if you need any specific one that you would like us to prioritize, contact us to send your suggestion.

Quick Start

  1. Register for a Global Fishing Watch account.

  2. Request an API Access Token

  3. Agree to the terms of use and attribute Global Fishing Watch in anything you publish.

  4. Submit HTTP request - Search a fishing vessel and get the fishing events

SEARCH A FISHING VESSEL


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/vessels/search?query=7831410&datasets=public-global-fishing-vessels:latest&limit=1&offset=0' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response includes the vessels matching your query.

{
    "metadata": {
        "query": "7831410",
        "suggestion": null,
        "field": "shipname"
    },
    "total": 2,
    "limit": 1,
    "offset": 0,
    "nextOffset": null,
    "entries": [
        {
            "callsign": "LW3058",
            "firstTransmissionDate": "2016-12-20T20:27:39Z",
            "flag": "ARG",
            "geartype": "squid_jigger",
            "id": "9b3e9019d-d67f-005a-9593-b66b997559e5",
            "imo": "7831410",
            "lastTransmissionDate": "2022-07-04T23:48:15Z",
            "mmsi": "701000948",
            "msgCount": 522034420,
            "posCount": 1884457,
            "shipname": "CLAUDINA",
            "source": "AIS",
            "vesselType": "Fishing",
            "years": [
                2016,
                2017,
                2018,
                2019,
                2020,
                2021,
                2022
            ],
            "dataset": "public-global-fishing-vessels:v20201001",
            "score": 87.7138
        }
    ]
}

GET FISHING EVENTS


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/events?vessels=9b3e9019d-d67f-005a-9593-b66b997559e5&datasets=public-global-fishing-events:latest&start-date=2017-01-01&end-date=2017-01-30&limit=1&offset=0' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response includes the fishing events from the vessel id found in the previous request.

{
    "metadata": {
        "datasets": [
            "public-global-fishing-events:v20201001"
        ],
        "vessels": [
            "9b3e9019d-d67f-005a-9593-b66b997559e5"
        ],
        "dateRange": {
            "from": "2017-01-01",
            "to": "2017-01-30"
        },
        "encounterTypes": []
    },
    "total": 10,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": [
        {
            "id": "718a4d93c16f78d9a54e9bc56d20c7e0",
            "type": "fishing",
            "start": "2017-01-18T23:56:16.000Z",
            "end": "2017-01-19T03:42:27.000Z",
            "position": {
                "lat": -46.1538,
                "lon": -63.2245
            },
            "regions": {
                "mpa": [],
                "eez": [
                  8466
                ],
                "rfmo": [
                  "ICCAT"
                ]
            },
            "boundingBox": [
                -63.21452500000001,
                -46.1618533333,
                -63.23098,
                -46.1495283333
            ],
            "distances": {
                "startDistanceFromShoreKm": 221,
                "endDistanceFromShoreKm": 220,
                "startDistanceFromPortKm": 242.616953,
                "endDistanceFromPortKm": 240.71707800000001
            },
            "vessel": {
                "id": "9b3e9019d-d67f-005a-9593-b66b997559e5",
                "name": "CLAUDINA",
                "ssvid": "701000948"
            },
            "fishing": {
                "totalDistanceKm": 2.1365631888840078,
                "averageSpeedKnots": 0.49600001274,
                "averageDurationHours": 0.15707175925925926
            }
        }
    ]
}

Search a fishing vessel by IMO = 7831410

Get one fishing event from the fishing vessel searched in the previous request and filter by Start Date=2017-06-01 and End Date=2017-06-30

Get your GFW Postman collection

You can download our Postman collection here to test some of the endpoints.

Remember to:

Map Visualization - 4Wings API

4Wings introduction

4Wings API (aka Map Visualization) allows you to get fast visualisation, navigation and analysis for gridded spatiotemporal datasets.You can:

Create a style for generate png tiles

GENERATE PNG TILES WITH TEMPORAL FILTER


curl --location --request POST 'https://gateway.api.globalfishingwatch.org/v2/4wings/generate-png?interval=10days&datasets%5B0%5D=public-global-fishing-effort:latest&color=%23361c0c&date-range=2020-01-01,2020-01-31' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "colorRamp": {
        "stepsByZoom": {
            "0": [
                {
                    "color": "rgba(54,28,12,25)",
                    "value": 663
                },
                {
                    "color": "rgba(54,28,12,127)",
                    "value": 17471
                },
                {
                    "color": "rgba(54,28,12,153)",
                    "value": 27895
                },
                {
                    "color": "rgba(54,28,12,178)",
                    "value": 38839
                },
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 60002
                },
                {
                    "color": "rgba(54,28,12,0)",
                    "value": 0
                },
                {
                    "color": "rgba(54,28,12,51)",
                    "value": 2400
                },
                {
                    "color": "rgba(54,28,12,76)",
                    "value": 5487
                },
                {
                    "color": "rgba(54,28,12,102)",
                    "value": 10663
                }
            ],
            "1": [
                {
                    "color": "rgba(54,28,12,25)",
                    "value": 165
                },
                {
                    "color": "rgba(54,28,12,51)",
                    "value": 600
                },
                {
                    "color": "rgba(54,28,12,76)",
                    "value": 1371
                },
                {
                    "color": "rgba(54,28,12,127)",
                    "value": 4367
                },
                {
                    "color": "rgba(54,28,12,0)",
                    "value": 0
                },
                {
                    "color": "rgba(54,28,12,102)",
                    "value": 2665
                },
                {
                    "color": "rgba(54,28,12,153)",
                    "value": 6973
                },
                {
                    "color": "rgba(54,28,12,178)",
                    "value": 9709
                },
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 15000
                }
            ],
            "10": [
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 0
                }
            ],
            "11": [
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 0
                }
            ],
            "12": [
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 0
                }
            ],
            "2": [
                {
                    "color": "rgba(54,28,12,102)",
                    "value": 666
                },
                {
                    "color": "rgba(54,28,12,153)",
                    "value": 1743
                },
                {
                    "color": "rgba(54,28,12,0)",
                    "value": 0
                },
                {
                    "color": "rgba(54,28,12,51)",
                    "value": 150
                },
                {
                    "color": "rgba(54,28,12,76)",
                    "value": 342
                },
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 3750
                },
                {
                    "color": "rgba(54,28,12,25)",
                    "value": 41
                },
                {
                    "color": "rgba(54,28,12,127)",
                    "value": 1091
                },
                {
                    "color": "rgba(54,28,12,178)",
                    "value": 2427
                }
            ],
            "3": [
                {
                    "color": "rgba(54,28,12,0)",
                    "value": 0
                },
                {
                    "color": "rgba(54,28,12,153)",
                    "value": 435
                },
                {
                    "color": "rgba(54,28,12,127)",
                    "value": 272
                },
                {
                    "color": "rgba(54,28,12,178)",
                    "value": 606
                },
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 937
                },
                {
                    "color": "rgba(54,28,12,25)",
                    "value": 10
                },
                {
                    "color": "rgba(54,28,12,51)",
                    "value": 37
                },
                {
                    "color": "rgba(54,28,12,76)",
                    "value": 85
                },
                {
                    "color": "rgba(54,28,12,102)",
                    "value": 166
                }
            ],
            "4": [
                {
                    "color": "rgba(54,28,12,51)",
                    "value": 9
                },
                {
                    "color": "rgba(54,28,12,102)",
                    "value": 41
                },
                {
                    "color": "rgba(54,28,12,127)",
                    "value": 68
                },
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 234
                },
                {
                    "color": "rgba(54,28,12,25)",
                    "value": 2
                },
                {
                    "color": "rgba(54,28,12,76)",
                    "value": 21
                },
                {
                    "color": "rgba(54,28,12,153)",
                    "value": 108
                },
                {
                    "color": "rgba(54,28,12,178)",
                    "value": 151
                },
                {
                    "color": "rgba(54,28,12,0)",
                    "value": 0
                }
            ],
            "5": [
                {
                    "color": "rgba(54,28,12,51)",
                    "value": 2
                },
                {
                    "color": "rgba(54,28,12,76)",
                    "value": 5
                },
                {
                    "color": "rgba(54,28,12,102)",
                    "value": 10
                },
                {
                    "color": "rgba(54,28,12,127)",
                    "value": 17
                },
                {
                    "color": "rgba(54,28,12,153)",
                    "value": 27
                },
                {
                    "color": "rgba(54,28,12,178)",
                    "value": 37
                },
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 58
                },
                {
                    "color": "rgba(54,28,12,25)",
                    "value": 0
                }
            ],
            "6": [
                {
                    "color": "rgba(54,28,12,51)",
                    "value": 0
                },
                {
                    "color": "rgba(54,28,12,76)",
                    "value": 1
                },
                {
                    "color": "rgba(54,28,12,102)",
                    "value": 2
                },
                {
                    "color": "rgba(54,28,12,127)",
                    "value": 4
                },
                {
                    "color": "rgba(54,28,12,153)",
                    "value": 6
                },
                {
                    "color": "rgba(54,28,12,178)",
                    "value": 9
                },
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 14
                }
            ],
            "7": [
                {
                    "color": "rgba(54,28,12,102)",
                    "value": 0
                },
                {
                    "color": "rgba(54,28,12,153)",
                    "value": 1
                },
                {
                    "color": "rgba(54,28,12,178)",
                    "value": 2
                },
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 3
                }
            ],
            "8": [
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 0
                }
            ],
            "9": [
                {
                    "color": "rgba(54,28,12,255)",
                    "value": 0
                }
            ]
        }
    },
    "url": "https://gateway.api.globalfishingwatch.org/v2/4wings/tile/heatmap/{z}/{x}/{y}?format=png&interval=10days&datasets[0]=public-global-fishing-effort:latest&date-range=2020-01-01,2020-01-31&style=eyJjb2xvciI6WzU0LDI4LDEyXSwicmFtcCI6WzAsNjYzLjIzMTk0NDQ0NDQ0NDUsMjQwMC4wMDMzMzMzMzMzMzMsNTQ4Ny4wNDIyMjIyMjIyMjMsMTA2NjMuMDY2OTQ0NDQ0NDQzLDE3NDcxLjUxODA1NTU1NTU1NiwyNzg5NS42NjUyNzc3Nzc3NzgsMzg4MzkuNTUyNTAwMDAwMDA1LDYwMDAyLjcxNDk5OTk5OTk4XX0="
}

GENERATE PNG TILES WITH GEAR TYPE AND TEMPORAL FILTER


curl --location --request POST 'https://gateway.api.globalfishingwatch.org/
/v2/4wings/generate-png?interval=10days&datasets[0]=public-global-fishing-effort:latest&filters[0]=geartype in ("tuna_purse_seines","driftnets")&date-range=2020-01-01,2020-01-31'  \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "colorRamp": {
        "stepsByZoom": {
            "0": [
                {
                   "color": "rgba(22,63,137,0)",
                   "value": 0
                },
                {
                   "color": "rgba(22,63,137,102)",
                   "value": 384
                },
                {
                   "color": "rgba(22,63,137,178)",
                   "value": 1502
                },
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 1944
                },
                {
                   "color": "rgba(22,63,137,25)",
                   "value": 26
                },
                {
                   "color": "rgba(22,63,137,51)",
                   "value": 88
                },
                {
                   "color": "rgba(22,63,137,76)",
                   "value": 186
                },
                {
                   "color": "rgba(22,63,137,127)",
                   "value": 677
                },
                {
                   "color": "rgba(22,63,137,153)",
                   "value": 1047
                }
            ],
            "1": [
                {
                   "color": "rgba(22,63,137,0)",
                   "value": 0
                },
                {
                   "color": "rgba(22,63,137,51)",
                   "value": 22
                },
                {
                   "color": "rgba(22,63,137,102)",
                   "value": 96
                },
                {
                   "color": "rgba(22,63,137,153)",
                   "value": 261
                },
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 486
                },
                {
                   "color": "rgba(22,63,137,25)",
                   "value": 6
                },
                {
                   "color": "rgba(22,63,137,76)",
                   "value": 46
                },
                {
                   "color": "rgba(22,63,137,127)",
                   "value": 169
                },
                {
                   "color": "rgba(22,63,137,178)",
                   "value": 375
                }
            ],
            "10": [
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 0
                }
            ],
            "11": [
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 0
                }
            ],
            "12": [
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 0
                }
            ],
            "2": [
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 121
                },
                {
                   "color": "rgba(22,63,137,25)",
                   "value": 1
                },
                {
                   "color": "rgba(22,63,137,76)",
                   "value": 11
                },
                {
                   "color": "rgba(22,63,137,102)",
                   "value": 24
                },
                {
                   "color": "rgba(22,63,137,127)",
                   "value": 42
                },
                {
                   "color": "rgba(22,63,137,178)",
                   "value": 93
                },
                {
                   "color": "rgba(22,63,137,0)",
                   "value": 0
                },
                {
                   "color": "rgba(22,63,137,51)",
                   "value": 5
                },
                {
                   "color": "rgba(22,63,137,153)",
                   "value": 65
                }
            ],
            "3": [
                {
                   "color": "rgba(22,63,137,102)",
                   "value": 6
                },
                {
                   "color": "rgba(22,63,137,127)",
                   "value": 10
                },
                {
                   "color": "rgba(22,63,137,153)",
                   "value": 16
                },
                {
                   "color": "rgba(22,63,137,178)",
                   "value": 23
                },
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 30
                },
                {
                   "color": "rgba(22,63,137,25)",
                   "value": 0
                },
                {
                   "color": "rgba(22,63,137,51)",
                   "value": 1
                },
                {
                   "color": "rgba(22,63,137,76)",
                   "value": 2
                }
            ],
            "4": [
                {
                   "color": "rgba(22,63,137,102)",
                   "value": 1
                },
                {
                   "color": "rgba(22,63,137,127)",
                   "value": 2
                },
                {
                   "color": "rgba(22,63,137,153)",
                   "value": 4
                },
                {
                   "color": "rgba(22,63,137,178)",
                   "value": 5
                },
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 7
                },
                {
                   "color": "rgba(22,63,137,76)",
                   "value": 0
                }
            ],
            "5": [
                {
                   "color": "rgba(22,63,137,127)",
                   "value": 0
                },
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 1
                }
            ],
            "6": [
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 0
                }
            ],
            "7": [
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 0
                }
            ],
            "8": [
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 0
                }
            ],
            "9": [
                {
                   "color": "rgba(22,63,137,255)",
                   "value": 0
                }
            ]
        }
    }
}

A Style is a document that defines the visual appearance of a map, in this case the map will be in png format, it includes what data to draw, the order to draw it in, and how to style the data when drawing it. You can find on the right, two examples:

HTTP Request

POST https://gateway.api.globalfishingwatch.org/v2/4wings/generate-png

URL Parameters

Parameter Description Required Format Param Type
color Color in hexadecimal used to generate the color ramp Example: #361c0c False string query
interval Tiles are available at several time resolutions (hourly, daily and 10 days), it means one frame every one hour, one day or 10 days. For each resolution, the the max displayable length items: 1 hour: 20 days, 1 day: 1 year and 10 days: several years depending on the dataset for AIS Fishing effort it starts in 2012. Example: 10days False Enum: ['10days', 'day', 'hour'] query
datasets[0] 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 Example: public-global-fishing-effort:latest True string query
filters[0] 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. Example: flag in ('ESP') False string query
date-range Start date and end date to filter the data Example: 2021-01-01,2021-03-01 False string query
style Id of the style obtained with endpoint /v2/4wings/generate-png. Example : eyJjb2xvciI6WzIyLDYzLDEzN10sInJhbXAiOlswLDE4NC41MDM4ODg4ODg4ODg4Nyw2NjkuNDg3Nzc3Nzc3Nzc3OAwxNDQ2LjUwODA1NTU1NTU1NTMsMjg2OS42MjA1NTU1NTU1NTU3LDU4OTEuMDI1NTU1NTU1NTU1LDg1MjguODkxMTExMTExMTEsMTE5MTYuNjA2OTQ0NDQ0NDQ0LDE3OTMyLjI3NjM4ODg4ODg4OF18 False string

Get fishing effort in raster format by tile coordinates

GET PNG TILE BY COORDINATES


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/4wings/tile/heatmap/2/3/1?format=png&interval=10days&datasets[0]=public-global-fishing-effort:latest&date-range=2020-01-01,2020-01-31&style=[STYLE]' \
  -H "Authorization: Bearer [TOKEN]" \
  -o "tile-by-coordinates.png" 

Make sure to replace [TOKEN] with your API Access Token and [STYLE] with the style obtained in the previous endpoint "Create a style for generate png tiles" in the 'url' field

If the request is successful, in this example the response will be a png file

This endpoint allows you to get details of the cell of the tile (in PNG or MVT format depending on the parameter).

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/4wings/tile/heatmap/{z}/{x}/{y}

URL Parameters

Parameter Description Required Format Param Type
z Zoom level (from 0 to 12) Example: 1 True number path
x X index (lat) of the tile True number path
y Y index (lon) of the tile True number path
temporal-aggregation Aggregates temporarily the data in the tile Example: True False boolean query
interval Tiles are available at several time resolutions (hourly, daily and 10 days), it means one frame every one hour, one day or 10 days. For each resolution, the the max displayable length items: 1 hour: 20 days, 1 day: 1 year and 10 days: several years depending on the dataset for AIS Fishing effort it starts in 2012. Example: 10days False Enum: ['10days', 'day', 'hour'] query
datasets[0] 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. Example: public-global-fishing-effort:latest True string query
filters[0] 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. Example: flag in ('ESP') False string query
date-range Start date and end date to filter the data Example: 2021-01-01,2021-03-01 False string query
format Format of response Example: mvt False Enum: ['mvt', 'png', 'intArray'] query

Generate bins of inputs to know the data (For example to create a color ramp of the data)

GENERATE FISHING EFFORT REPORT GROUPED BY YEAR AND BY CUSTOM POLYGON IN JSON FORMAT


curl --location -g --request GET 'https://gateway.api.globalfishingwatch.org/v2/4wings/bins/1?datasets[0]=public-global-fishing-effort:latest&temporal-aggregation=false&num-bins=9&interval=10days' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

[
    [
        0,
        681.7608333333334,
        3155.027222222222,
        11128.39916666666,
        24225.742837079433,
        39811.977777777785,
        59699.12027777779,
        88621.67472222226,
        118122.56555555557
    ]
]

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/4wings/bins/{z}

URL Parameters

Parameter Description Required Format Param Type
z Zoom level (from 0 to 12) True number path
temporal-aggregation Aggregates temporarily the data in the tile Example: True False boolean query
num-bins Number of bins or buckets that you would like Example: 10 False number query
interval Tiles are available at several time resolutions (hourly, daily and 10 days), it means one frame every one hour, one day or 10 days. For each resolution, the the max displayable length items: 1 hour: 20 days, 1 day: 1 year and 10 days: several years depending on the dataset for AIS Fishing effort it starts in 2012. Example: 10days False Enum: ['10days', 'day', 'hour'] query
datasets[0] 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. Example: public-global-fishing-effort:latest True string query
filters[0] 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. Example: flag in ('ESP') False string query
date-range Start date and end date to filter the data Example: 2021-01-01,2021-03-01 False string query

Return info in the cells of the tile specified

GET DETAIL OF A TILE TO ALLOW FURTHER INTERACTION

curl --location -g --request GET 'https://gateway.api.globalfishingwatch.org/v2/4wings/interaction/1/0/0/107?date-range=2021-01-01,2021-12-31&datasets[0]=public-global-fishing-effort:latest' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be: fishing hours and vessel id that allow you to get more detail of a vessel by using the Vessel API

{
    "total": 1,
    "limit": null,
    "offset": null,
    "nextOffset": null,
    "metadata": {},
    "entries": [
        [
            {
                "hours": 11.455833333333334,
                "id": "f2134364c-c3d5-8ee9-ddd4-5511c0500a50"
            },
            {
                "hours": 9.895000000000001,
                "id": "f042d0bcf-fe96-cad5-5833-36b4aff2e87a"
            },
            {
                "hours": 12.617222222222223,
                "id": "e2d464a53-35ed-f059-c7e2-1ac76e12c9cc"
            },
            {
                "hours": 1.238611111111111,
                "id": "c88e21112-2a09-4d56-196e-ff9cb26f76c9"
            },
            {
                "hours": 0.053055555555555564,
                "id": "b8de3c8e8-84f0-ba2f-528c-ff877e2d0e9e"
            },
            {
                "hours": 3.531944444444444,
                "id": "b5d3439b6-6d19-5385-9d6b-08a0dfd60fa7"
            },
            {
                "hours": 18.993333333333332,
                "id": "ab75d8a33-3f93-62eb-0c86-38d8c742eff3"
            },
            {
                "hours": 9.597777777777777,
                "id": "a812d4320-0608-5ad0-1929-d5206eda123a"
            },
            {
                "hours": 34.2575,
                "id": "9eab37595-5bf1-471e-2e38-c070ebb00a7a"
            },
            {
                "hours": 47.11222222222222,
                "id": "9cf14ce31-144f-dda7-ded3-743bec9e41db"
            },
            {
                "hours": 9.228888888888891,
                "id": "9aed1677e-ef23-f541-58eb-8d755d410df4"
            },
            {
                "hours": 1.6025,
                "id": "784830b33-3de5-b572-61aa-bd9496643fb1"
            },
            {
                "hours": 5.095000000000001,
                "id": "70a3ff9ca-ab64-12b2-6446-34cdf14000c6"
            },
            {
                "hours": 5.3925,
                "id": "6b3129a20-009f-1741-5877-a714ea11cf2b"
            },
            {
                "hours": 16.631666666666668,
                "id": "68ab5e789-96a1-fd61-016c-92bd413a9682"
            },
            {
                "hours": 10.718055555555555,
                "id": "65aaba596-62eb-49af-910d-f7d9d47a2d06"
            },
            {
                "hours": 9.872222222222222,
                "id": "3f7c46fe4-45f8-0685-a7e5-60d531c7c352"
            },
            {
                "hours": 8.126666666666667,
                "id": "2ab8c04ff-f0e3-a3f1-7ef4-2428604174e0"
            },
            {
                "hours": 38.58861111111111,
                "id": "1abad9a58-8758-383e-8c58-6c8029ecaa44"
            },
            {
                "hours": 10.016388888888889,
                "id": "184b291b6-619c-748c-1f32-5fe46616d0dc"
            },
            {
                "hours": 0.11166666666666666,
                "id": "1738bc096-6373-5ae6-8bd0-dd31ecf6c0eb"
            },
            {
                "hours": 2.338888888888889,
                "id": "098ac6ed6-65a9-260b-fb84-8c932eb977ae"
            },
            {
                "hours": 47.81805555555555,
                "id": "050743514-4618-79b3-8643-96ada9281517"
            },
            {
                "hours": 17.753055555555555,
                "id": "04b95cb83-31d8-06e7-0845-8691696643f5"
            }
        ]
    ]
}

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/4wings/interaction/{z}/{x}/{y}/{cells}

URL Parameters

Parameter Description Required Format Param Type
z Zoom level (from 0 to 12) True number path
x X index (lat) of the tile True number path
y Y index (lon) of the tile True number path
cells Indexes of cells separated by comma Example: 107,1,2 True string path
limit Number maximun of results Example: 10 False number query
datasets[0] 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. Example: public-global-fishing-effort:latest True string query
filters[0] 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. Example: flag in ('ESP') False string query
date-range Start date and end date to filter the data Example: 2021-01-01,2021-03-01 False string query

Create a report of a specified region

GENERATE FISHING EFFORT REPORT GROUPED BY YEAR AND BY CUSTOM POLYGON IN JSON FORMAT


curl --location -g --request POST 'https://gateway.api.globalfishingwatch.org/v2/4wings/report?spatial-resolution=low&temporal-resolution=yearly&group-by=flag&datasets[0]=public-global-fishing-effort:latest&date-range=2021-01-01T00:00:00.000Z,2022-01-01T00:00:00.000Z&format=json' \
  -H "Authorization: Bearer [TOKEN]"
  -H 'Content-Type: application/json' \
--data-raw '{"geojson":{"type":"Polygon","coordinates":[[[-76.11328125,-26.273714024406416],[-76.201171875,-26.980828590472093],[-76.376953125,-27.527758206861883],[-76.81640625,-28.30438068296276],[-77.255859375,-28.767659105691244],[-77.87109375,-29.152161283318918],[-78.486328125,-29.45873118535532],[-79.189453125,-29.61167011519739],[-79.892578125,-29.6880527498568],[-80.595703125,-29.61167011519739],[-81.5625,-29.382175075145277],[-82.177734375,-29.07537517955835],[-82.705078125,-28.6905876542507],[-83.232421875,-28.071980301779845],[-83.49609375,-27.683528083787756],[-83.759765625,-26.980828590472093],[-83.84765625,-26.35249785815401],[-83.759765625,-25.64152637306576],[-83.583984375,-25.16517336866393],[-83.232421875,-24.447149589730827],[-82.705078125,-23.966175871265037],[-82.177734375,-23.483400654325635],[-81.5625,-23.241346102386117],[-80.859375,-22.998851594142906],[-80.15625,-22.917922936146027],[-79.453125,-22.998851594142906],[-78.662109375,-23.1605633090483],[-78.134765625,-23.40276490540795],[-77.431640625,-23.885837699861995],[-76.9921875,-24.28702686537642],[-76.552734375,-24.846565348219727],[-76.2890625,-25.48295117535531],[-76.11328125,-26.273714024406416]]]}}'

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "total": 1,
    "limit": null,
    "offset": null,
    "nextOffset": null,
    "metadata": {},
    "entries": [
        {
            "public-global-fishing-effort:v20201001": [
                {
                    "date": "2021",
                    "flag": "ESP",
                    "hours": 0.9591666666666667,
                    "lat": -24.7,
                    "lon": -78.6
                },
                {
                    "date": "2021",
                    "flag": "ESP",
                    "hours": 0.41805555555555557,
                    "lat": -24.2,
                    "lon": -77.8
                },
                {
                    "date": "2021",
                    "flag": "ESP",
                    "hours": 0.27555555555555555,
                    "lat": -24.6,
                    "lon": -78.4
                },
                {
                    "date": "2021",
                    "flag": "ESP",
                    "hours": 0.034444444444444444,
                    "lat": -24.7,
                    "lon": -78.5
                },
                {
                    "date": "2021",
                    "flag": "ESP",
                    "hours": 0.4283333333333333,
                    "lat": -27.3,
                    "lon": -82
                }
            ]
        }
    ]
}

GENERATE FISHING EFFORT REPORT GROUPED BY GEAR TYPE, USING EXISTING REGIONS (Russian EEZ) IN CSV FORMAT. To get details of existing regions, check Regions in the Reference data section


curl --location -g --request POST 'https://gateway.api.globalfishingwatch.org/v2/4wings/report?spatial-resolution=low&temporal-resolution=monthly&group-by=gearType&datasets[0]=public-global-fishing-effort:latest&date-range=2022-01-01,2022-05-01&format=csv' \
--header 'Authorization: Bearer [TOKEN]' \
--header 'Content-Type: application/json' \
--output 'report-grouped.json' \
--data-raw '{
    "region": {
        "dataset": "public-eez-areas",
        "id": 5690
    }
}'

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be a ZIP file including the CSV file and a pdf with data considerations.

HTTP Request

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

URL Parameters

Parameter Description Required Format Param Type
spatial-resolution 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. Example: low False Enum: ['low', 'high'] query
format 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. Example: csv True Enum: ['csv', 'tif', 'json'] query
group-by 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. Only required when spatial-aggregation is True. Example: vessel_id False Enum: ['vessel_id', 'flag', 'gearType', 'flagAndGearType', 'mmsi'] query
temporal-resolution 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, or if you request csv, group by vessel_id and entire, you get one row per vessel id. Example: yearly True Enum: ['daily', 'monthly', 'yearly','entire'] query
datasets[0] 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. Example: public-global-fishing-effort:latest True string query
filters[0] 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. Example: flag in ('ESP') False string query
date-range Start date and end date to filter the data. Maximum 366 days. Example: 2021-01-01,2021-03-01 False string query
spatial-aggregation Aggregates spatially the data in the report. With value true, the formats supported are only csv and json. Example: True False boolean query

Body

Key Description Required Format Param Type
geojson Geometry to filter the data in GeoJSON format False object body
region Object with region information (To get details of existing regions, check Regions in the Reference data section) False object body
region.dataset Id of the dataset to obtain the region (example: public-eez-areas) False string body
region.id Id of the region (example: 5690) False string body

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

Vessels API

Introduction Vessels API

Vessels API allows you to search for vessels and get vessel identity details. You can:

SEARCH ANY VESSEL BY MMSI = 224224000


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/vessels/search?query=224224000&datasets=public-global-support-vessels:latest,public-global-carrier-vessels:latest,public-global-fishing-vessels:latest&limit=10&offset=0' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "query": "224224000",
        "suggestion": null,
        "field": "shipname"
    },
    "total": 1,
    "limit": 10,    
    "offset": 0,
    "nextOffset": null,
    "entries": [
        {
            "callsign": "EBSJ",
            "firstTransmissionDate": "2015-10-13T15:47:16Z",
            "flag": "ESP",
            "geartype": null,
            "id": "3c99c326d-dd2e-175d-626f-a3c488a4342b",
            "imo": "8733445",
            "lastTransmissionDate": "2019-10-15T12:10:51Z",
            "mmsi": "224224000",
            "msgCount": 1887249,
            "posCount": 73677,
            "shipname": "AGURTZA BERRIA",
            "source": "AIS",
            "vesselType": "Purse Seine Support",
            "years": [
                2015,
                2016,
                2017,
                2018,
                2019
            ],
            "dataset": "public-global-support-vessels:v20201001",
            "score": 29.100689
        }
    ]
}

This endpoint searches for a vessel given a free form query. The query will be matched against any identifiers for the vessel, and a paginated, ranked results list will be returned. It allows you to perform a basic search of a vessel by sending some identifier, for example: MMSI, IMO, CALL SIGN,Shipname, etc.

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/vessels/search

URL Parameters

Parameter Description Required Format Param Type
limit Amount of search results to return. Example: 10 True number query
offset Offset into the search results, used for pagination. It starts at 0. It is used in combination with the param “limit”, for example you send limit = 5 and you get in the response total vessels =10. So, If you send offset =0 OR you don’t send it, you will get the first 5 results (first page). Therefore, in order to get the second page, you need to send offset = 5 which is the position of the first element you want from the second page. Example: 5 True number query
datasets Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here. You can send several datasets separated by comma. Example: public-global-fishing-vessels:latest,public-global-carrier-vessels:latest True string query
query Free form query that allows you to search a vessel by sending some identifier, for example: MMSI, IMO, CALL SIGN,Shipname, etc. Identifier depends on the dataset. You can send one character length but we recommend sending at least 3 characters. Example: Don tito True string query
binary If the response should be in binary format (proto buffer) or not. It is useful if you want to improve the performance of your platform. A decoder is needed to transform the response. Default is False. Example: True False boolean query
suggest-field Field for suggestion. The list of fields to suggest depend on the dataset Example: shipname False string query
query-fields List of fields to match with the search query instead of the entire object property. The list of query fields depend on the dataset (separated by comma) Example: shipname,mmsi False string query

SEARCH ANY VESSEL BY MMSI AND IMO AND A VESSEL NAME


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/vessels/advanced-search?datasets=public-global-carrier-vessels:latest,public-global-fishing-vessels:latest,public-global-support-vessels:latest&query=shipname%20LIKE%20%27%25GABU%20REEFE%25%27%20OR%20imo%20%3D%20%278300949%27&limit=1&offset=0' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "query": "shipname LIKE '%GABU REEFE%' OR imo = '8300949'"
    },
    "total": 3,
    "limit": 1,
    "offset": 1,
    "nextOffset": 1,
    "entries": [
        {
            "callsign": "ER2732",
            "firstTransmissionDate": "2019-02-22T21:46:13Z",
            "flag": "MDA",
            "geartype": null,
            "id": "0b7047cb5-58c8-6e63-4bfd-96a6af515c91",
            "imo": "8300949",
            "lastTransmissionDate": "2022-02-17T14:08:20Z",
            "mmsi": "214182732",
            "msgCount": 70035084,
            "posCount": 378287,
            "shipname": "GABU REEFER",
            "source": "AIS",
            "vesselType": "Carrier",
            "years": [
                2019,
                2020,
                2021,
                2022
            ],
            "dataset": "public-global-carrier-vessels:v20201001",
            "score": 7.6147256
        }
    ]
}

This endpoint allows you to perform an advanced search by creating a query like shipname LIKE '%GABU REEFE%' OR imo = '8300949. Where you can combine several fields, for example: id (vessel id), callsign, flag, imo, mmsi, shipname, normalized_shipname, lastTransmissionDate and firstTransmissionDate.

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/vessels/advanced-search

URL Parameters

Parameter Description Required Format Param Type
limit Amount of search results to return. Example: 10 True number query
offset Offset into the search results, used for pagination. It starts at 0. It is used in combination with the param “limit”, for example you send limit = 5 and you get in the response total vessels =10. So, If you send offset =0 OR you don’t send it, you will get the first 5 results (first page). Therefore, in order to get the second page, you need to send offset = 5 which is the position of the first element you want from the second page. Example: 5 True number query
datasets Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here. You can send several datasets separated by comma. Example: public-global-fishing-vessels:latest,public-global-carrier-vessels:latest True string query
query Advanced query that allows you to search a vessel by sending several identifiers. The list of identifiers depends on the dataset. You can combine logic operators like AND, OR, LIKE, >= , <. Example: (shipname LIKE '%SEIN PHOENIX%' OR mmsi = '441618000' OR imo = '9047271' OR callsign='D8SP') AND lastTransmissionDate >= '2021-05-29' AND firstTransmissionDate <= '2021-08-29' AND flag = 'KOR' True string query

Get list of vessels filtered by ids

GET DETAILS OF TWO FISHING VESSELS AND ONE CARRIER


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/vessels?datasets=public-global-fishing-vessels:latest,public-global-carrier-vessels:latest,public-global-support-vessels:latest&ids=8c7304226-6c71-edbe-0b63-c246734b3c01,6583c51e3-3626-5638-866a-f47c3bc7ef7c,71e7da672-2451-17da-b239-857831602eca' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {},
    "total": 3,
    "limit": null,
    "offset": null,
    "nextOffset": null,
    "entries": [
        {
            "callsign": "DTBY3",
            "firstTransmissionDate": "2013-09-02T03:59:51Z",
            "flag": "KOR",
            "geartype": "tuna_purse_seines",
            "id": "6583c51e3-3626-5638-866a-f47c3bc7ef7c",
            "imo": "891948900",
            "lastTransmissionDate": "2022-06-24T06:15:01Z",
            "mmsi": "441734000",
            "msgCount": 3466294,
            "posCount": 196191,
            "shipname": "ADRIA",
            "source": "AIS",
            "vesselType": "Fishing",
            "years": [
                2013,
                2014,
                2015,
                2017,
                2020
            ],
            "dataset": "public-global-fishing-vessels:v20201001"
        },
        {
            "callsign": "DUQA-7",
            "firstTransmissionDate": "2017-02-15T05:54:53Z",
            "flag": "PHL",
            "geartype": "tuna_purse_seines",
            "id": "71e7da672-2451-17da-b239-857831602eca",
            "imo": "8118322",
            "lastTransmissionDate": "2019-08-09T05:56:14Z",
            "mmsi": "548012100",
            "msgCount": 1967237,
            "posCount": 105523,
            "shipname": "JOHN REYNALD",
            "source": "AIS",
            "vesselType": "Fishing",
            "years": [
                2017,
                2018,
                2019
            ],
            "dataset": "public-global-fishing-vessels:v20201001"
        },
        {
            "callsign": "5BWC3",
            "firstTransmissionDate": "2013-05-15T20:18:31Z",
            "flag": "CYP",
            "geartype": null,
            "id": "8c7304226-6c71-edbe-0b63-c246734b3c01",
            "imo": "9076260",
            "lastTransmissionDate": "2022-07-10T23:57:22Z",
            "mmsi": "210631000",
            "msgCount": 132125326,
            "posCount": 825764,
            "shipname": "FRIO FORWIN",
            "source": "AIS",
            "vesselType": "Carrier",
            "years": [
                2013,
                2014,
                2015,
                2016,
                2017,
                2018,
                2019,
                2020,
                2021,
                2022
            ],
          "dataset": "public-global-carrier-vessels:v20201001"
        }
    ]
}

After you perform a Basic or an Advanced Search, you get the vessel id, for example 58cf536b1-1fca-dac3-ad31-7411a3708dcd. You can use this endpoint to get the details of a list of specific vessel ids.

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/vessels

URL Parameters

Parameter Description Required Format Param Type
datasets Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here. You can send several datasets separated by comma. Example: public-global-fishing-vessels:latest,public-global-carrier-vessels:latest True string query
ids List of vessel ids separated by comma. You can get this information using the search endpoints Example: 6583c51e3-3626-5638-866a-f47c3bc7ef7c True string query
binary If the response should be in binary format (proto buffer) or not. It is useful if you want to improve the performance of your platform. A decoder is needed to transform the response. Default is False. Example: True False boolean query

Get vessel by id

GET DETAILS OF ONE VESSEL


curl --location --request GET 'https://gateway.globalfishingwatch.org/v2/vessels/8c7304226-6c71-edbe-0b63-c246734b3c01?datasets=public-global-carrier-vessels:latest' \\
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "callsign": "5BWC3",
    "firstTransmissionDate": "2013-05-15T20:18:31Z",
    "flag": "CYP",
    "geartype": null,
    "id": "8c7304226-6c71-edbe-0b63-c246734b3c01",
    "imo": "9076260",
    "lastTransmissionDate": "2022-07-10T23:57:22Z",
    "mmsi": "210631000",
    "msgCount": 132125326,
    "posCount": 825764,
    "shipname": "FRIO FORWIN",
    "source": "AIS",
    "vesselType": "Carrier",
    "years": [
        2013,
        2014,
        2015,
        2016,
        2017,
        2018,
        2019,
        2020,
        2021,
        2022
    ],
    "dataset": "public-global-carrier-vessels:v20201001"
}

After you perform a Basic or an Advanced Search, you get the vessel id, for example 58cf536b1-1fca-dac3-ad31-7411a3708dcd. You can use this endpoint to get the details of ONE vessel id.

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/vessels/{vesselId}

URL Parameters

Parameter Description Required Format Param Type
vesselId Example: 6583c51e3-3626-5638-866a-f47c3bc7ef7c True string path
dataset Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here. You can send several datasets separated by comma. Example: public-global-fishing-vessels:latest,public-global-carrier-vessels:latest True string query

Events API

Introduction Events API

Events API allows you to explore different activities of a vessel. You can analyze:

Check more detail about data caveats here.

Get All Events (GET endpoint)

GET FISHING EVENTS


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/events?vessels=9b3e9019d-d67f-005a-9593-b66b997559e5&datasets=public-global-fishing-events:latest&start-date=2017-01-01&end-date=2017-01-31&limit=1&offset=0' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "datasets": [
            "public-global-fishing-events:v20201001"
        ],
        "vessels": [
            "9b3e9019d-d67f-005a-9593-b66b997559e5"
        ],
        "dateRange": {
            "from": "2017-01-01",
            "to": "2017-01-31"
        },
        "encounterTypes": []
    },
    "total": 10,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": [
        {
            "id": "718a4d93c16f78d9a54e9bc56d20c7e0",
            "type": "fishing",
            "start": "2017-01-18T23:56:16.000Z",
            "end": "2017-01-19T03:42:27.000Z",
            "position": {
                "lat": -46.1538,
                "lon": -63.2245
            },
            "regions": {
                "mpa": [],
                "eez": [
                    8466
                ],
                "rfmo": [
                    "ICCAT"
                ]
            },
            "boundingBox": [
                -63.21452500000001,
                -46.1618533333,
                -63.23098,
                -46.1495283333
            ],
            "distances": {
                "startDistanceFromShoreKm": 221,
                "endDistanceFromShoreKm": 220,
                "startDistanceFromPortKm": 242.616953,
                "endDistanceFromPortKm": 240.71707800000001
            },
            "vessel": {
                "id": "9b3e9019d-d67f-005a-9593-b66b997559e5",
                "name": "CLAUDINA",
                "ssvid": "701000948"
            },
            "fishing": {
                "totalDistanceKm": 2.1365631888840078,
                "averageSpeedKnots": 0.49600001274,
                "averageDurationHours": 0.15707175925925926
            }
        }
    ]
}

GET ENCOUNTER EVENTS


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/events?datasets=public-global-encounters-events:latest&vessels=8c7304226-6c71-edbe-0b63-c246734b3c01&limit=1&offset=0' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "datasets": [
            "public-global-encounters-events:v20201001"
        ],
        "vessels": [
            "8c7304226-6c71-edbe-0b63-c246734b3c01"
        ],
        "dateRange": {
            "from": null,
            "to": null
        },
        "encounterTypes": [
            "fishing-carrier",
            "fishing-support",
            "carrier-fishing",
            "support-fishing"
        ]
    },
    "total": 2,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": [
        {
            "id": "da55e5723374f99f91887d4f51256d5a.2",
            "type": "encounter",
            "start": "2016-07-23T00:00:00.000Z",
            "end": "2016-07-23T11:50:00.000Z",
            "position": {
                "lat": 72.0866,
                "lon": 8.0857
            },
            "regions": {
                "mpa": [],
                "eez": [],
                "rfmo": [
                  "ICCAT"
                ]
            },
            "boundingBox": [
                8.085723348900002,
                72.0865557573,
                8.085723348900002,
                72.0865557573
            ],
            "distances": {
                "startDistanceFromShoreKm": 426,
                "endDistanceFromShoreKm": 426,
                "startDistanceFromPortKm": 425.01421899999997,
                "endDistanceFromPortKm": 425.01421899999997
            },
            "vessel": {
                "id": "8c7304226-6c71-edbe-0b63-c246734b3c01",
                "flag": "CYP",
                "name": "FRIO FORWIN",
                "type": "carrier",
                "ssvid": "210631000"
            },
            "encounter": {
                "vessel": {
                    "id": "208659960-0142-40c1-339a-c816edcab44b",
                    "flag": "RUS",
                    "name": "FORPOST",
                    "type": "fishing",
                    "ssvid": "273355780"
                },
                "medianDistanceKilometers": 0.065,
                "medianSpeedKnots": 0.5,
                "type": "carrier-fishing"
            }
        }
    ]
}

GET LOITERING EVENTS


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/events?datasets=public-global-loitering-events-carriers:latest&vessels=8c7304226-6c71-edbe-0b63-c246734b3c01&limit=1&offset=0' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "datasets": [
            "public-global-loitering-events-carriers:v20201001"
        ],
        "vessels": [
            "8c7304226-6c71-edbe-0b63-c246734b3c01"
        ],
        "dateRange": {
            "from": null,
            "to": null
        },
        "encounterTypes": []
    },
    "total": 107,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": [
        {
            "id": "9991a9e4b2ee7313c33f5263308d045c",
            "type": "loitering",
            "start": "2013-06-12T11:40:09.000Z",
            "end": "2013-06-12T12:01:09.000Z",
            "position": {
                "lat": 32.2075,
                "lon": -13.9346
            },
            "regions": {
                "mpa": [],
                "eez": [
                  8363
                ],
                "rfmo": [
                  "ICCAT"
                ]
            },
            "boundingBox": [
                -13.9335216667,
                32.2104016667,
                -13.9357016667,
                32.20455
            ],
            "distances": {
                "startDistanceFromShoreKm": 239,
                "endDistanceFromShoreKm": 239,
                "startDistanceFromPortKm": 242.068016,
                "endDistanceFromPortKm": 241.65545300000002
            },
            "vessel": {
                "id": "8c7304226-6c71-edbe-0b63-c246734b3c01",
                "name": "FRIO FORWIN",
                "type": "carrier",
                "ssvid": "210631000"
            },
            "loitering": {
                "totalTimeHours": 0.35,
                "totalDistanceKm": 0.6822365329451406,
                "averageSpeedKnots": 1.0525093072279246,
                "averageDistanceFromShoreKm": 239.00000000000003
            }
        }
    ]
}

GET PORT VISITS


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/events?datasets=public-global-port-visits-c2-events:latest&vessels=914f83946-6af4-04c6-4974-44a203a87952&limit=1&offset=0' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "datasets": [
            "public-global-port-visits-c2-events:v20201001"
        ],
        "vessels": [
            "914f83946-6af4-04c6-4974-44a203a87952"
        ],
        "dateRange": {
            "from": null,
            "to": null
        },
        "encounterTypes": []
    },
    "total": 63,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": [
        {
            "id": "a7b8b2f40b75ea6bec8bc8dbcb56741e",
            "type": "port_visit",
            "start": "2014-04-15T20:09:21.000Z",
            "end": "2014-04-28T12:15:34.000Z",
            "position": {
                "lat": 42.2182,
                "lon": -8.7915
            },
            "regions": {
                "mpa": [
                    "348806",
                    "555557037",
                    "555583119",
                    "555593050"
                ],
                "eez": [
                    5693
                ],
                "rfmo": [
                    "ICCAT"
                ]
            },
            "boundingBox": [
                -8.7508320328,
                42.2291383982,
                -8.8819075644,
                42.2035438605
            ],
            "distances": {
                "startDistanceFromShoreKm": 0,
                "endDistanceFromShoreKm": 2,
                "startDistanceFromPortKm": 0,
                "endDistanceFromPortKm": 0
            },
            "vessel": {
                "id": "914f83946-6af4-04c6-4974-44a203a87952",
                "name": "IRENE",
                "ssvid": "355794000"
            },
            "port_visit": {
                "visitId": "f5fafee33631a3948c8e2042b5810cdc",
                "confidence": 3,
                "durationHrs": 304.1036111111111,
                "startAnchorage": {
                    "id": "esp-cangas",
                    "lat": 42.229138398208576,
                    "lon": -8.750832032773074,
                    "flag": "ESP",
                    "name": "CANGAS",
                    "at_dock": true,
                    "anchorage_id": "0d2f61f7",
                    "top_destination": "VIGO",
                    "distance_from_shore_km": 0
                },
                "intermediateAnchorage": {
                    "id": "esp-cangas",
                    "lat": 42.229138398208576,
                    "lon": -8.750832032773074,
                    "flag": "ESP",
                    "name": "CANGAS",
                    "at_dock": true,
                    "anchorage_id": "0d2f61f7",
                    "top_destination": "VIGO",
                    "distance_from_shore_km": 0
                },
                "endAnchorage": {
                    "id": "esp-vigo",
                    "lat": 42.20354386049306,
                    "lon": -8.881907564441319,
                    "flag": "ESP",
                    "name": "VIGO",
                    "at_dock": false,
                    "anchorage_id": "0d25f581",
                    "top_destination": "VIGO",
                    "distance_from_shore_km": 2
                }
            }
        }
    ]
}

Change the API Dataset to select the event type:

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/events

URL Parameters

Parameter Description Required Format Param Type
limit Amount of search results to return. Example: 10 True number query
offset Offset into the search results, used for pagination. It starts at 0. It is used in combination with the param “limit”, for example you send limit = 5 and you get in the response total vessels =10. So, If you send offset =0 OR you don’t send it, you will get the first 5 results (first page). Therefore, in order to get the second page, you need to send offset = 5 which is the position of the first element you want from the second page. Example: 5 True number query
sort Property used to sort using a property. The list of possible values depends on the dataset. Before the property you can use ‘+’ or ‘-’ and based on that prefix, you can decide if it will be sort ascending + (ASC) or descending - (DESC).Example: -start False Enum: ['+start', '-start', '+end', '-end'] query
datasets Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here. You can send several datasets separated by comma. Example: public-global-fishing-events:latest,public-global-encounter-events:latest True string query
vessels List of vessel ids separated by comma. You can get this information using the search endpoints Example: 8c7304226-6c71-edbe-0b63-c246734b3c01,6583c51e3-3626-5638-866a-f47c3bc7ef7c False string query
types Event types separated by comma. Possible values: port,encounter,loitering,gap,port_visit Example: fishing False string query
start-date Start date in format YYYY-MM-DD of the start date of the event (inclusive). Filter the events that their end date is greater or equal than the start date filter. Example: 2020-01-01 False string query
end-date End date in format YYYY-MM-DD of the end date of the event (exclusive). Filter the events that their start date is less than the end date filter. Example: 2020-02-01 False string query
include-regions Flag to specify if the matching with regions should be executed or not. Check our data caveats for details on how the region is matching. Default value is True. Example: True False boolean query
confidences This param applies only to port visits events, check data caveats to understand the different levels. Values go from 2 to 4, where 2 is low confidence, 3 is medium and 4 is high confidence. Values are separated by comma. Possible values: 2, 3, 4 Example: 3,4 False string query
encounter-types Possible values: carrier-fishing, fishing-carrier, fishing-support, support-fishing Example: carrier-fishing,fishing-carrier False string query

Get All Events (POST endpoint)

GET FISHING EVENTS


curl --location --request POST 'https://gateway.api.globalfishingwatch.org/v2/events?offset=0&limit=1' \
--header 'Authorization: Bearer [TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datasets": [ "public-global-fishing-events:latest"],
    "startDate": "2017-01-01",
    "endDate": "2017-01-31",
    "flags": ["CHN"],
    "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              120.36621093749999,
              26.725986812271756
            ],
            [
              122.36572265625,
              26.725986812271756
            ],
            [
              122.36572265625,
              28.323724553546015
            ],
            [
              120.36621093749999,
              28.323724553546015
            ],
            [
              120.36621093749999,
              26.725986812271756
            ]
          ]
        ]
      }

}'

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "datasets": [
            "public-global-fishing-events:v20201001"
        ],
        "dateRange": {
            "from": "2017-01-01",
            "to": "2017-01-31"
        },
        "encounterTypes": [],
        "flags": [
            "CHN"
        ],
        "geometry": {
            "type": "FeatureCollection",
            "features": [
                {
                    "type": "Feature",
                    "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                            [
                                [
                                    120.36621093749999,
                                    26.725986812271756
                                ],
                                [
                                    122.36572265625,
                                    26.725986812271756
                                ],
                                [
                                    122.36572265625,
                                    28.323724553546015
                                ],
                                [
                                    120.36621093749999,
                                    28.323724553546015
                                ],
                                [
                                    120.36621093749999,
                                    26.725986812271756
                                ]
                            ]
                        ]
                    }
                }
            ]
        }
    },
    "total": 1774,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": [
        {
            "id": "dc0e88984dd9106fe1e1d2151da6d4ec",
            "type": "fishing",
            "start": "2017-01-01T00:00:45.000Z",
            "end": "2017-01-01T00:56:45.000Z",
            "position": {
                "lat": 27.2241,
                "lon": 121.742
            },
            "regions": {
                "mpa": [],
                "eez": [
                    "8486"
                ],
                "rfmo": [
                    "WCPFC",
                    "ACAP",
                    "APFIC",
                    "IWC"
                ],
                "fao": [
                    "61"
                ],
                "major_fao": [
                    "61"
                ],
                "eez12nm": []
            },
            "boundingBox": [
                121.7405466667,
                27.1961733333,
                121.7431733333,
                27.2491533333
            ],
            "distances": {
                "startDistanceFromShoreKm": 68,
                "endDistanceFromShoreKm": 66,
                "startDistanceFromPortKm": 46.575801,
                "endDistanceFromPortKm": 41.298395
            },
            "vessel": {
                "id": "4d8d5aded-d958-b88b-4ccb-3e8542670060",
                "flag": "CHN",
                "name": "ZHERUIYU02109",
                "type": "fishing",
                "ssvid": "412431417"
            },
            "fishing": {
                "totalDistanceKm": 17.691522682956926,
                "averageSpeedKnots": 3.3749999999999996,
                "averageDurationHours": 0.3111111111111111
            }
        }
    ]
}

GET ENCOUNTER EVENTS


curl --location --request POST 'https://gateway.api.globalfishingwatch.org/v2/events?offset=0&limit=1' \
--header 'Authorization: Bearer [TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datasets": [ "public-global-encounters-events:latest"],
    "startDate": "2017-01-01",
    "endDate": "2017-01-31",
    "vessels": ["55d38c0ee-e0d7-cb32-ac9c-8b3680d213b3"],
    "flags": ["TWN"],
    "duration": 60,
    "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -130.9735107421875,
              -17.691128657307427
            ],
            [
              -130.4901123046875,
              -17.691128657307427
            ],
            [
              -130.4901123046875,
              -17.209017141391765
            ],
            [
              -130.9735107421875,
              -17.209017141391765
            ],
            [
              -130.9735107421875,
              -17.691128657307427
            ]
          ]
        ]
      }


}'

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "datasets": [
            "public-global-encounters-events:v20201001"
        ],
        "vessels": [
            "55d38c0ee-e0d7-cb32-ac9c-8b3680d213b3"
        ],
        "dateRange": {
            "from": "2017-01-01",
            "to": "2017-01-31"
        },
        "encounterTypes": [
            "fishing-carrier",
            "fishing-support",
            "carrier-fishing",
            "support-fishing"
        ],
        "flags": [
            "TWN"
        ],
        "geometry": {
            "type": "FeatureCollection",
            "features": [
                {
                    "type": "Feature",
                    "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                            [
                                [
                                    -130.9735107421875,
                                    -17.691128657307427
                                ],
                                [
                                    -130.4901123046875,
                                    -17.691128657307427
                                ],
                                [
                                    -130.4901123046875,
                                    -17.209017141391765
                                ],
                                [
                                    -130.9735107421875,
                                    -17.209017141391765
                                ],
                                [
                                    -130.9735107421875,
                                    -17.691128657307427
                                ]
                            ]
                        ]
                    }
                }
            ]
        }
    },
    "total": 1,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": [
        {
            "id": "05e5fcf80f3542a33154214f0a586f19.2",
            "type": "encounter",
            "start": "2017-01-01T00:50:00.000Z",
            "end": "2017-01-01T04:30:00.000Z",
            "position": {
                "lat": -17.4783,
                "lon": -130.7285
            },
            "regions": {
                "mpa": [],
                "eez": [],
                "rfmo": [
                    "WCPFC",
                    "SPRFMO",
                    "IWC",
                    "ACAP",
                    "IATTC"
                ],
                "fao": [
                    "77"
                ],
                "major_fao": [
                    "77"
                ],
                "eez12nm": []
            },
            "boundingBox": [
                -130.7285232872,
                -17.4782849293,
                -130.7285232872,
                -17.4782849293
            ],
            "distances": {
                "startDistanceFromShoreKm": 602,
                "endDistanceFromShoreKm": 602,
                "startDistanceFromPortKm": 760.023188,
                "endDistanceFromPortKm": 760.023188
            },
            "vessel": {
                "id": "55d38c0ee-e0d7-cb32-ac9c-8b3680d213b3",
                "flag": "TWN",
                "name": "JIN HSIANG FA",
                "type": "fishing",
                "ssvid": "416077500"
            },
            "encounter": {
                "vessel": {
                    "id": "46ae0e5f9-9304-7ac9-dc78-462d84320bf5",
                    "flag": "TWN",
                    "name": "SHUN TIAN FA 168",
                    "type": "carrier",
                    "ssvid": "416602000"
                },
                "medianDistanceKilometers": 0.016,
                "medianSpeedKnots": 1.067,
                "type": "fishing-carrier"
            }
        }
    ]
}

GET LOITERING EVENTS


curl --location --request POST 'https://gateway.api.globalfishingwatch.org/v2/events?offset=0&limit=1' \
--header 'Authorization: Bearer [TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datasets": [ "public-global-loitering-events-carriers:latest"],
    "startDate": "2017-01-01",
    "endDate": "2017-01-31",
    "vessels": ["82be6f228-8ce4-26d1-bf81-3b7979d0c72f"],
    "flags": ["KOR"],
    "duration": 60,
    "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              43.835981972515576,
              -6.785011952437713
            ],
            [
              43.83602857589722,
              -6.785011952437713
            ],
            [
              43.83602857589722,
              -6.784984652340707
            ],
            [
              43.835981972515576,
              -6.784984652340707
            ],
            [
              43.835981972515576,
              -6.785011952437713
            ]
          ]
        ]
      }
}'

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "datasets": [
            "public-global-loitering-events-carriers:v20201001"
        ],
        "vessels": [
            "82be6f228-8ce4-26d1-bf81-3b7979d0c72f"
        ],
        "dateRange": {
            "from": "2017-01-01",
            "to": "2017-01-31"
        },
        "encounterTypes": [],
        "flags": [
            "KOR"
        ],
        "geometry": {
            "type": "FeatureCollection",
            "features": [
                {
                    "type": "Feature",
                    "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                            [
                                [
                                    43.835981972515576,
                                    -6.785011952437713
                                ],
                                [
                                    43.83602857589722,
                                    -6.785011952437713
                                ],
                                [
                                    43.83602857589722,
                                    -6.784984652340707
                                ],
                                [
                                    43.835981972515576,
                                    -6.784984652340707
                                ],
                                [
                                    43.835981972515576,
                                    -6.785011952437713
                                ]
                            ]
                        ]
                    }
                }
            ]
        }
    },
    "total": 0,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": []
}

GET PORT VISITS


curl --location --request POST 'https://gateway.api.globalfishingwatch.org/v2/events?offset=0&limit=1' \
--header 'Authorization: Bearer [TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datasets": [ "public-global-port-visits-c2-events:latest"],
    "startDate": "2017-01-01",
    "endDate": "2017-01-31",
    "vessels": ["e0248aed9-99b4-bae7-6b87-ff0a3c464676"],
    "flags": ["ATG"],
    "duration": 60,
    "geometry":{
        "type": "Polygon",
        "coordinates": [
          [
            [
              30.552978515625,
              46.255846818480315
            ],
            [
              31.22314453125,
              46.255846818480315
            ],
            [
              31.22314453125,
              46.59661864884465
            ],
            [
              30.552978515625,
              46.59661864884465
            ],
            [
              30.552978515625,
              46.255846818480315
            ]
          ]
        ]
      }



}'

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "metadata": {
        "datasets": [
            "public-global-port-visits-c2-events:v20201001"
        ],
        "vessels": [
            "e0248aed9-99b4-bae7-6b87-ff0a3c464676"
        ],
        "dateRange": {
            "from": "2017-01-01",
            "to": "2017-01-31"
        },
        "encounterTypes": [],
        "flags": [
            "ATG"
        ],
        "geometry": {
            "type": "FeatureCollection",
            "features": [
                {
                    "type": "Feature",
                    "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                            [
                                [
                                    30.552978515625,
                                    46.255846818480315
                                ],
                                [
                                    31.22314453125,
                                    46.255846818480315
                                ],
                                [
                                    31.22314453125,
                                    46.59661864884465
                                ],
                                [
                                    30.552978515625,
                                    46.59661864884465
                                ],
                                [
                                    30.552978515625,
                                    46.255846818480315
                                ]
                            ]
                        ]
                    }
                }
            ]
        }
    },
    "total": 1,
    "nextOffset": 1,
    "offset": 0,
    "limit": 1,
    "entries": [
        {
            "id": "4f76e3bf40fcb9af92f6e7250154c86d",
            "type": "port_visit",
            "start": "2017-01-01T00:00:00.000Z",
            "end": "2017-01-01T09:35:02.000Z",
            "position": {
                "lat": 46.3181,
                "lon": 31.0484
            },
            "regions": {
                "mpa": [],
                "eez": [
                    "5695"
                ],
                "rfmo": [
                    "ACAP",
                    "IWC",
                    "ICCAT",
                    "GFCM"
                ],
                "fao": [
                    "37",
                    "37.4.2",
                    "37.4"
                ],
                "major_fao": [
                    "37"
                ],
                "eez12nm": []
            },
            "boundingBox": [
                31.0767735168,
                46.2917746863,
                31.0090529428,
                46.3757554864
            ],
            "distances": {
                "startDistanceFromShoreKm": 28,
                "endDistanceFromShoreKm": 20,
                "startDistanceFromPortKm": 0,
                "endDistanceFromPortKm": 0
            },
            "vessel": {
                "id": "e0248aed9-99b4-bae7-6b87-ff0a3c464676",
                "flag": "ATG",
                "name": "JORK",
                "type": "cargo",
                "ssvid": "305656000"
            },
            "port_visit": {
                "visitId": "ffe81fe2608c6de1799a701b736951ca",
                "confidence": 4,
                "durationHrs": 9.58388888888889,
                "startAnchorage": {
                    "anchorage_id": "40c652c5",
                    "at_dock": false,
                    "distance_from_shore_km": 28,
                    "flag": "UKR",
                    "id": "ukr-nikolaev",
                    "lat": 46.291774686340844,
                    "lon": 31.076773516760372,
                    "name": null,
                    "top_destination": "NIKOLAEV"
                },
                "intermediateAnchorage": {
                    "anchorage_id": "40c65295",
                    "at_dock": false,
                    "distance_from_shore_km": 26,
                    "flag": "UKR",
                    "id": "ukr-nikolaev",
                    "lat": 46.30317322627217,
                    "lon": 31.073053845170914,
                    "name": null,
                    "top_destination": "NIKOLAEV"
                },
                "endAnchorage": {
                    "anchorage_id": "40c64c1b",
                    "at_dock": false,
                    "distance_from_shore_km": 20,
                    "flag": "UKR",
                    "id": "ukr-nikolaev",
                    "lat": 46.37575548639163,
                    "lon": 31.009052942845823,
                    "name": null,
                    "top_destination": "NIKOLAEV"
                }
            }
        }
    ]
}

Change the API Dataset to select the event type:

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/events

URL Parameters

Parameter Description Required Format Param Type
limit Amount of search results to return. Example: 10 True number query
offset Offset into the search results, used for pagination. It starts at 0. It is used in combination with the param “limit”, for example you send limit = 5 and you get in the response total vessels =10. So, If you send offset =0 OR you don’t send it, you will get the first 5 results (first page). Therefore, in order to get the second page, you need to send offset = 5 which is the position of the first element you want from the second page. Example: 5 True number query
sort Property used to sort using a property. The list of possible values depends on the dataset. Before the property you can use ‘+’ or ‘-’ and based on that prefix, you can decide if it will be sort ascending + (ASC) or descending - (DESC).Example: -start False Enum: ['+start', '-start', '+end', '-end'] query

Body Parameters

Parameter Description Required Format Param Type
datasets Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here. You can send several datasets in array format. Example: ['public-global-fishing-events:latest','public-global-encounter-events:latest'] True [string] body
vessels List of vessel ids. You can get this information using the search endpoints Example: ['8c7304226-6c71-edbe-0b63-c246734b3c01','6583c51e3-3626-5638-866a-f47c3bc7ef7c'] False [string] body
types Event types. Possible values: port,encounter,loitering,gap,port_visit Example: ['fishing'] False [string] body
startDate Start date in format YYYY-MM-DD of the start date of the event (inclusive). Filter the events that their end date is greater or equal than the start date filter. Example: 2020-01-01 False string body
endDate End date in format YYYY-MM-DD of the end date of the event (exclusive). Filter the events that their start date is less than the end date filter. Example: 2020-02-01 False string body
confidences This param applies only to port visits events, check data caveats to understand the different levels. Values go from 2 to 4, where 2 is low confidence, 3 is medium and 4 is high confidence. Possible values: 2, 3, 4 Example: ['3','4'] False [string] body
encounterTypes Possible values: carrier-fishing, fishing-carrier, fishing-support, support-fishing Example: ['carrier-fishing','fishing-carrier'] False [string] body
duration Duration, in minutes, of the event. Example: 30 False number body
vesselTypes Vessel types of the vessels involved in the events. Possible values: fishing,carrier,support,passenger,other_non_fishing,seismic_vessel,bunker_or_tanker,cargo Example: ['fishing', 'carrier'] False [string] body
vesselGroups Ids of the vessel groups. Example: ['my-vessel-group'] False [string] body
flags Flags of the vessels involved in the events, in ISO3. Example: ['ESP', 'FRA'] False [string] body
geometry Region where the events occur. False object body

Get one by Event ID

GET A PORT VISIT EVENT BY ITS ID


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/events/c2f0967e061f99a01793edac065de003?datasets=public-global-port-visits-c2-events:latest' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response will be:

{
    "id": "c2f0967e061f99a01793edac065de003",
    "type": "port_visit",
    "start": "2020-01-26T05:52:47.000Z",
    "end": "2020-01-29T14:39:33.000Z",
    "position": {
        "lat": 20.8374,
        "lon": -17.0161
    },
    "regions": {
        "mpa": [],
        "eez": [
            8369
        ],
        "rfmo": [
            "ICCAT"
        ]
    },
    "boundingBox": [
        -17.0147743934,
        20.7287971969,
        -17.0301185356,
        20.8284907611
    ],
    "distances": {
        "startDistanceFromShoreKm": 7,
        "endDistanceFromShoreKm": 2,
        "startDistanceFromPortKm": 0,
        "endDistanceFromPortKm": 0
    },
    "vessel": {
        "id": "8c7304226-6c71-edbe-0b63-c246734b3c01",
        "name": "FRIO FORWIN",
        "ssvid": "210631000"
    },
    "port_visit": {
        "visitId": "54a297966f51994d8bad91ba58945f8c",
        "confidence": 4,
        "durationHrs": 80.77944444444445,
        "startAnchorage": {
            "id": "mrt-nouadhibou",
            "lat": 20.72879719687954,
            "lon": -17.014774393446658,
            "flag": "MRT",
            "name": "NOUADHIBOU",
            "at_dock": false,
            "anchorage_id": "0ea1bbe7",
            "top_destination": "NOUADHIBOU",
            "distance_from_shore_km": 7
        },
        "intermediateAnchorage": {
            "id": "mrt-nouadhibou",
            "lat": 20.885489104200627,
            "lon": -17.003218026679036,
            "flag": "MRT",
            "name": "NOUADHIBOU",
            "at_dock": false,
            "anchorage_id": "0ea1b6ad",
            "top_destination": "NOUADHIBOU",
            "distance_from_shore_km": 4
        },
        "endAnchorage": {
            "id": "mrt-nouadhibou",
            "lat": 20.828490761089796,
            "lon": -17.030118535609358,
            "flag": "MRT",
            "name": "NOUADHIBOU",
            "at_dock": true,
            "anchorage_id": "0ea1b0c3",
            "top_destination": "NOUADHIBOU",
            "distance_from_shore_km": 2
        }
    }
}

HTTP Request

GET https://gateway.api.globalfishingwatch.org/v2/events/{eventId}

URL Parameters

Parameter Description Required Format Param Type
eventId True string path
raw If true, return all content of the event without parsing False boolean query
datasets Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here. You can send several datasets separated by comma. Example: public-global-fishing-events:latest,public-global-encounter-events:latest True string query

General API Documentation

Key Concepts: API DATASET and VESSEL ID

API DATASET

API dataset is a key parameter to identify which data you are requesting.

Global Fishing Watch is harnessing innovative technology to turn transparent data into actionable information and drive tangible change in the way that our ocean is governed. Data accessed through ​​the Global Fishing Watch APIs is as accurate as possible, but should be used with the data caveats described in each dataset in mind.

API Dataset for 4Wings API Description
public-global-fishing-effort:latest AIS apparent fishing effort, check more detail about data caveats here
API Dataset for Events API Description
public-global-encounters-events:latest AIS Encounters events between carrier and fishing vessels. Check more detail about data caveats here
public-global-loitering-events-carriers:latest AIS Loitering events for carriers. Check more detail about data caveats here
public-global-fishing-events:latest AIS apparent fishing events. Check more detail about data caveats here
public-global-port-visits-c2-events:latest AIS port visits. Check more detail about data caveats here
API Dataset for Vessels API Description
public-global-fishing-vessels:latest Fishing vessels based on AIS. You can use these fields to search in the Vessels API: vessel_id, flag and geartype. Check more detail about data caveats here
public-global-carrier-vessels:latest Carriers vessels based on AIS data. You can use these fields to search in the Vessels API: id, lastTransmissionDate, firstTransmissionDate, shipname and imo.. Check more detail about data caveats here
public-global-support-vessels:latest Support vessels based on AIS. You can use these fields to search in the Vessels API: id, flag, lastTransmissionDate, firstTransmissionDate, shipname, mmsi, callsign and imo. Check more detail about data caveats here

API DATASETS SPECIFIC VERSIONS

When you are sending latest alias, you still get the detail of the specific API Dataset in the header of the response, for example:

In case you want to request an specific version of the API Dataset, this is the list of available versions:

4Wings API Description
public-global-fishing-effort:v20201001 AIS apparent fishing effort generated using GFW (Global Fishing Watch) Data Pipeline version 20201001
Events API Description
public-global-encounters-events:v20201001 AIS Encounters events generated using GFW Data Pipeline version 20201001
public-global-loitering-events-carriers:v20201001 AIS Loitering events for carriers generated using GFW Data Pipeline version 20201001
public-global-fishing-events:v20201001 AIS apparent fishing events generated using GFW Data Pipeline version 20201001
public-global-port-visits-c2-events:v20201001 AIS port visits generated using GFW Data Pipeline version 20201001
Vessels API Description
public-global-carrier-vessels:v20201001 Carriers vessels generated using GFW Data Pipeline version 20201001
public-global-support-vessels:v20201001 Support vessels generated using GFW Data Pipeline version 20201001
public-global-fishing-vessels:v20201001 Fishing vessels generated using GFW Data Pipeline version 20201001

API DATASETS VERSIONING

VESSEL ID

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) in order to identify vessels that may not consistently transmit AIS, or the same identifiers on AIS, over time.

Errors Codes

The GFW API uses the following error codes:

Range Description
2XX Successful execution
4XX Error on the client side
5XX Errors on the server side
Code Meaning
200 OKAY - The request has succeeded.
202 Accepted - The request has been accepted for processing, but the processing has not been completed.
204 No content - The server has successfully fulfilled the request and that there is no additional content to send in the response payload body.For example when you ask for an empty tile in /4wings/tile/heatmap/
401 Unauthorized - Your API Access Token is wrong or your don't have permissions to access that dataset.
403 Forbidden - The server understood the request but refuses to authorize it.
404 Not Found - The specified data could not be found.
422 Unprocessable Entity -The server understands the content type of the request entity, and the syntax of the request entity is correct but was unable to process the contained instructions. For example, this error condition may occur if a a user requests in /4wings/tile/heatmap/ a zoom greater than 12 since it is semantically erroneous, we only support up to zoom level 12.
429 Too Many Requests - The server received more request that the user can do. For example, this error condition may occur if a user tries to do several reports at the same time.
503 Service Unavailable - We're temporarily offline for maintenance. Please try again later or contact us in apis@globalfishingwatch.org

Error Code Examples

If you are asking for a wrong API dataset, you get this error:

{
    "statusCode": 404,
    "error": "Not Found",
    "messages": [
        {
            "title": "Not Found",
            "detail": "Dataset with id public-global-fishing-effort:latest not found"
        }
    ]
}

If you are missing one mandatory field, for a example 'Query', you get this error:

{
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "messages": [
        {
            "title": "Query",
            "detail": "Query param dataset is required"
        }
    ]
}

If you have insufficient permissions, you get this error:

{
    "statusCode": 403,
    "error": "Forbidden",
    "messages": [
        {
            "title": "Forbidden",
            "detail": "Insufficient permissions for public-global-fishing-effort:latest datasets"
        }
    ]
}

If you send zoom > 12 in /4wings/tile/heatmap/, you get this error:

{
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "messages": [
        {
            "title": "z",
            "detail": "The tiler does not support zoom levels greater than 12"
        }
    ]
}

If you send a report at the same time that you doing other report, you get this error:

{
    "statusCode": 429,
    "error": "Too Many Requests",
    "messages": [
        {
            "title": "Too Many Requests",
            "detail": "You can only generate one report at the same time. If you need this feature, contact us"
        }
    ]
}

If you try to generate a style url (/v2/4wings/generate-png) and it doesn't exist data for the filters.`, you get this error:

{
    "statusCode": 204
}

In 4Wings Report API, if you are sending a custom polygon that is too large, you get this error in html. In this case, we recommend sending a region id, see more details here

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>413 Request Entity Too Large</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Request Entity Too Large</h1>
<h2>Your client issued a request that was too large.
</h2>
<h2><script>
  (function() { /*

 Copyright The Closure Library Authors.
 SPDX-License-Identifier: Apache-2.0
*/
var c=function(a,d,b){a=a+"=deleted; path="+d;null!=b&&(a+="; domain="+b);document.cookie=a+"; expires=Thu, 01 Jan 1970 00:00:00 GMT"};var g=function(a){var d=e,b=location.hostname;c(d,a,null);c(d,a,b);for(var f=0;;){f=b.indexOf(".",f+1);if(0>f)break;c(d,a,b.substring(f+1))}};var h;if(4E3<unescape(encodeURI(document.cookie)).length){for(var k=document.cookie.split(";"),l=[],m=0;m<k.length;m++){var n=k[m].match(/^\s*([^=]+)/);n&&l.push(n[1])}for(var p=0;p<l.length;p++){var e=l[p];g("/");for(var q=location.pathname,r=0;;){r=q.indexOf("/",r+1);if(0>r)break;var t=q.substring(0,r);g(t);g(t+"/")}"/"!=q.charAt(q.length-1)&&(g(q),g(q+"/"))}h=!0}else h=!1;
h&&setTimeout(function(){if(history.replaceState){var a=location.href;history.replaceState(null,"","/");location.replace(a)}},1E3); })();

</script>
</h2>
</body></html>

Most error responses have this format, except when the request entity is too large (see example on the right):

{

"statusCode": 4XXX or 5XXX,

"messages": [{ "title": "[Title]", "detail": "[Detail]" }],

"error": "[Generic error]"

}

Response

Example of a single resource in Vessel API:

    {
        "callsign": "",
        "firstTransmissionDate": "2018-11-06T13:05:41Z",
        "flag": "ESP",
        "geartype": "trawlers",
        "id": "ec6fa45c2-2b0e-0c0d-a194-13d12f30b2c6",
        "imo": null,
        "lastTransmissionDate": "2022-01-03T07:01:35Z",
        "mmsi": "224334460",
        "msgCount": 26199,
        "normalizedShipname": "CARLOS",
        "posCount": 7275,
        "shipname": "CARLOS",
        "source": "AIS",
        "vesselType": "Fishing",
        "dataset": "public-global-fishing-vessels:v20201001",
    }

Example of a collection of resource in Vessel Search API:

{   
    "total": 23,
    "limit": 10,
    "offset": 0,
    "nextOffset": 10,
    "metadata": {
        "suggestion": null,
        "query": "Don Carlos"
    },
    "entries": [
        {
            "callsign": "",
            "firstTransmissionDate": "2018-11-06T13:05:41Z",
            "flag": "ESP",
            "geartype": "trawlers",
            "id": "ec6fa45c2-2b0e-0c0d-a194-13d12f30b2c6",
            "imo": null,
            "lastTransmissionDate": "2022-01-03T07:01:35Z",
            "mmsi": "224334460",
            "msgCount": 26199,
            "normalizedShipname": "CARLOS",
            "posCount": 7275,
            "shipname": "CARLOS",
            "source": "AIS",
            "vesselType": "Fishing",
            "dataset": "public-global-fishing-vessels:v20201001",
            "score": 11.524361
        },
        {...},
    ]
}

Responses varies in case of:

  1. a single resource, the API returns the result directly.

  2. a collection of resources, the API returns the next response format (except in the case that the response is not a JSON)

API Versioning

Communication around API versions

Version Version Status Deprecation Date Release Notes
v2 🟢 CURRENT Release Notes v2
v1 🔴 DEPRECATED Oct 31 2022

For API Dataset Versioning, check here

Data caveat

How are the events estimated?

The automatic identification system (AIS) data is obtained from a combination of commercial and government sources. Learn more. The data is then used to estimate vessel identity and activity, including apparent fishing,encounters, loitering events, and port visits.

Any and all references to activity events, including fishing, encounters, loitering, and port visits should be understood in the context of Global Fishing Watch's algorithms, which are best efforts to determine apparent vessel activity events based on AIS data collected via satellites and terrestrial receivers. As AIS data varies in completeness, accuracy and quality, it is possible that some events are not identified. It is also possible that some events are identified but are incorrect or do not indicate actual fishing, transshipment, or port access. For these reasons, Global Fishing Watch qualifies all designations of events, including synonyms of event terms such as "fishing effort," "fishing" or "fishing activity," as apparent rather than certain. Any/all Global Fishing Watch information about apparent events should be considered an estimate and must be relied upon solely at your own risk. Global Fishing Watch is constantly improving processes to make sure event algorithms and designations are as accurate as possible.

Encounter event

Encounters may indicate potential transshipment activity between two vessels. Encounters can occur in the vessel viewer between a carrier and fishing vessel or a fishing support vessel and a fishing vessel. AIS data is used to calculate encounters based on the distance between the two vessels, vessel speeds, and duration in a given area. An encounter is defined as a period when two vessels are detected within 500 meters of each other for at least two hours and traveling at a median speed of less than 2 knots, while at least 10 km from a coastal anchorage. Check more details here

You can read more about transshipment behavior from our report or scientific publication.

Loitering event

Loitering is when a single vessel exhibits behavior indicative of a potential encounter event. It is possible that loitering events do not indicate a potential transshipment. For example, other events in which a vessel may remain fairly stationary include maintenance or waiting outside of port for permission to dock. AIS data is used to calculate loitering events based on vessel speed and distance from shore. Loitering occurs when a carrier vessel travels at an average speed of less than 2 knots, while at least an average of 20 nautical miles from shore. Loitering events are not displayed for fishing vessels, due to the challenge in distinguishing loitering from other low speed operations related to fishing activity. Due to the individual definitions of loitering events and encounter events, it is possible for a loitering event to overlap with an encounter event, representing the same activity, or the loitering event may encompass one or more encounter events.

Check more details here

Port visit events

Movements in and out of a port are automatically detected by Global Fishing Watch and categorized according to four distinct types of events: port entry, port stop, port gap (i.e. a gap in AIS transmission while in port) and port exit. When at least two of these events occur, then a port visit is detected. Therefore, a port visit occurs when a vessel has a port entry, a port stop or port gap, and potentially followed by a port exit event, depending on the confidence of the port visit (see next question on how port visit confidence is determined). This means the vessel is within 3 km of an anchorage (port entry), and is moving between 0.5 and 0.2 knots (port stop), or is within an anchorage but has a gap in AIS transmission for at least 4 hours (port gap), and then the vessel transits more than 4 km outside of the anchorage point (port exit). Ports are based upon the Global Fishing Watch anchorages dataset, a global database of anchorage locations where vessels congregate. More information on anchorages can be found here.

Confidence levels of a port visit

Definition of each por event:

Apparent fishing events

Global Fishing Watch analyzes AIS data collected from vessels that our research has identified as known or possible commercial fishing vessels, and applies a fishing detection algorithm to determine “apparent fishing activity” based on changes in vessel speed and direction. The algorithm classifies each AIS broadcast data point for these vessels as either apparently fishing or not fishing and shows the apparent fishing effort on the Global Fishing Watch map. Fishing events use those data points as input and summarize them into one event for easier analysis. Fishing events are defined using the following restrictions:

  1. Consecutive positions identified as fishing are grouped together into a single event

  2. Fishing positions which appear consecutively, but are 10 km apart or more than 2 hours apart are separated into distinct events.

  3. Fishing events within 1 hour and 2 km of another fishing event but possibly having intermittent transit points are grouped together into a single event.

Finally, the dataset is restricted by removing fishing events that are brief and fast, as these are less likely to indicate a realistic fishing event. The following short fishing events are removed:

Check more details about difference between fishing effort and fishing events here

Vessel Types

For vessel type a research and analysis is conducted in addition to using the original AIS data to identify the most likely value. Global Fishing Watch developed a carrier database that is curated using a combination of sources, including: major RFMO vessel registry lists, publicly available national registries, the IMO number, and a convolutional neural network—machine learning algorithm—used to estimate vessel class, as well as web and search images. The fishing vessels identified from Global Fishing Watch come from its fishing database, which is collated using vessel registry databases, reported AIS identity information, and estimated classification using a machine learning algorithm. All support vessels in Vessel Viewer are considered purse seine support vessels based on internal review. Learn more about Global Fishing Watch vessel classes here.

Why am I seeing multiple outputs when I search for a vessel?

When processing AIS positions Global Fishing Watch algorithms try to match AIS position messages with AIS self-reported identity messages to assign vessel tracks throughout time to the correct vessel identity. When there is a new identity reported, Global Fishing Watch creates a new record.Often times, a new identity is reported when a vessel does have a real identity change (e.g, the vessel went to port where it changed its flag State and name). However, there are instances when the vessel simply changes the way it is transmitting on AIS. For example, a vessel will often transmit its name, IMO, MMSI, and callsign, but for a period of time it only transmits its MMSI and not the other identity values, which results in multiple identities for a single vessel.

  1. Search by Name = GABU REEFER and IMO = 8300949
  2. Vessel Viewer will return two results:
Result order Name IMO MMSI CALL SIGN AIS TRANSMISSIONS
First GABU REEFER 8300949 214182732 ER2732 Feb 22 2019 to Sept 19 2021
Second GABU REEFER 8300949 616852000 D6FJ2 Jan 02 2012 to Feb 23 2019
  1. In this example even though they are the same physical vessel, the identity reported is different.
  2. The two records show the vessel under the same IMO, however the vessel did not consistently transmit the same identity values. In the second example, the vessel was likely transmitting under a different MMSI, different call sign and possibly a different owner.

Exclusive economic zone boundaries definition

Exclusive economic zones (EEZs) extend up to 200 nautical miles from a country's coast. EEZ boundaries are shown as solid lines for “200 NM”, “Treaty”, “Median line”, “Joint regime”, “Connection Line”, “Unilateral claim (undisputed)” and dashed lines for “Joint regime”, “Unsettled”, “Unsettled median line” based on the “LINE_TYPE” field. For more detail on the methodology to create these boundaries, check https://marineregions.org/eezmethodology.php Source: marineregions.org. Flanders Marine Institute (2019). Maritime Boundaries Geodatabase: Maritime Boundaries and Exclusive Economic Zones (200NM), version 11.

Marine protected area boundaries definition

Marine protected areas (MPAs) are areas of the ocean set aside for long-term conservation. These can have different levels of protection, and the range of activities allowed or prohibited within their boundaries varies considerably. Source: World Database on Protected Areas.

What does it mean if an event is within a specific geographic area, such as an EEZ,MPA or RFMO?

An event is considered to occur within a specific geographic area if the bounding box created for the event location— based on the minimum and maximum coordinates—overlaps with the bounding box of the geographic area (the area is based on external sources specified under the Map section of the FAQ). For example, if you select Argentina EEZ and Chile EEZ under the Fishing Events activity highlights, you will see all fishing events where the bounding box created by minimum and maximum coordinates of the events occurred within the minimum and maximum coordinates of the Argentina EEZ or within the Chile EEZ. Because a bounding box method is used, it is possible the actual track coordinates do not overlap with the EEZ. Please investigate the highlighted events further on the map.

Exclusive economic zone boundaries definitions

Exclusive economic zones (EEZs) extend up to 200 nautical miles from a country's coast. For more detail on the methodology to create these boundaries, check https://marineregions.org/eezmethodology.php Source: marineregions.org. Flanders Marine Institute (2019). Maritime Boundaries Geodatabase: Maritime Boundaries and Exclusive Economic Zones (200NM), version 11.

Marine protected area boundaries definition

Marine protected areas (MPAs) are areas of the ocean set aside for long-term conservation. These can have different levels of protection, and the range of activities allowed or prohibited within their boundaries varies considerably. Source: World Database on Protected Areas. Last updated: May 2021.

Reference Data

GEAR TYPES SUPPORTED

You can use the following list to filter fishing effort or other data by gear type. For more details, check our data caveats here.

REGIONS

GET LIST OF EEZs


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/datasets/public-eez-areas/user-context-layers' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response returns:

[
  {
          "id": 5670,
          "iso3": "ALB",
          "label": "Albanian Exclusive Economic Zone"
      },
      {
          "id": 8378,
          "iso3": "DZA",
          "label": "Algerian Exclusive Economic Zone"
      },
      {
             "id": 5690,
             "iso3": "RUS",
             "label": "Russian Exclusive economic Zone"
         },
    {
      ...
    },
]

GET LIST OF MPAs


curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v2/datasets/public-mpa-all/user-context-layers' \
  -H "Authorization: Bearer [TOKEN]"

Make sure to replace [TOKEN] with your API Access Token. If the request is successful, the response returns:

[
    {
        "id": "555512344",
        "label": "100_Daeseom"
    },
    {
        "id": "555512376",
        "label": "101_Hogamseom"
    },
    {
        "id": "555512360",
        "label": "102_Galmaeseom"
    },
    {
        ...
    },
]

There are two endpoints that uses regions ids:

In order to get the details of those regions, call the endpoints described on the right.

You can check the source we use for those regions in our data caveats.

SDK

gfwR

Global Fishing Watch enables the research community to access data from its application programming interfaces, or APIs, directly through R—a specialized programming language for data processing, statistical analysis and data visualizations. The package, called gfwr, allows R users to request data from Global Fishing Watch’s APIs and receive data in a tidy format suitable for incorporation into new or existing R workflows.

Installing gfwr gives academics, researchers, students and journalists the ability to easily pull data for analysis without any prior API experience.

To learn more about gfwR: Github gfwR official page

License and Rate Limits

Terms of Use

GLOBAL FISHING WATCH
1025 CONNECTICUT AVE., NW, STE. 200
WASHINGTON, DC 20036-5425

Welcome to the Global Fishing Watch ("GFW", "We", "Our", "Us”) suite of Application Program Interfaces (APIs). These Terms of Use let the user of these Services ("You", "Your") know what You get when You use Our APIs to access our websites, and what We expect in return.

The services available through Global Fishing Watch, including all data products and associated services, (collectively referred to as the “Services”), are owned and operated by Global Fishing Watch, Inc. By using the Services, You agree to be bound by these Terms of Use and any future updates (collectively, the "Terms").

1. USAGE

We provide You with access to these Services in order to promote better management of the ocean for the betterment of all people.

A. Please don’t misuse Our Services. You agree to use the Services and their contents only for lawful purposes and not to defame, harass or threaten any one or to make available any defamatory, infringing, obscene, pornographic, offensive or illegal material. You may not use the Services in any manner that could damage or overburden the Services or interfere with any other person’s use of the Services.

B. Your use of the Services does not give You any ownership rights in the intellectual property in the Services or in its contents. Some of the software used to provide the Services may be made available separately under open-source licenses.

C. Noncommercial Use Only. The Services are available for noncommercial use only in accordance with the CC BY-NC 4.0 license, including complying with the attribution requirements set forth in Section 3 below. You are welcome to use the Services provided that Your application and its use are not intended (primarily or materially) for or directed towards commercial advantage or monetary compensation. In this context, We ask that users not exceed 50,000 DAILY API requests per day and 1,550,000 per month. Users who exceed this volume may be asked to reduce usage or may receive diminished service levels. GFW reserves the right to revoke Your usage rights at any time for any reason, including if We determine that Your application or use is not consistent with such restrictions on commercial use.

D. We will continue to regularly add to, modify, and otherwise improve Our Services. By using the Services, You acknowledge that We may change the features and functions of the Services, including APIs, over time. It is Your responsibility to ensure that Your use of the Services is compatible with the current version. We ask that you also reasonably cooperate with us from time to time in providing feedback on your Use of the APIs, your purposes and the impact created, which will help us advance our noncommercial goals for the APIs.

2. ACCOUNTS AND API USAGE

A. In order to use many of the Services, You must register for an account. GFW reserves the right to reject any account registration request, in its sole discretion.

B. By requesting to open an account with the Global Fishing Watch Services, You represent and warrant to us, as of the time of your request and on a continuing basis for the duration of Your use of the Services, that: (1) You are applying on behalf of an organization or entity that supports the sustainable use of ocean resources; (2) You are authorized to act on behalf of such organization or entity; (3) the application is sent from a valid email from the organization or entity; and (4) no other application or registration for this organization or entity exists. GFW may request additional information in order to confirm these conditions are met.

C. When You use Our application program interfaces (“API(s)”), each request to an API must include one of Your Account's unique API keys.

D. Please protect the security of Your Account. When accessing or using the API, you must comply with all of our security policies and procedures at all times. You are responsible for Your use of the Services and all activity that occurs under Your Account, including any use of Your Account’s API keys.

E. You may not, and may not attempt to, reverse-engineer, decompile, disassemble, or otherwise attempt to determine or modify the source code of our API or create any derivative products from the API. Anyone who uses the API to access Account data or to perform actions on the service must authenticate with an API key.

F. You agree that your login credentials and any other required forms of authentication, where applicable, have been chosen by you, when applicable. You also agree to keep your login credentials and any other required forms of authentication, including your API keys, confidential and separate from each other, as well as separate from any other information or documents relating to your use of the service.

G. The GFW API Token is specific to You and is Your responsibility. Your token is not to be shared or published with any additional users. You may only use the API token issued to you, and your Use of any token other than the one issued to You is a violation of these Terms. You may not include Your token in a publicly available web interface such that it can be discovered by other parties using Your website and/or application. You may not permit or authorize any other person or entity to use the API token issued to you.

H. We may cancel or suspend Your access to the Services at any time and for any reason, without notice. Upon cancellation or suspension, Your right to use the Services will end. You will have the right to access to Your Content stored on the Services for a period of fifteen days following cancellation or suspension; thereafter You may not have access to Your Content stored on the Services.

I. You agree to participate in follow-up surveys and report how the APIs are used, the number of users and other benefits they provide the end-stakeholder.

3. ATTRIBUTION AND CITATION

A. In connection with any use you make of Our APIs, you agree that you will attribute Us as the source of the data in compliance with our Attribution Requirements, which are as follows:

A.1. Websites or embedded graphics. If You use Our APIs in a Website, data visualization or graphic, You must include either of the following:

 
“Powered by Global Fishing Watch.” and link this text to https://globalfishingwatch.org on web pages or visuals that make use of the Global Fishing Watch API(s).

OR

 
“Global Fishing Watch. [2022 or current year in the Global Fishing Watch copyright notice on the home page], updated daily. [API dataset name and version], [DATE RANGE]. Data set accessed YYYY-MM-DD at https://globalfishingwatch.org/our-apis/.”

A.2. Bibliography. If You include the use of Our API(s) in a bibliography or use the entire Site as a source, use the following citation format:

 
“Copyright [2022 or current year in the Global Fishing Watch copyright notice on the home page], Global Fishing Watch, Inc., ​https://globalfishingwatch.org​/our-apis/.”

A.3. Other products or use. If You made any other use of Our API(s), use the following citation format:

 
“Powered by Global Fishing Watch.” and link this text to https://globalfishingwatch.org on other products or use-cases that make use of the Global Fishing Watch API(s).

OR

 
“Global Fishing Watch. [2022 or current year in the Global Fishing Watch copyright notice on the home page], updated daily. [API dataset name and version], [DATE RANGE]. Data set accessed YYYY-MM-DD at https://globalfishingwatch.org/our-apis/.”

B. You also agree to ensure that Our Attribution Requirements are communicated and maintained by any partners or downstream users of Our Services. Aside from the Attribution Requirements, neither You nor any partners or downstream users of Our Services shall use the GFW name, logos, trademarks or other marks without GFW’s prior written consent.

4. THIRD-PARTY CONTENT

A. The Services incorporate content, data, and information from others, including You. While We may review any content, and remove it if We determine it violates the law or Our policies, We do not commit to review all content, and You should not rely on Us to do so.

B. Open data is important to Us and We make considerable effort to make many of the datasets available without restriction through the Services. Nonetheless, each dataset carries its own license and restrictions. You should review the dataset’s metadata to understand these restrictions.

C. You must comply with the licenses of Our datasets. All content displayed on or accessible through the Services is protected by United States copyright laws or their equivalents in other countries.

5. YOUR CONTENT

A. Most of Our Services are designed to help You share or publish Your content. In using Global Fishing Watch service, You may submit data, information, or other content to the Services (“Your Content”). You retain ownership of Your Content.

B. Except where expressly prohibited, You understand that We may use, display, or distribute Your Content even if You stop using the Services. For the sole purpose of enabling Your use of the Services, You grant Us a non-exclusive, worldwide, royalty-free, transferable right and license (with right to sublicense), to use, copy, display, distribute, modify, create derivative works, and store Your Content and to allow others to do so.

6. DISCLAIMERS AND LIMITATIONS

A. YOU AGREE THAT YOUR USE OF THE SERVICES AND ITS CONTENT IS AT YOUR SOLE RISK. THE SERVICES AND CONTENT ARE PROVIDED ON AN “AS IS” BASIS AND WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. TO THE FULLEST EXTENT PERMITTED BY LAW, WE DISCLAIM ALL WARRANTIES, STATUTORY, EXPRESS OR IMPLIED, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. ACTUAL CONDITIONS MAY DIFFER FROM INFORMATION PROVIDED BY THE SERVICES. WE DO NOT WARRANT THAT THE CONTENT OR SERVICES WILL BE ERROR FREE, ACCURATE OR WITHOUT INTERRUPTION.

B. WHEN USING THE SERVICES YOU MAY BE EXPOSED TO USER SUBMISSIONS AND OTHER THIRD PARTY CONTENT ("NON-GFW CONTENT"), AND SOME OF THIS CONTENT MAY BE INACCURATE, OFFENSIVE, INDECENT, OR OTHERWISE OBJECTIONABLE. WE DO NOT ENDORSE ANY NON-GFW CONTENT. UNDER NO CIRCUMSTANCES WILL GFW BE LIABLE FOR OR IN CONNECTION WITH THE NON-GFW CONTENT, INCLUDING FOR ANY INACCURACIES, ERRORS, OR OMISSIONS IN ANY NON-GFW CONTENT, ANY INTELLECTUAL PROPERTY INFRINGEMENT WITH REGARD TO ANY NON-GFWCONTENT, OR FOR ANY LOSS OR DAMAGE OF ANY KIND INCURRED AS A RESULT OF THE USE OF ANY NON-GFW CONTENT.

C. UNDER NO CIRCUMSTANCES WILL WE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES (INCLUDING WITHOUT LIMITATION, LOSS OF PROFITS, DATA, OR USE OR COST OF COVER) RESULTING FROM YOUR USE OR THE INABILITY TO USE THE SERVICES OR THEIR CONTENTS, EVEN IF WE WERE AWARE OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU FOR CLAIMS OR DAMAGES FOR ANY REASON IN EXCESS OF ONE HUNDRED DOLLARS ($100 USD) IN AGGREGATE FOR ALL CLAIMS OR DAMAGES. CERTAIN JURISDICTIONS DO NOT ALLOW EXCLUSIONS OR LIMITATIONS ON IMPLIED WARRANTIES OR LIMITATIONS ON LIABILITY, AND THEREFORE SOME OR ALL OF THE DISCLAIMERS, EXCLUSIONS, OR LIMITATIONS MAY NOT APPLY TO YOU, AND YOU MAY HAVE ADDITIONAL RIGHTS.

7. DMCA COMPLIANCE

If You are a copyright owner or an agent thereof, and believe that any content on the Services infringes Your copyrights, You may send a notice in writing to Global Fishing Watch E-mail: support@globalfishingwatch.org with the following information:

A. Your signature as a person authorized to act on behalf of the owner of an exclusive right that is allegedly infringed;

B. Identification of the exact location on the Services of copyrighted work claimed to have been infringed, or, if multiple copyrighted works on the Services are covered by a single notification, a representative list of such works as located on the Services;

C. The address, telephone number, and e-mail address of the complaining party;

D. A statement that the complaining party has a good faith belief that use of the material in the manner complained of is not authorized by the copyright owner, its agent, or the law; and

E. A statement that the information in the notification is accurate, and under penalty of perjury, that the complaining party is authorized to act on behalf of the owner of an exclusive right that is allegedly infringed.

8. ADDITIONAL TERMS

A. We reserve the right to modify these Terms at any time. All changes are effective immediately upon posting on the Global Fishing Watch website. You should review these terms regularly for changes. Your continued use of the Services after any such changes constitutes Your binding acceptance of the updated Terms.

B. The laws of the District of Columbia, United States of America, excluding its conflict of laws provisions, apply to any dispute about the Services, their content or these Terms. The U.N. Convention on Contracts for the International Sale of Goods doesn't apply. If we have a disagreement related to these Terms, or Your or Our performance under them that we cannot resolve between us, then we agree to have them finally resolved in arbitration using either (i) the International Arbitration Rules of the International Dispute Resolution Centre of the American Arbitration Association, if You are located outside of the United States, in any case with one arbitrator, or (ii) the Commercial Arbitration Rules of the American Arbitration Association, if You are located in the United States. We agree to follow this paragraph if it differs from those rules. We agree that the arbitrator will not have the power to award either of us any damages that are not consistent with Section 6 (Disclaimers and Limitations) of these Terms. The arbitration will be in Washington, DC, USA, and will be conducted in English. Unless we agree or one of us shows its essential, there will not be any formal discovery in our arbitration. The arbitrators can award costs and attorney’s fees against one of us, or divide them between us. We understand that any court with jurisdiction will enforce the decisions from the arbitration and enter judgment on them.

C. You agree to indemnify, hold harmless and at your expense defend Us, Our affiliates, and Our and their respective officers, managers, and employees (“Indemnified Persons”) from and against any and all losses, claims, demands, and expenses (including reasonable attorney’s fees of counsel selected by Us) arising in connection with any (a) of Your or Your affiliates’ (i) breach of these Terms, including any representation, warranty or covenant contained herein, or (ii) willful misconduct or negligence. For the avoidance of doubt, the indemnification set forth in this Section is in addition to, and not in place of, those set forth in any terms of use or user agreement for the Service.

D. If We do not promptly enforce the Terms, We have not given up any other rights or the right to enforce them or other Terms in the future.

E. If any particular provision of these Terms is not enforceable, that doesn't affect the enforceability of any other provision of the Terms.

F. These Terms are between You and Us, and no one else can enforce them.

G. These Terms are the entire statement of the agreement between You and Us regarding the Services and their contents.

Rate Limits

Our APIs are intended for non-commercial use. In this context, we ask that users not exceed 50,000 DAILY API requests per day and 1,550,000 per month. Users which exceed this volume may be asked to reduce usage or may receive diminished service levels.

API Token

The GFW API Token is specific to you and is your responsibility. Your token is not to be shared or published with any additional users. Use of any token other than the one issue to you is a violation of these term. You may not include your token in a publicly available web interface such that it can be discovered by other parties using your website and/or application

API Release Notes

Check more detail on how our API versioning process here.

V2 - 2022 November 11

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

V2 - 2022 October 19

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

V2 - 2022 September 28

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)

V2 - 2022 July 26

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

V1 - 2021 Jan 01

Initial alpha release.