# Vessels API (/docs/v3/vessels)



### Introduction Vessels API [#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 <a href="https://globalfishingwatch.org/data-download/datasets/public-vessel-identity:v20230118" target="_blank">here</a> which was used in the recently published <a href="https://www.science.org/doi/10.1126/sciadv.abp8200" target="_blank">paper</a> Tracking elusive and shifting identities of the global fishing fleet by Park et al. (2023).

Search results are paginated. See [Pagination](/docs/v3/general-api-doc/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](/docs/v3/general-api-doc/reference-data#vessel-api---registry-codes---data-sources)
* Get identity details based on AIS self reported data or public registries. Check more detail about data caveats [here](/docs/v3/general-api-doc/data-caveats).

<Callout type="info" title="Learning how APIs are used in Global Fishing Watch Vessel Viewer">
  If you want to learn which APIs are used in{' '}

  <a href="https://globalfishingwatch.org/map/fishing-activity/default-public/vessel-search?longitude=26&latitude=19&zoom=1.49" target="_blank">
    {' '}

    Vessel Viewer
  </a>

  , you can review{' '}

  <a external="true" href="/our-apis/documentation/assets/2024_Vessel_Viewer_and_APIs_behind_It.pdf" target="_blank">
    this document showing the exact API requests done behind each page
  </a>

  .
</Callout>

### Search [#search]

#### Search vessels [#search-vessels]

<OpenAPIPage document="apiv3" operations="[{ path: '/api/v3/vessels/search', method: 'get' }]" hasHead="false" />

#### Examples [#examples]

* [EXAMPLE 1](/docs/examples/vessels/vessels-example1) - Basic search - search any vessel by a keyword
* [EXAMPLE 2](/docs/examples/vessels/vessels-example2) - Advanced search - search any vessel by a keyword

### Get list of vessels filtered by ids [#get-list-of-vessels-filtered-by-ids]

#### Get vessels by ids [#get-vessels-by-ids]

<OpenAPIPage document="apiv3" operations="[{ path: '/api/v3/vessels', method: 'get' }]" hasHead="false" />

> GET DETAILS OF TWO FISHING VESSELS AND ONE CARRIER

<Tabs items="['cURL', 'Python', 'R', 'JavaScript']">
  <Tab value="cURL">
    ```shell
    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]"
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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",
        ],
    )
    ```
  </Tab>

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

  <Tab value="JavaScript">
    ```js
    // Make sure to replace [TOKEN] with your API Access Token.
    const res = await fetch(
      'https://gateway.api.globalfishingwatch.org/v3/vessels?datasets[0]=public-global-vessel-identity: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()
    ```
  </Tab>
</Tabs>

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

```json
{
  "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](#search), 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 [#get-vessel-by-id]

#### Get vessel by id [#get-vessel-by-id-1]

<OpenAPIPage document="apiv3" operations="[{ path: '/api/v3/vessels/{vesselId}', method: 'get' }]" hasHead="false" />

> GET DETAILS OF ONE VESSEL

<Tabs items="['cURL', 'Python', 'R', 'JavaScript']">
  <Tab value="cURL">
    ```shell
    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]"
    ```
  </Tab>

  <Tab value="Python">
    ```python
    result = await gfw_client.vessels.get_vessel_by_id(
        id="c54923e64-46f3-9338-9dcb-ff09724077a3",
        dataset="public-global-vessel-identity:latest",
    )
    ```
  </Tab>

  <Tab value="R">
    ```r
    gfw_vessel_info(search_type = "id",
                    ids = c("c54923e64-46f3-9338-9dcb-ff09724077a3"))
    ```
  </Tab>

  <Tab value="JavaScript">
    ```js
    // 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()
    ```
  </Tab>
</Tabs>

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

```json
{
  "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](#search) , 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**.