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]):

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

limit (Optional[int]):

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

datasets (Optional[Union[List[VesselDataset], List[str]]]):

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

query (Optional[str]):

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. Example: “Don tito”.

where (Optional[str]):

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

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

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

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

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

**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]]]):

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

registries_info_data (Optional[Union[VesselRegistryInfoData, str]]):

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

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

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

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

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

vessel_groups (Optional[List[str]]):

List of vessel-groups. 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]]):

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

registries_info_data (Optional[Union[VesselRegistryInfoData, str]]):

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

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

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

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

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

**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.