gfwapiclient.resources.events.resources

Global Fishing Watch (GFW) API Python Client - Events API Resource.

Module Contents

Classes

EventResource

Resource for interacting with the Events API.

Data

__all__

API

gfwapiclient.resources.events.resources.__all__ = ['EventResource']

class gfwapiclient.resources.events.resources.EventResource(*, http_client: gfwapiclient.http.client.HTTPClient)

Bases: gfwapiclient.http.resources.BaseResource

Resource for interacting with the Events API.

This resource provides methods for retrieving event data, including lists of events, individual events by ID, and event statistics.

Initialization

Initialize a new BaseResource.

Args:

http_client (HTTPClient):

The HTTP client to send requests.

async get_all_events(*, datasets: Union[List[gfwapiclient.resources.events.base.models.request.EventDataset], List[str]], vessels: Optional[List[str]] = None, types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventType], List[str]]] = None, start_date: Optional[Union[datetime.date, str]] = None, end_date: Optional[Union[datetime.date, str]] = None, confidences: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventConfidence], List[str]]] = None, encounter_types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventEncounterType], List[str]]] = None, duration: Optional[int] = None, vessel_types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventVesselType], List[str]]] = None, vessel_groups: Optional[List[str]] = None, flags: Optional[List[str]] = None, geometry: Optional[Union[gfwapiclient.resources.events.base.models.request.EventGeometry, Dict[str, Any]]] = None, region: Optional[Union[gfwapiclient.resources.events.base.models.request.EventRegion, Dict[str, Any]]] = None, gap_intentional_disabling: Optional[bool] = None, limit: Optional[int] = None, offset: Optional[int] = None, sort: Optional[str] = None, **kwargs: Dict[str, Any]) → gfwapiclient.resources.events.list.models.response.EventListResult

Get All Events.

Retrieves a list of events based on specified criteria.

Args:

datasets (Union[List[EventDataset], List[str]]):

Datasets to search for events. Allowed values: [“public-global-encounters-events:latest”, “public-global-fishing-events:latest”, “public-global-gaps-events:latest”, “public-global-loitering-events:latest”, “public-global-port-visits-events:latest”]. Example: [“public-global-fishing-events:latest”, “public-global-encounters-events:latest”].

vessels (Optional[List[str]]):

List of vessel IDs to filter events. Example: [“55d38c0ee-e0d7-cb32-ac9c-8b3680d213b3”].

types (Optional[Union[List[EventType], List[str]]]):

List of event types to filter events. Allowed values: [“ENCOUNTER”, “PORT_VISIT”, “FISHING”, “CARRIER_OPERATIONS”, “LOITERING”]. Example: [“FISHING”, “ENCOUNTER”].

start_date (Optional[Union[datetime.date, str]]):

Start date for event filtering. Format: YYYY-MM-DD. Example: “2017-01-01”.

end_date (Optional[Union[datetime.date, str]]):

End date for event filtering. Format: YYYY-MM-DD. Example: “2017-01-31”.

confidences (Optional[Union[List[EventConfidence], List[str]]]):

List of event confidence levels to filter events. Allowed values: [“2”, “3”, “4”]. Example: [“3”, “4”].

encounter_types (Optional[Union[List[EventEncounterType], List[str]]]):

List of encounter types to filter events. Allowed values: [“CARRIER-FISHING”, “FISHING-CARRIER”, “FISHING-SUPPORT”, “SUPPORT-FISHING”, “FISHING-BUNKER”, “BUNKER-FISHING”, “FISHING-FISHING”, “FISHING-TANKER”, “TANKER-FISHING”, “CARRIER-BUNKER”, “BUNKER-CARRIER”, “SUPPORT-BUNKER”, “BUNKER-SUPPORT”]. Example: [“CARRIER-FISHING”, “FISHING-CARRIER”].

duration (Optional[int]):

Duration to filter events (in minutes). Example: 60.

vessel_types (Optional[Union[List[EventVesselType], List[str]]]):

List of vessel types to filter events. Allowed values: [“BUNKER”, “CARGO”, “DISCREPANCY”, “CARRIER”, “FISHING”, “GEAR”, “OTHER”, “PASSENGER”, “SEISMIC_VESSEL”, “SUPPORT”]. Example: [“FISHING”, “CARGO”].

vessel_groups (Optional[List[str]]):

List of vessel groups to filter events. Example: [“my-vessel-group”].

flags (Optional[List[str]]):

List of vessel flags to filter events. Example: [“USA”, “CAN”].

geometry (Optional[Union[EventGeometry, Dict[str, Any]]]):

Geometry to filter events. Example: {“type”: “Polygon”, “coordinates”: […]}.

region (Optional[Union[EventRegion, Dict[str, Any]]]):

Region to filter events. Example: {“dataset”: “public-eez-areas”, “id”: “5690”}.

gap_intentional_disabling (Optional[bool]):

Filter events based on intentional disabling of gap.

limit (Optional[int]):

Maximum number of events to return. Default: 99999. Example: 100.

offset (Optional[int]):

Number of events to skip before returning results. Default: 0. Example: 100.

sort (Optional[str]):

Property to sort the events by. Example: “-start”.

**kwargs (Dict[str, Any]):

Additional keyword arguments.

Returns:

EventListResult:

The result containing the list of events.

Raises:

GFWAPIClientError:

If the API request fails.

RequestParamsValidationError:

If the request parameters are invalid.

RequestBodyValidationError:

If the request body is invalid.

async get_event_by_id(*, id: str, dataset: Union[gfwapiclient.resources.events.base.models.request.EventDataset, str], **kwargs: Dict[str, Any]) → gfwapiclient.resources.events.detail.models.response.EventDetailResult

Get one by Event ID.

Retrieves a single event by its ID.

Args:

id (str):

The ID of the event to retrieve. Example: “3ca9b73aee21fbf278a636709e0f8f03”.

dataset (Union[EventDataset, str]):

The dataset to search for the event in. Allowed values: [“public-global-encounters-events:latest”, “public-global-fishing-events:latest”, “public-global-gaps-events:latest”, “public-global-loitering-events:latest”, “public-global-port-visits-events:latest”]. Example: “public-global-fishing-events:latest”.

**kwargs (Dict[str, Any]):

Additional keyword arguments.

Returns:

EventDetailResult:

The result containing the event details.

Raises:

GFWAPIClientError:

If the API request fails.

RequestParamsValidationError:

If the request parameters are invalid.

async get_events_stats(*, datasets: Union[List[gfwapiclient.resources.events.base.models.request.EventDataset], List[str]], timeseries_interval: Union[gfwapiclient.resources.events.stats.models.request.EventStatsTimeSeriesInterval, str], vessels: Optional[List[str]] = None, types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventType], List[str]]] = None, start_date: Optional[Union[datetime.date, str]] = None, end_date: Optional[Union[datetime.date, str]] = None, confidences: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventConfidence], List[str]]] = None, encounter_types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventEncounterType], List[str]]] = None, duration: Optional[int] = None, vessel_types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventVesselType], List[str]]] = None, vessel_groups: Optional[List[str]] = None, flags: Optional[List[str]] = None, geometry: Optional[Union[gfwapiclient.resources.events.base.models.request.EventGeometry, Dict[str, Any]]] = None, region: Optional[Union[gfwapiclient.resources.events.base.models.request.EventRegion, Dict[str, Any]]] = None, gap_intentional_disabling: Optional[bool] = None, includes: Optional[Union[List[gfwapiclient.resources.events.stats.models.request.EventStatsInclude], List[str]]] = None, **kwargs: Dict[str, Any]) → gfwapiclient.resources.events.stats.models.response.EventStatsResult

Get events statistics worldwide or for a specific region.

Args:

datasets (Union[List[EventDataset], List[str]]):

Datasets to search for statistics. Allowed values: [“public-global-encounters-events:latest”, “public-global-fishing-events:latest”, “public-global-gaps-events:latest”, “public-global-loitering-events:latest”, “public-global-port-visits-events:latest”]. Example: [“public-global-fishing-events:latest”, “public-global-encounters-events:latest”].

timeseries_interval (Union[EventStatsTimeSeriesInterval, str]):

Time series granularity for statistics. Allowed values: [“HOUR”, “DAY”, “MONTH”, “YEAR”]. Example: “DAY”.

vessels (Optional[List[str]]):

List of vessel IDs to filter statistics. Example: [“55d38c0ee-e0d7-cb32-ac9c-8b3680d213b3”].

types (Optional[Union[List[EventType], List[str]]]):

List of event types to filter statistics. Allowed values: [“ENCOUNTER”, “PORT_VISIT”, “FISHING”, “CARRIER_OPERATIONS”, “LOITERING”]. Example: [“FISHING”, “ENCOUNTER”].

start_date (Optional[Union[datetime.date, str]]):

Start date for event filtering. Format: YYYY-MM-DD. Example: “2023-01-31”.

end_date (Optional[Union[datetime.date, str]]):

End date for event filtering. Format: YYYY-MM-DD. Example: “2023-12-31”.

confidences (Optional[Union[List[EventConfidence], List[str]]]):

List of event confidence levels to filter statistics. Allowed values: [“2”, “3”, “4”]. Example: [“3”, “4”].

encounter_types (Optional[Union[List[EventEncounterType], List[str]]]):

List of encounter types to filter statistics. Allowed values: [“CARRIER-FISHING”, “FISHING-CARRIER”, “FISHING-SUPPORT”, “SUPPORT-FISHING”, “FISHING-BUNKER”, “BUNKER-FISHING”, “FISHING-FISHING”, “FISHING-TANKER”, “TANKER-FISHING”, “CARRIER-BUNKER”, “BUNKER-CARRIER”, “SUPPORT-BUNKER”, “BUNKER-SUPPORT”]. Example: [“CARRIER-FISHING”, “FISHING-CARRIER”].

duration (Optional[int]):

Duration to filter statistics (in minutes). Example: 60.

vessel_types (Optional[Union[List[EventVesselType], List[str]]]):

List of vessel types to filter statistics. Allowed values: [“BUNKER”, “CARGO”, “DISCREPANCY”, “CARRIER”, “FISHING”, “GEAR”, “OTHER”, “PASSENGER”, “SEISMIC_VESSEL”, “SUPPORT”]. Example: [“FISHING”, “CARGO”].

vessel_groups (Optional[List[str]]):

List of vessel groups to filter statistics. Example: [“my-vessel-group”].

flags (Optional[List[str]]):

List of vessel flags to filter statistics. Example: [“USA”, “CAN”].

geometry (Optional[Union[EventGeometry, Dict[str, Any]]]):

Geometry to filter statistics. Example: {“type”: “Polygon”, “coordinates”: […]}.

region (Optional[Union[EventRegion, Dict[str, Any]]]):

Region to filter statistics. Example: {“dataset”: “public-eez-areas”, “id”: “5690”}.

gap_intentional_disabling (Optional[bool]):

Filter statistics based on intentional disabling of gap.

includes (Optional[Union[List[EventStatsInclude], List[str]]]):

List of additional information to include in the statistics. Allowed values: [“TOTAL_COUNT”, “TIME_SERIES”]. Example: [“TOTAL_COUNT”, “TIME_SERIES”].

**kwargs (Dict[str, Any]):

Additional keyword arguments.

Returns:

EventStatsResult:

The result containing the event statistics.

Raises:

GFWAPIClientError:

If the API request fails.

RequestBodyValidationError:

If the request body is invalid.

_prepare_get_all_events_request_params(*, limit: Optional[int] = None, offset: Optional[int] = None, sort: Optional[str] = None) → gfwapiclient.resources.events.list.models.request.EventListParams

Prepares and returns the request parameters for the get all events endpoint.

_prepare_get_all_events_request_body(*, datasets: Union[List[gfwapiclient.resources.events.base.models.request.EventDataset], List[str]], vessels: Optional[List[str]] = None, types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventType], List[str]]] = None, start_date: Optional[Union[datetime.date, str]] = None, end_date: Optional[Union[datetime.date, str]] = None, confidences: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventConfidence], List[str]]] = None, encounter_types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventEncounterType], List[str]]] = None, duration: Optional[int] = None, vessel_types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventVesselType], List[str]]] = None, vessel_groups: Optional[List[str]] = None, flags: Optional[List[str]] = None, geometry: Optional[Union[gfwapiclient.resources.events.base.models.request.EventGeometry, Dict[str, Any]]] = None, region: Optional[Union[gfwapiclient.resources.events.base.models.request.EventRegion, Dict[str, Any]]] = None, gap_intentional_disabling: Optional[bool] = None) → gfwapiclient.resources.events.list.models.request.EventListBody

Prepares and returns the request body for the get all events endpoint.

_prepare_get_event_by_id_request_params(*, dataset: Union[gfwapiclient.resources.events.base.models.request.EventDataset, str]) → gfwapiclient.resources.events.detail.models.request.EventDetailParams

Prepares and returns the request parameters for the get event by ID endpoint.

_prepare_get_events_stats_request_body(*, datasets: Union[List[gfwapiclient.resources.events.base.models.request.EventDataset], List[str]], timeseries_interval: Union[gfwapiclient.resources.events.stats.models.request.EventStatsTimeSeriesInterval, str], vessels: Optional[List[str]] = None, types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventType], List[str]]] = None, start_date: Optional[Union[datetime.date, str]] = None, end_date: Optional[Union[datetime.date, str]] = None, confidences: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventConfidence], List[str]]] = None, encounter_types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventEncounterType], List[str]]] = None, duration: Optional[int] = None, vessel_types: Optional[Union[List[gfwapiclient.resources.events.base.models.request.EventVesselType], List[str]]] = None, vessel_groups: Optional[List[str]] = None, flags: Optional[List[str]] = None, geometry: Optional[Union[gfwapiclient.resources.events.base.models.request.EventGeometry, Dict[str, Any]]] = None, region: Optional[Union[gfwapiclient.resources.events.base.models.request.EventRegion, Dict[str, Any]]] = None, gap_intentional_disabling: Optional[bool] = None, includes: Optional[Union[List[gfwapiclient.resources.events.stats.models.request.EventStatsInclude], List[str]]] = None) → gfwapiclient.resources.events.stats.models.request.EventStatsBody

Prepares and returns the request body for the get events statistics endpoint.