gfwapiclient.http.models.response

Global Fishing Watch (GFW) API Python Client - HTTP Response Models.

Module Contents

Classes

ResultItem	Base model for handling individual data items within API endpoint responses.
Result	Base model for representing API endpoint response results.

Data

__all__
_ResultItemT
_ResultT

API

gfwapiclient.http.models.response.__all__ = ['Result', 'ResultItem', '_ResultItemT', '_ResultT']

class gfwapiclient.http.models.response.ResultItem(/, **data: typing.Any)

Bases: gfwapiclient.base.models.BaseModel

Base model for handling individual data items within API endpoint responses.

This model serves as a base for defining the structure of individual data items returned by API endpoints. It extends BaseModel to leverage Pydantic’s data validation and serialization capabilities, ensuring that response data is correctly parsed and represented as Python objects.

Specific API response item models should inherit from this class and define their own fields to match the structure of the data they represent.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

gfwapiclient.http.models.response._ResultItemT = 'TypeVar(...)'

class gfwapiclient.http.models.response.Result(*, data: Union[List[gfwapiclient.http.models.response._ResultItemT], gfwapiclient.http.models.response._ResultItemT])

Bases: typing.Generic[gfwapiclient.http.models.response._ResultItemT]

Base model for representing API endpoint response results.

This model encapsulates the response data from an API endpoint, which can be either a single ResultItem or a list of ResultItem instances. It provides methods to access the data in Pydantic model format or convert it to a pandas DataFrame or GeoDataFrame.

Specific API endpoints should inherit from this class to define their own Result model, and specifying the ResultItem type.

Initialization

Initializes a new Result instance.

Args:

data (Union[List[_ResultItemT], _ResultItemT]):

The response data from the API endpoint, which can be either a single ResultItem or a list of ResultItem instances.

_result_item_class: Type[gfwapiclient.http.models.response._ResultItemT] = None

_data: Union[List[gfwapiclient.http.models.response._ResultItemT], gfwapiclient.http.models.response._ResultItemT] = None

data(**kwargs: Any) → Union[List[gfwapiclient.http.models.response._ResultItemT], gfwapiclient.http.models.response._ResultItemT]

Returns the API endpoint result data in Pydantic model format.

This method provides direct access to the underlying data, which can be either a single ResultItem instance or a list of ResultItem instances.

Args:

**kwargs (Any):

Additional arguments passed to the model_dump method to customize the serialization process.

Returns:

Union[List[_ResultItemT], _ResultItemT]:

The API endpoint result data, either a single ResultItem or a list of ResultItem.

df(*, include: Optional[Set[str]] = None, exclude: Optional[Set[str]] = None, **kwargs: Any) → Union[pandas.DataFrame, geopandas.GeoDataFrame]

Returns the API endpoint result as a DataFrame or GeoDataFrame.

This method converts the response data into a DataFrame or GeoDataFrame, allowing for easy data manipulation and analysis.

Args:

include (Optional[Set[str]]):

A set of field names to include in the DataFrame. If None, all fields are included.

exclude (Optional[Set[str]]):

A set of field names to exclude from the DataFrame. If None, no fields are excluded.

**kwargs (Any):

Additional keyword arguments to pass to DataFrame or GeoDataFrame constructor.

Returns:

Union[pd.DataFrame, gpd.GeoDataFrame]:

A DataFrame representing the API endpoint result. If the result items contain geospatial data, a GeoDataFrame may be returned.

gfwapiclient.http.models.response._ResultT = 'TypeVar(...)'