gfwapiclient.resources.vessels.resources

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

This module defines the resource for interacting with the Vessels API, providing methods to retrieve vessel information.

Module Contents

Classes

VesselResource

Vessels data API resource.

Data

__all__

API

gfwapiclient.resources.vessels.resources.__all__ = ['VesselResource']

class gfwapiclient.resources.vessels.resources.VesselResource(*, http_client: gfwapiclient.http.client.HTTPClient)

Bases: gfwapiclient.http.resources.BaseResource

Vessels data API resource.

This resource provides methods to interact with the Vessels API, allowing retrieval of vessel information including search, list by IDs, and retrieval by ID.

Initialization

Initialize a new BaseResource.

Args:

http_client (HTTPClient):

The HTTP client to send requests.

async search_vessels(*, since: Optional[str] = None, limit: Optional[int] = 20, datasets: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselDataset], List[str]]] = None, query: Optional[str] = None, where: Optional[str] = None, match_fields: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselMatchField], List[str]]] = None, includes: Optional[Union[List[gfwapiclient.resources.vessels.search.models.request.VesselSearchInclude], List[str]]] = None, **kwargs: Dict[str, Any]) → gfwapiclient.resources.vessels.search.models.response.VesselSearchResult

Search vessels based on provided parameters.

Args:

since (Optional[str], default=None):

The token to send to get more results. Defaults to None.

limit (Optional[int], default=20):

Amount of search results to return. Defaults to 20. Maximum 50. Example: 20.

datasets (Optional[Union[List[VesselDataset], List[str]]], default=[“public-global-vessel-identity:latest”]):

Specify the datasets that will be used to search the vessel. Defaults to [“public-global-vessel-identity:latest”]. Allowed values: “public-global-vessel-identity:latest”. Example: [“public-global-vessel-identity:latest”].

query (Optional[str], default=None):

Free form query that allows you to search a vessel by sending some identifier, for example: MMSI, IMO, CALL SIGN, Shipname, etc. Minimum 3 characters. Defaults to None. Example: “Don tito”.

where (Optional[str], default=None):

Advanced query that allows you to search a vessel by sending several identifiers. Defaults to None. Example: “(shipname = ‘SEIN PHOENIX’ OR mmsi = ‘441618000’) AND flag = ‘KOR’”

match_fields (Optional[Union[List[VesselMatchField], List[str]]], default=None):

This query param allows to filter by matchFields levels. Defaults to None. Allowed values: “SEVERAL_FIELDS”, “NO_MATCH”, “ALL”. Example: [“ALL”].

includes (Optional[Union[List[VesselSearchInclude], List[str]]], default=[“OWNERSHIP”, “AUTHORIZATIONS”, “MATCH_CRITERIA”]):

This query param allows to add extra information to the response. Defaults to [“OWNERSHIP”, “AUTHORIZATIONS”, “MATCH_CRITERIA”]. Allowed values: “OWNERSHIP”, “AUTHORIZATIONS”, “MATCH_CRITERIA”. Example: [“OWNERSHIP”, “AUTHORIZATIONS”].

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

Additional keyword arguments.

Returns:

VesselSearchResult:

The search results.

Raises:

GFWAPIClientError:

If the API request fails.

RequestParamsValidationError:

If the request parameters are invalid.

async get_vessels_by_ids(*, ids: List[str], datasets: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselDataset], List[str]]] = None, registries_info_data: Optional[gfwapiclient.resources.vessels.base.models.request.VesselRegistryInfoData] = None, includes: Optional[List[gfwapiclient.resources.vessels.base.models.request.VesselInclude]] = None, match_fields: Optional[List[gfwapiclient.resources.vessels.base.models.request.VesselMatchField]] = None, vessel_groups: Optional[List[str]] = None, **kwargs: Dict[str, Any]) → gfwapiclient.resources.vessels.list.models.response.VesselListResult

Get a list of vessels by their IDs.

Args:

ids (List[str]):

List of vessel IDs to retrieve. Example: [“6583c51e3-3626-5638-866a-f47c3bc7ef7c”].

datasets (Optional[Union[List[VesselDataset], List[str]]], default=[“public-global-vessel-identity:latest”]):

Specify the datasets that will be used to search the vessel. Defaults to [“public-global-vessel-identity:latest”]. Allowed values: “public-global-vessel-identity:latest”. Example: [“public-global-vessel-identity:latest”].

registries_info_data (Optional[Union[VesselRegistryInfoData, str]], default=”ALL”):

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. Defaults to “ALL”. Allowed values: “NONE”, “DELTA”, “ALL”. Example: “ALL”.

includes (Optional[Union[List[VesselInclude], List[str]]], default=[“POTENTIAL_RELATED_SELF_REPORTED_INFO”]):

This query param allows to add extra information to the response. Defaults to [“POTENTIAL_RELATED_SELF_REPORTED_INFO”]. Allowed values: “POTENTIAL_RELATED_SELF_REPORTED_INFO”. Example: [“POTENTIAL_RELATED_SELF_REPORTED_INFO”].

match_fields (Optional[Union[List[VesselMatchField], List[str]]], default=None):

This query param allows to filter by matchFields levels. Defaults to None. Allowed values: “SEVERAL_FIELDS”, “NO_MATCH”, “ALL”. Example: [“ALL”].

vessel_groups (Optional[List[str]], default=None):

List of vessel-groups. Defaults to None Example: [“my-vessel-group”].

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

Additional keyword arguments.

Returns:

VesselListResult:

The list of vessel details.

Raises:

GFWAPIClientError:

If the API request fails.

RequestParamsValidationError:

If the request parameters are invalid.

async get_vessel_by_id(*, id: str, dataset: Optional[Union[gfwapiclient.resources.vessels.base.models.request.VesselDataset, str]] = None, registries_info_data: Optional[Union[gfwapiclient.resources.vessels.base.models.request.VesselRegistryInfoData, str]] = None, includes: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselInclude], List[str]]] = None, match_fields: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselMatchField], List[str]]] = None, **kwargs: Dict[str, Any]) → gfwapiclient.resources.vessels.detail.models.response.VesselDetailResult

Get vessel details by ID.

Args:

id (str):

The ID of the vessel to retrieve. Example: “6583c51e3-3626-5638-866a-f47c3bc7ef7c”.

dataset (Optional[Union[VesselDataset, str]], default=”public-global-vessel-identity:latest”):

Specify the dataset that will be used to search the vessel. Defaults to “public-global-vessel-identity:latest”. Allowed values: “public-global-vessel-identity:latest”. Example: “public-global-vessel-identity:latest”.

registries_info_data (Optional[Union[VesselRegistryInfoData, str]], default=”ALL”):

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. Defaults to “ALL”. Allowed values: “NONE”, “DELTA”, “ALL”. Example: “ALL”.

includes (Optional[Union[List[VesselInclude], List[str]]], default=[“POTENTIAL_RELATED_SELF_REPORTED_INFO”]):

This query param allows to add extra information to the response. Defaults to [“POTENTIAL_RELATED_SELF_REPORTED_INFO”]. Allowed values: “POTENTIAL_RELATED_SELF_REPORTED_INFO”. Example: [“POTENTIAL_RELATED_SELF_REPORTED_INFO”].

match_fields (Optional[Union[List[VesselMatchField], List[str]]], default=None):

This query param allows to filter by matchFields levels. Defaults to None. Allowed values: “SEVERAL_FIELDS”, “NO_MATCH”, “ALL”. Example: [“ALL”].

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

Additional keyword arguments.

Returns:

VesselDetailResult:

The vessel details.

Raises:

GFWAPIClientError:

If the API request fails.

RequestParamsValidationError:

If the request parameters are invalid.

_prepare_search_vessels_request_params(*, since: Optional[str] = None, limit: Optional[int] = 20, datasets: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselDataset], List[str]]] = None, query: Optional[str] = None, where: Optional[str] = None, match_fields: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselMatchField], List[str]]] = None, includes: Optional[Union[List[gfwapiclient.resources.vessels.search.models.request.VesselSearchInclude], List[str]]] = None) → gfwapiclient.resources.vessels.search.models.request.VesselSearchParams

Prepare and return search vessels request parameters.

_prepare_get_vessels_by_ids_request_params(*, ids: List[str], datasets: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselDataset], List[str]]] = None, registries_info_data: Optional[Union[gfwapiclient.resources.vessels.base.models.request.VesselRegistryInfoData, str]] = None, includes: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselInclude], List[str]]] = None, match_fields: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselMatchField], List[str]]] = None, vessel_groups: Optional[List[str]] = None) → gfwapiclient.resources.vessels.list.models.request.VesselListParams

Prepare and return get vessels by IDs request parameters.

_prepare_get_vessel_by_id_request_params(*, dataset: Optional[Union[gfwapiclient.resources.vessels.base.models.request.VesselDataset, str]] = None, registries_info_data: Optional[Union[gfwapiclient.resources.vessels.base.models.request.VesselRegistryInfoData, str]] = None, includes: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselInclude], List[str]]] = None, match_fields: Optional[Union[List[gfwapiclient.resources.vessels.base.models.request.VesselMatchField], List[str]]] = None) → gfwapiclient.resources.vessels.detail.models.request.VesselDetailParams

Prepare and return get vessel by ID request parameters.