Using a custom region for the 4wings API

[mattcarr03]

Hi there,

Thank you for all the work done in making this package and documents freely available!

I am struggling to use the 4wings API with a custom region/geojson polygon. I have no problem using the public eez datasets (see example below):

ais_report_result = await gfw_client.fourwings.create_report(
spatial_resolution="LOW",
temporal_resolution="YEARLY",
group_by="VESSEL_ID",
datasets=["public-global-presence:latest"],
start_date=yr_start,
end_date=yr_end,
region={
"dataset": "public-eez-areas",
"id": "8396", # South Africa EEZ
}
)

However if I want to add a custom region the script fails, for example:

test_region = gpd.GeoDataFrame(
geometry=[box(16, -36, 19, -33)],
crs="EPSG:4326"
)

test_region = {
"geojson": test_region.geometry[0].geo_interface
}

ais_report_result = await gfw_client.fourwings.create_report(
spatial_resolution="LOW",
temporal_resolution="YEARLY",
group_by="VESSEL_ID",
datasets=["public-global-presence:latest"],
start_date=yr_start,
end_date=yr_end,
region=test_region
)

I have tried many different variations to create the geojson "test region" but have not yet managed to find the correct format. Could you please advise if it is possible to have a custom region using the python client package? If so, what is the correct format for using a custom geojson file?

Kind regards,
Matthew Carr

[lykmapipo]

@mattcarr03 Based on Creating a Report or Creating an AIS Presence Report and your shared examples above, below is how you can Create and pass custom region/geojson from shapely/geodataframe to create 4Wings reports from your Jupyter Notebooks:

import os
from shapely import box

import geopandas as gpd
import gfwapiclient as gfw

# 1. Instantiate the `gfw.Client`
access_token = os.environ.get(
    "GFW_API_ACCESS_TOKEN",
    "<OR_PASTE_YOUR_GFW_API_ACCESS_TOKEN_HERE>",
)

gfw_client = gfw.Client(
    access_token=access_token,
)

# 2. Create custom region/geojson from geodataframe
gdf = gpd.GeoDataFrame(
    geometry=[box(16, -36, 19, -33)],
    crs="EPSG:4326",
)
# OR:
# gdf = gpd.read_file("path/to/your/custom/geojson.shp")

geojson = gdf.__geo_interface__  # Obtain geojson from shapely/geodataframe

# 3. Creating an AIS Presence report
ais_presence_report_result = await gfw_client.fourwings.create_report(
    spatial_resolution="LOW",
    temporal_resolution="YEARLY",
    group_by="VESSEL_ID",
    datasets=["public-global-presence:latest"],
    start_date="2022-01-01",
    end_date="2022-03-01",
    geojson=geojson,
)

# 4. Access the report data as a DataFrame
ais_presence_report_df = ais_presence_report_result.df()


# 5. Explore the report data
ais_presence_report_df.info()

Disclaimer: AIS vessel presence is one of the largest datasets available. To prevent timeouts and ensure optimal performance, keep requests manageable: prefer simple, small regions/geojsons and shorter time ranges (e.g., a few days).

The next release will allow you to pass shapely, GeoDataFrame or file path to geojson parameter. See: enhance GeoJSON handling across resources

Hope it helps.

[mattcarr03]

Hi, @lykmapipo thank you for the clarification!

The geojson option works as expected.

Thanks again for all the work put into this package.