Vessels API

Search vessels and retrieve identity details, combining GFW AIS identity data with over 40 public regional and national registries.

Introduction Vessels API

Vessels API allows you to search for vessels and get vessel identity details. This API combines Global Fishing Watch (GFW) core AIS identity data with GFW registry database to enable an improved understanding of vessel identity over time. The GFW registry database includes vessel identity information from over 40 public regional and national registries and a static version was released on our Data Download Portal here which was used in the recently published paper Tracking elusive and shifting identities of the global fishing fleet by Park et al. (2023).

Search results are paginated. See Pagination for how limit, offset, and nextOffset work.

You can:

Search for AIS and across over 40 public international, regional and national vessel registries. Check list of sources in the reference data section
Get identity details based on AIS self reported data or public registries. Check more detail about data caveats here.

Learning how APIs are used in Global Fishing Watch Vessel Viewer

If you want to learn which APIs are used in

Vessel Viewer

, you can review

this document showing the exact API requests done behind each page

Search

Search vessels

Authorization

ApiKeyAuth

AuthorizationBearer <token>

In: header

Query Parameters

since?string

The token to send to get more results.

limit?number

Amount of search results to return. Maximum 50. Default: 30

datasets*array<string>

Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here.

query?string

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. This property and where are incompatible together, you just can use one at once. Minimum 3 characters.

where?string

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 operator is not supported yet. This property and query are incompatible together, you just can use one at once.

match-fields?array<string>

This query param allows to filter by matchFields levels. Possible values: ID_MATCH_ONLY, SEVERAL_FIELDS, NO_MATCH, ALL. It is allow to use with query query-param but not with where query-param

includes?array<string>

This query param allows to add extra information to the response. Possible values: MATCH_CRITERIA, OWNERSHIP, AUTHORIZATIONS

binary?boolean

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

curl -X GET "https://example.com/api/v3/vessels/search?datasets=public-global-fishing-vessels%3Alatest&datasets=public-global-carrier-vessels%3Alatest"

{  "entries": [    {      "combinedSourcesInfo": [        {          "geartypes": [            {              "name": "OTHER",              "source": "GFW_OTHER_LIST",              "yearFrom": "2012",              "yearTo": "2023"            },            {              "name": "GEAR",              "source": "GFW_FISHING_LIST",              "yearFrom": "2013",              "yearTo": "2023"            }          ],          "inferredVesselClassAgNnet": [            {              "source": "AIS_INFERRED_NN_INFO",              "value": "TUNA_PURSE_SEINES",              "yearFrom": 2012,              "yearTo": 2025            }          ],          "onFishingListSr": [            {              "source": "GFW_VESSEL_LIST",              "value": true,              "yearFrom": 2012,              "yearTo": 2025            }          ],          "prodGeartypeSource": [            {              "source": "COMBINATION_OF_REGISTRY_AND_AIS_INFERRED_NN_INFO",              "value": "GFW_RESEARCH_VI_SSVID_BEST_VESSEL_CLASS",              "yearFrom": 2012,              "yearTo": 2025            }          ],          "registryVesselClass": [            {              "source": "REGISTRY",              "value": "OTHER_FISHING|PURSE_SEINES",              "yearFrom": 2012,              "yearTo": 2025            }          ],          "shiptypes": [            {              "name": "OTHER",              "source": "GFW_OTHER_LIST",              "yearFrom": "2012",              "yearTo": "2023"            },            {              "name": "FISHING",              "source": "GFW_FISHING_LIST",              "yearFrom": "2013",              "yearTo": "2023"            }          ],          "vesselId": "SINAR LAUTAN ABADI"        }      ],      "dataset": "proto-global-vessel-identity:latest",      "matchCriteria": [        {          "latestVesselInfo": true,          "matches": [            {              "property": "shipname",              "value": "STERNHAI"            }          ],          "period": {            "endDate": "2023-01-01"          },          "property": "selfReportedInfo.id",          "reference": "3023ab41b367d8f2d62d2a60c67c711f",          "source": "selfReportedInfo.id"        }      ],      "registryExtraFields": [        {}      ],      "registryInfo": [        {          "callsign": "Y4EO",          "extraFields": [            {}          ],          "flag": "DEU",          "geartypes": [            "trawlers"          ],          "id": "9e075a986-6162-fe6e-b25e-81188438a00c",          "imo": null,          "latestVesselInfo": true,          "lengthM": 26.4,          "nShipname": "STERNHAI",          "shipname": "STERNHAI",          "ssvid": "211307720",          "tonnageGt": 121,          "transmissionDateFrom": "2012-05-25 15:16:29 UTC",          "transmissionDateTo": "2014-06-30 08:51:05 UTC",          "vesselInfoReference": "3023ab41b367d8f2d62d2a60c67c711f"        }      ],      "registryInfoTotalRecords": 3,      "registryOwners": [        {          "dateFrom": "2014-06-30T00:00:00Z",          "dateTo": "2015-09-30T00:00:00Z",          "flag": "IDN",          "name": "SINAR LAUTAN ABADI",          "sourceCode": "IDN-1104",          "ssvid": "211307720"        }      ],      "registryPublicAuthorizations": [        {          "dateFrom": "2012-05-25T00:00:00Z",          "dateTo": "2014-06-30T00:00:00Z",          "sourceCode": "IDN-1104",          "ssvid": "211307720"        }      ],      "selfReportedInfo": [        {          "callsign": "Y4EO",          "flag": "DEU",          "id": "9e075a986-6162-fe6e-b25e-81188438a00c",          "imo": null,          "messagesCounter": 1284,          "nShipname": "STERNHAI",          "positionsCounter": 894,          "shipname": "STERNHAI",          "sourceCode": [            "AIS"          ],          "ssvid": "211307720",          "transmissionDateFrom": "2012-05-25 15:16:29 UTC",          "transmissionDateTo": "2014-06-30 08:51:05 UTC"        }      ]    }  ],  "limit": 10,  "metadata": {    "didYouMean": {      "shipname": [        {          "dataset": "public-global-vessel-identity:latest",          "metadata": {            "id": "d66d9e47a-a652-6009-ab1c-30549b4a59a1",            "nShipname": "DONTITO",            "shipname": "DON TITO"          },          "value": "DON TITO"        }      ]    },    "normalizedQuery": "DONTITO",    "query": "Don Tito"  },  "since": "MTAuNzQ1MDM5LjllMDc1YTk4Ni02MTYyLWZlNmUtYjI1ZS04MTE4ODQzOGEwMGM=",  "total": 152}

Examples

EXAMPLE 1 - Basic search - search any vessel by a keyword
EXAMPLE 2 - Advanced search - search any vessel by a keyword

Get list of vessels filtered by ids

Get vessels by ids

Authorization

ApiKeyAuth

AuthorizationBearer <token>

In: header

Query Parameters

registries-info-data?string

The response doesn't include all registry info data by default. It means, the default value is NONE. You can use DELTA to get only the data that changes in the time or ALL to get all data from the registries

Value in

"NONE"
"DELTA"
"ALL"

includes?array<string>

This query param allows to add extra information to the response. Possible values: POTENTIAL_RELATED_SELF_REPORTED_INFO

binary?boolean

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

match-fields?array<string>

This query param allows to filter by matchFields levels. Possible values: ID_MATCH_ONLY, SEVERAL_FIELDS, NO_MATCH, ALL. It is allow to use with query query-param but not with where query-param

datasets*array<string>

Specify the datasets that will be used to search the vessel. You can learn more about which are the possible datasets here.

ids*array<string>

List of vessel ids. You can get this information using the search endpoints

vessel-groups?array<string>

List of vessel-groups.

curl -X GET "https://example.com/api/v3/vessels?datasets=public-global-fishing-vessels%3Alatest&datasets=public-global-carrier-vessels%3Alatest&ids=6583c51e3-3626-5638-866a-f47c3bc7ef7c"

{  "entries": [    {      "combinedSourcesInfo": [        {          "geartypes": [            {              "name": "OTHER",              "source": "GFW_OTHER_LIST",              "yearFrom": "2012",              "yearTo": "2023"            },            {              "name": "GEAR",              "source": "GFW_FISHING_LIST",              "yearFrom": "2013",              "yearTo": "2023"            }          ],          "inferredVesselClassAgNnet": [            {              "source": "AIS_INFERRED_NN_INFO",              "value": "TUNA_PURSE_SEINES",              "yearFrom": 2012,              "yearTo": 2025            }          ],          "onFishingListSr": [            {              "source": "GFW_VESSEL_LIST",              "value": true,              "yearFrom": 2012,              "yearTo": 2025            }          ],          "prodGeartypeSource": [            {              "source": "COMBINATION_OF_REGISTRY_AND_AIS_INFERRED_NN_INFO",              "value": "GFW_RESEARCH_VI_SSVID_BEST_VESSEL_CLASS",              "yearFrom": 2012,              "yearTo": 2025            }          ],          "registryVesselClass": [            {              "source": "REGISTRY",              "value": "OTHER_FISHING|PURSE_SEINES",              "yearFrom": 2012,              "yearTo": 2025            }          ],          "shiptypes": [            {              "name": "OTHER",              "source": "GFW_OTHER_LIST",              "yearFrom": "2012",              "yearTo": "2023"            },            {              "name": "FISHING",              "source": "GFW_FISHING_LIST",              "yearFrom": "2013",              "yearTo": "2023"            }          ],          "vesselId": "SINAR LAUTAN ABADI"        }      ],      "dataset": "proto-global-vessel-identity:latest",      "registryExtraFields": [        {}      ],      "registryInfo": [        {          "callsign": "Y4EO",          "extraFields": [            {}          ],          "flag": "DEU",          "geartypes": [            "trawlers"          ],          "id": "9e075a986-6162-fe6e-b25e-81188438a00c",          "imo": null,          "latestVesselInfo": true,          "lengthM": 26.4,          "nShipname": "STERNHAI",          "shipname": "STERNHAI",          "ssvid": "211307720",          "tonnageGt": 121,          "transmissionDateFrom": "2012-05-25 15:16:29 UTC",          "transmissionDateTo": "2014-06-30 08:51:05 UTC",          "vesselInfoReference": "3023ab41b367d8f2d62d2a60c67c711f"        }      ],      "registryInfoTotalRecords": 3,      "registryOwners": [        {          "dateFrom": "2014-06-30T00:00:00Z",          "dateTo": "2015-09-30T00:00:00Z",          "flag": "IDN",          "name": "SINAR LAUTAN ABADI",          "sourceCode": "IDN-1104",          "ssvid": "211307720"        }      ],      "registryPublicAuthorizations": [        {          "dateFrom": "2012-05-25T00:00:00Z",          "dateTo": "2014-06-30T00:00:00Z",          "sourceCode": "IDN-1104",          "ssvid": "211307720"        }      ],      "selfReportedInfo": {        "callsign": "Y4EO",        "flag": "DEU",        "id": "9e075a986-6162-fe6e-b25e-81188438a00c",        "imo": null,        "messagesCounter": 1284,        "nShipname": "STERNHAI",        "positionsCounter": 894,        "shipname": "STERNHAI",        "sourceCode": [          "AIS"        ],        "ssvid": "211307720",        "transmissionDateFrom": "2012-05-25 15:16:29 UTC",        "transmissionDateTo": "2014-06-30 08:51:05 UTC"      }    }  ],  "limit": 10,  "metadata": {    "idsFound": [      "a10dbd01f-fdb5-ff1f-519d-d41847d1eb81",      "fc6275631-1a5a-4621-b290-7dee86905c1e"    ],    "idsNotFound": []  },  "since": "MTAuNzQ1MDM5LjllMDc1YTk4Ni02MTYyLWZlNmUtYjI1ZS04MTE4ODQzOGEwMGM=",  "total": 152}

GET DETAILS OF TWO FISHING VESSELS AND ONE CARRIER

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

result = await gfw_client.vessels.get_vessels_by_ids(
    ids=[
        "8c7304226-6c71-edbe-0b63-c246734b3c01",
        "6583c51e3-3626-5638-866a-f47c3bc7ef7c",
        "71e7da672-2451-17da-b239-857831602eca",
    ],
)

gfw_vessel_info(search_type = "id",
                ids = c("8c7304226-6c71-edbe-0b63-c246734b3c01",
                        "6583c51e3-3626-5638-866a-f47c3bc7ef7c",
                        "71e7da672-2451-17da-b239-857831602eca"))

// Make sure to replace [TOKEN] with your API Access Token.
const res = await fetch(
  'https://gateway.api.globalfishingwatch.org/v3/vessels?datasets[0]=public-global-vessel-identity:latest&ids[0]=8c7304226-6c71-edbe-0b63-c246734b3c01&ids[1]=6583c51e3-3626-5638-866a-f47c3bc7ef7c&ids[2]=71e7da672-2451-17da-b239-857831602eca',
  { headers: { Authorization: 'Bearer [TOKEN]' } }
)
const data = await res.json()

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

{
  "limit": null,
  "since": null,
  "total": 1,
  "metadata": {
    "idsFound": ["c54923e64-46f3-9338-9dcb-ff09724077a3"],
    "idsNotFound": [
      "73f5e35b6-6b92-0b9a-f8f4-cc7b29ef6c72",
      "16c4ef8cc-c2bb-c587-7126-843ee54274ce",
      "e486710c3-3baa-8532-4ddf-e6665e99d5a4",
      "91666fdf5-5b79-3645-64da-8d199b76cd7e",
      "8837304ea-ace9-a723-50cc-be1eb5797362"
    ]
  },
  "entries": [
    {
      "dataset": "public-global-vessel-identity:v20230623",
      "registryInfoTotalRecords": 0,
      "registryInfo": [],
      "registryOwners": [],
      "registryAuthorizations": [],
      "selfReportedInfo": [
        {
          "id": "c54923e64-46f3-9338-9dcb-ff09724077a3",
          "ssvid": "775998121",
          "shipname": "DON TITO",
          "nShipname": "DONTITO",
          "flag": "VEN",
          "callsign": "YD23136",
          "imo": null,
          "geartype": null,
          "shiptype": "OTHER_NON_FISHING",
          "messagesCounter": 1103,
          "positionsCounter": 430,
          "shiptypesByYear": [
            {
              "shiptype": "OTHER_NON_FISHING",
              "years": [2021, 2022, 2023]
            }
          ],
          "sourceCode": ["AIS"],
          "matchFields": "NO_MATCH",
          "transmissionDateFrom": "2021-08-06T10:49:26Z",
          "transmissionDateTo": "2023-09-21T14:52:16Z"
        }
      ]
    }
  ]
}

After you perform a Basic, you get the vessel id, for example c54923e64-46f3-9338-9dcb-ff09724077a3. You can use this endpoint to get the details of a list of specific vessel ids.

Get vessel by id

Authorization

ApiKeyAuth

AuthorizationBearer <token>

In: header

Path Parameters

vesselId*string

Query Parameters

registries-info-data?string

Value in

"NONE"
"DELTA"
"ALL"

includes?array<string>

This query param allows to add extra information to the response. Possible values: POTENTIAL_RELATED_SELF_REPORTED_INFO

binary?boolean

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

match-fields?array<string>

This query param allows to filter by matchFields levels. Possible values: ID_MATCH_ONLY, SEVERAL_FIELDS, NO_MATCH, ALL. It is allow to use with query query-param but not with where query-param

dataset*string

Specify the dataset that will be used to search the vessel. You can learn more about which are the possible datasets here.

curl -X GET "https://example.com/api/v3/vessels/string?dataset=public-global-fishing-vessels%3Alatest"

{  "combinedSourcesInfo": [    {      "geartypes": [        {          "name": "OTHER",          "source": "GFW_OTHER_LIST",          "yearFrom": "2012",          "yearTo": "2023"        },        {          "name": "GEAR",          "source": "GFW_FISHING_LIST",          "yearFrom": "2013",          "yearTo": "2023"        }      ],      "inferredVesselClassAgNnet": [        {          "source": "AIS_INFERRED_NN_INFO",          "value": "TUNA_PURSE_SEINES",          "yearFrom": 2012,          "yearTo": 2025        }      ],      "onFishingListSr": [        {          "source": "GFW_VESSEL_LIST",          "value": true,          "yearFrom": 2012,          "yearTo": 2025        }      ],      "prodGeartypeSource": [        {          "source": "COMBINATION_OF_REGISTRY_AND_AIS_INFERRED_NN_INFO",          "value": "GFW_RESEARCH_VI_SSVID_BEST_VESSEL_CLASS",          "yearFrom": 2012,          "yearTo": 2025        }      ],      "registryVesselClass": [        {          "source": "REGISTRY",          "value": "OTHER_FISHING|PURSE_SEINES",          "yearFrom": 2012,          "yearTo": 2025        }      ],      "shiptypes": [        {          "name": "OTHER",          "source": "GFW_OTHER_LIST",          "yearFrom": "2012",          "yearTo": "2023"        },        {          "name": "FISHING",          "source": "GFW_FISHING_LIST",          "yearFrom": "2013",          "yearTo": "2023"        }      ],      "vesselId": "SINAR LAUTAN ABADI"    }  ],  "dataset": "proto-global-vessel-identity:latest",  "registryExtraFields": [    {}  ],  "registryInfo": [    {      "callsign": "Y4EO",      "extraFields": [        {}      ],      "flag": "DEU",      "geartypes": [        "trawlers"      ],      "id": "9e075a986-6162-fe6e-b25e-81188438a00c",      "imo": null,      "latestVesselInfo": true,      "lengthM": 26.4,      "nShipname": "STERNHAI",      "shipname": "STERNHAI",      "ssvid": "211307720",      "tonnageGt": 121,      "transmissionDateFrom": "2012-05-25 15:16:29 UTC",      "transmissionDateTo": "2014-06-30 08:51:05 UTC",      "vesselInfoReference": "3023ab41b367d8f2d62d2a60c67c711f"    }  ],  "registryInfoTotalRecords": 3,  "registryOwners": [    {      "dateFrom": "2014-06-30T00:00:00Z",      "dateTo": "2015-09-30T00:00:00Z",      "flag": "IDN",      "name": "SINAR LAUTAN ABADI",      "sourceCode": "IDN-1104",      "ssvid": "211307720"    }  ],  "registryPublicAuthorizations": [    {      "dateFrom": "2012-05-25T00:00:00Z",      "dateTo": "2014-06-30T00:00:00Z",      "sourceCode": "IDN-1104",      "ssvid": "211307720"    }  ],  "selfReportedInfo": {    "callsign": "Y4EO",    "flag": "DEU",    "id": "9e075a986-6162-fe6e-b25e-81188438a00c",    "imo": null,    "messagesCounter": 1284,    "nShipname": "STERNHAI",    "positionsCounter": 894,    "shipname": "STERNHAI",    "sourceCode": [      "AIS"    ],    "ssvid": "211307720",    "transmissionDateFrom": "2012-05-25 15:16:29 UTC",    "transmissionDateTo": "2014-06-30 08:51:05 UTC"  }}

GET DETAILS OF ONE VESSEL

curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v3/vessels/c54923e64-46f3-9338-9dcb-ff09724077a3?dataset=public-global-vessel-identity:latest' \
  -H "Authorization: Bearer [TOKEN]"

result = await gfw_client.vessels.get_vessel_by_id(
    id="c54923e64-46f3-9338-9dcb-ff09724077a3",
    dataset="public-global-vessel-identity:latest",
)

gfw_vessel_info(search_type = "id",
                ids = c("c54923e64-46f3-9338-9dcb-ff09724077a3"))

// Make sure to replace [TOKEN] with your API Access Token.
const res = await fetch(
  'https://gateway.api.globalfishingwatch.org/v3/vessels/c54923e64-46f3-9338-9dcb-ff09724077a3?dataset=public-global-vessel-identity:latest',
  { headers: { Authorization: 'Bearer [TOKEN]' } }
)
const data = await res.json()

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

{
  "dataset": "public-global-vessel-identity:v20230623",
  "registryInfoTotalRecords": 0,
  "registryInfo": [],
  "registryOwners": [],
  "registryAuthorizations": [],
  "selfReportedInfo": [
    {
      "id": "c54923e64-46f3-9338-9dcb-ff09724077a3",
      "ssvid": "775998121",
      "shipname": "DON TITO",
      "nShipname": "DONTITO",
      "flag": "VEN",
      "callsign": "YD23136",
      "imo": null,
      "geartype": null,
      "shiptype": "OTHER_NON_FISHING",
      "messagesCounter": 1103,
      "positionsCounter": 430,
      "shiptypesByYear": [
        {
          "shiptype": "OTHER_NON_FISHING",
          "years": [2021, 2022, 2023]
        }
      ],
      "sourceCode": ["AIS"],
      "matchFields": "NO_MATCH",
      "transmissionDateFrom": "2021-08-06T10:49:26Z",
      "transmissionDateTo": "2023-09-21T14:52:16Z"
    }
  ]
}

After you perform a Basic , you get the vessel id, for example c54923e64-46f3-9338-9dcb-ff09724077a3. You can use this endpoint to get the details of ONE vessel id.

On this page