--- title: "Vessel events (fishing, encounters, port visits, loitering)" method: GET path: "/api/v1/gfw/events" tags: ["Environment"] --- # Vessel events (fishing, encounters, port visits, loitering) `GET /api/v1/gfw/events` Vessel activity events detected from AIS data. Types: fishing (apparent fishing activity), encounter (vessel-to-vessel meetings - potential transshipment), loitering (vessels stationary at sea), port_visit (arrivals and departures). Each event has position, duration, distances from shore/port, and EEZ/MPA/RFMO region data. Max date range: 366 days. ## Query parameters - `vessel_id` string — GFW vessel ID (optional - omit for global events). - `type` string — Event type: fishing, encounter, loitering, port_visit. - `start_date` string — Start date (YYYY-MM-DD). Default: 90 days ago. - `end_date` string — End date (YYYY-MM-DD). Default: today. - `limit` integer — Max results. ## Response `200` Vessel activity event records with positions, durations and region tags. - EnvelopeGfwEventsData - `data` GfwEventsData, required - `event_type` string, nullable — Event type classifier. - `count` union — Number of items in this result set. - integer - number - `total` union — Total count or sum. - integer - number - `date_range` DateRange - `start` string, nullable — Start date (YYYY-MM-DD). - `end` string, nullable — End of the data range or time window. - `events` GfwEvent[], nullable — Array of event records. - `id` string, nullable — Record identifier. - `type` string, nullable — Record type. - `start` string, nullable — Start of the data range or pagination cursor. - `end` string, nullable — End of the data range or time window. - `lat` union — Latitude in decimal degrees. - integer - number - `lon` union — Longitude in decimal degrees. - integer - number - `vessel` Vessel - `id` string, nullable — Record identifier. - `name` string, nullable — Entity or record name. - `ssvid` string, nullable - `flag` string, nullable — Flag value. - `type` string, nullable — Record type. - `publicAuthorizations` PublicAuthorization[], nullable - `hasPubliclyListedAuthorization` string, nullable - `rfmo` string, nullable - `nextPort` unknown - `regions` GfwRegions - `mpa` unknown[], nullable - unknown - `eez` string[], nullable - `rfmo` string[], nullable - `fao` string[], nullable - `majorFao` string[], nullable - `eez12Nm` string[], nullable - `highSeas` string[], nullable - `mpaNoTakePartial` unknown[], nullable - unknown - `mpaNoTake` unknown[], nullable - unknown - `distances` Distances - `startDistanceFromShoreKm` union - integer - number - `endDistanceFromShoreKm` union - integer - number - `startDistanceFromPortKm` union - integer - number - `endDistanceFromPortKm` union - integer - number - `detail` GfwDetail - `totalDistanceKm` union - integer - number - `averageSpeedKnots` union - integer - number - `averageDurationHours` unknown - `potentialRisk` boolean, nullable - `vesselPublicAuthorizationStatus` string, nullable - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope. - `endpoint` string, required — Requested endpoint path. - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request. - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced. - `provider` string, required — API name and version. - `source` string, nullable — Identifier of the primary upstream source used for this response. - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response. - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data. - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried. - `cached` boolean, nullable — True when this response was served from the internal cache. - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data. ## Other responses - `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401. - `422` — Validation Error - `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window. - `503` — Upstream source is temporarily unavailable. Retry after a short delay. ## Changes - **2026-08-28** `560e8847c7b3` — 12 breaking, 1 info - the response property `data/count` became optional for the status `200` - the response property `data/date_range` became optional for the status `200` - the response property `data/event_type` became optional for the status `200` - the response property `data/events` became optional for the status `200` - …9 more - **2026-08-08** `4c4530760ba1` — 12 info - added the optional property `code` to the response with the `401` status - added the optional property `code` to the response with the `429` status - added the optional property `code` to the response with the `503` status - added the optional property `hint` to the response with the `401` status - …8 more [Change history](https://skmtc.dev/sugra/apis/sugra-api/changes/api/v1/gfw/events/get.md) --- [API](https://skmtc.dev/sugra/apis/sugra-api.md) · [All operations](https://skmtc.dev/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sugra/sugra-api/revisions/87582f2e0110/schema)