# Events API (/docs/v3/events) ### Introduction Events API [#introduction-events-api] Events API allows you to explore different activities of a vessel. You can analyze: * apparent fishing events * encounters between these vessel types: fishing-carrier, fishing-support, fishing-bunker, fishing-fishing, tanker-fishing, carrier-bunker and support-banker. * In this API Portal we are offering more encounter types compared to our Public Map * loitering for all vessel types * port visits for all vessel types * AIS off (aka GAPs) for all vessel types Check more detail about data caveats [here](/docs/v3/general-api-doc/data-caveats). Event responses are paginated. See [Pagination](/docs/v3/general-api-doc/pagination) for how `limit`, `offset`, and `nextOffset` work. **REMINDER!** Change the **API Dataset** to select the event type: * For fishing events, use `public-global-fishing-events:latest` * For encounters events, use `public-global-encounters-events:latest` * For loitering events, use `public-global-loitering-events:latest` * For port visits, use `public-global-port-visits-events:latest` * For AIS off event, use `public-global-gaps-events:latest` ### Get All Events (GET endpoint) [#get-all-events-get-endpoint] We recommend use the GET endpoint if you are using the API from a Web APP because you can take advantage of the Browser cache to improve the load speed #### Events GET [#events-get] #### Events GET examples [#events-get-examples] These examples are available: 1. [**Example 1 (GET)**](/docs/examples/events/get-example1) - Get Fishing Events 2. [**Example 2 (GET)**](/docs/examples/events/get-example2) - Get Encounter Events 3. [**Example 3 (GET)**](/docs/examples/events/get-example3) - Get Loitering Events 4. [**Example 4 (GET)**](/docs/examples/events/get-example4) - Get Port Visits ### Get All Events (POST endpoint) [#get-all-events-post-endpoint] #### Events POST [#events-post] #### Events POST examples [#events-post-examples] These examples are available: 1. [**Example 1 (POST)**](/docs/examples/events/post-example1) - Get Fishing Events 2. [**Example 2 (POST)**](/docs/examples/events/post-example2) - Get Encounter Events 3. [**Example 3 (POST)**](/docs/examples/events/post-example3) - Get Loitering Events 4. [**Example 4 (POST)**](/docs/examples/events/post-example4) - Get Port Visits 5. [**Example 5 (POST)**](/docs/examples/events/post-example5) - Get Fishing Events Within Senegal EEZ ### Get one by Event ID [#get-one-by-event-id] #### Get by event id [#get-by-event-id] > GET A PORT VISIT EVENT BY ITS ID ```shell curl --location --request GET 'https://gateway.api.globalfishingwatch.org/v3/events/c2f0967e061f99a01793edac065de003?dataset=public-global-port-visits-events:latest' \ -H "Authorization: Bearer [TOKEN]" ``` ```python result = await gfw_client.events.get_event_by_id( id="c2f0967e061f99a01793edac065de003", dataset="public-global-port-visits-events:latest", ) ``` ```js // Make sure to replace [TOKEN] with your API Access Token. const res = await fetch( 'https://gateway.api.globalfishingwatch.org/v3/events/c2f0967e061f99a01793edac065de003?dataset=public-global-port-visits-events: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: ```json { "start": "2020-01-26T05:52:47.000Z", "end": "2020-01-29T14:39:33.000Z", "id": "c2f0967e061f99a01793edac065de003", "type": "port_visit", "position": { "lat": 20.8374, "lon": -17.0161 }, "regions": { "mpa": [], "eez": ["8369"], "rfmo": ["IWC", "NAMMCO", "ACAP", "ICCAT", "SRFC"], "fao": ["34.1", "34.1.32", "34.1.3", "34"], "majorFao": ["34"], "eez12Nm": [], "highSeas": [], "mpaNoTakePartial": [], "mpaNoTake": [] }, "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": "FRIOFORWIN", "ssvid": "210631000" }, "port_visit": { "visitId": "54a297966f51994d8bad91ba58945f8c", "confidence": 4, "durationHrs": 80.77944444444445, "startAnchorage": { "anchorageId": "0ea1bbe7", "atDock": false, "distanceFromShoreKm": 7, "flag": "MRT", "id": "mrt-cansado", "lat": 20.72879719687954, "lon": -17.014774393446658, "name": "CANSADO", "topDestination": "NOUADHIBOU" }, "intermediateAnchorage": { "anchorageId": "0ea1b6ad", "atDock": false, "distanceFromShoreKm": 4, "flag": "MRT", "id": "mrt-nouadhibou", "lat": 20.885489104200627, "lon": -17.003218026679036, "name": "NOUADHIBOU", "topDestination": "NOUADHIBOU" }, "endAnchorage": { "anchorageId": "0ea1b0c3", "atDock": true, "distanceFromShoreKm": 2, "flag": "MRT", "id": "mrt-cansado", "lat": 20.828490761089796, "lon": -17.030118535609358, "name": "CANSADO", "topDestination": "NOUADHIBOU" } } } ``` ### Statistics on events (POST) [#statistics-on-events-post] Get events statistics worldwide or for a specific region. The available events to get stats are: * Fishing events * Encounter events * Loitering events * AIS Off events (aka GAPs) * Port visits #### Events Stats POST [#events-stats-post] \| 500 | Internal Server Error \| Server side issue. Please contact us at [apis@globalfishingwatch.org](mailto:apis@globalfishingwatch.org) | [Error Codes](/docs/v3/general-api-doc/errors) | #### Properties Events Stats Response [#properties-events-stats-response] | Name | Type | Required | Restrictions | Description | | ---------- | ---------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------- | | flags | \[string] | true | none | Distinct flags | | numEvents | number | true | none | Number of events | | numFlags | number | true | none | Number of distinct vessel flags | | numVessels | number | true | none | Number of distinct vessels | | timeseries | \[[See Timeseries definition below](#properties-events-stats-response-timeseries)] | true | none | Timeseries | ##### Properties Events Stats Response Timeseries [#properties-events-stats-response-timeseries] | Name | Type | Required | Restrictions | Description | | ----- | ----------------- | -------- | ------------ | ---------------- | | date | string(date-time) | true | none | Date | | value | number | true | none | Number of events | #### Events Stats POST examples [#events-stats-post-examples] These examples are available: 1. [**Example 1 (POST)**](/docs/examples/events/stats-example1) - Get Encounters Stats 2. [**Example 2 (POST)**](/docs/examples/events/stats-example2) - Get Fishing Events Stats in a Custom Region 3. [**Example 3 (POST)**](/docs/examples/events/stats-example3) - Get Port Visits Stats in a Region ID (Senegal)