Skip to content

update usage guides, workflow guides, and notebooks #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lykmapipo wants to merge 9 commits into
base: feature/bulk-downloads-result-utils
Choose a base branch
from
Open

update usage guides, workflow guides, and notebooks #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ea2a765
docs(usage-guides): update and simplify getting-started guide and not…
lykmapipo Jun 23, 2026
b1a2d9b
docs(usage-guides): update and simplify vessels API guide and notebook
lykmapipo Jun 23, 2026
89c1494
docs(usage-guides): update references data API guide and notebook
lykmapipo Jun 23, 2026
59d77b0
docs(usage-guides): update insights API guide and notebook
lykmapipo Jun 23, 2026
d5111ff
docs(events): update Events API usage guides and notebook
lykmapipo Jun 25, 2026
6c5aca1
docs(fourwings): update 4Wings API usage guides and notebook
lykmapipo Jun 25, 2026
c985ccb
docs(bulk-downloads): update Bulk Downloads API usage guides and note…
lykmapipo Jun 25, 2026
5030db9
docs(workflow-guides): update API workflow guides and jupyter notebooks
lykmapipo Jun 25, 2026
8e02cc2
Merge branch 'feature/bulk-downloads-result-utils' into feature/docs
lykmapipo Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 32 additions & 56 deletions docs/source/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,23 +76,20 @@ vessel_search_result = await gfw_client.vessels.search_vessels(
query="412331038",
)

vessel_search_ids = [
self_reported_info.id
for vessel_search_item in vessel_search_result.data()
if vessel_search_item.registry_info_total_records >= 1
for self_reported_info in vessel_search_item.self_reported_info
]
vessel_search_ids = vessel_search_result.vessel_ids

print(vessel_search_ids)
```

**Output:**

```
['755a48dd4-4bee-4bcf-7b5f-9baea058fc7b', '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f']
['da2b09b31-127e-27e0-fe5f-d6d87e96de6a',
'755a48dd4-4bee-4bcf-7b5f-9baea058fc7b',
'3dad49b0b-b2e0-9347-0c4c-e39fea560f9f']
```

**Note:** It is recommended to prioritize vessels that include both `registry_info` and `self_reported_info` (AIS), as this indicates a successful match between registry data and AIS information.
> **Note:** It is recommended to prioritize vessels that include both `registry_info` and `self_reported_info` (AIS), as this indicates a successful match between registry data and AIS information. See how the [Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api) is used in the [Vessel Viewer](https://globalfishingwatch.org/map/) [here](https://globalfishingwatch.org/our-apis/assets/2024_Vessel_Viewer_and_APIs_behind_It.pdf).

### Getting Details of Vessels Filtered by Vessel Searched IDs

Expand All @@ -101,58 +98,34 @@ vessels_result = await gfw_client.vessels.get_vessels_by_ids(
ids=vessel_search_ids,
)

vessel_self_reported_infos = [
self_reported_info
for vessel_item in vessels_result.data()
for self_reported_info in vessel_item.self_reported_info
]

vessel_ids = [
self_reported_info.id for self_reported_info in vessel_self_reported_infos
]
vessel_ids = vessels_result.vessel_ids

print(vessel_ids)
```

**Output:**

```
['755a48dd4-4bee-4bcf-7b5f-9baea058fc7b', '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f']
['da2b09b31-127e-27e0-fe5f-d6d87e96de6a',
'755a48dd4-4bee-4bcf-7b5f-9baea058fc7b',
'3dad49b0b-b2e0-9347-0c4c-e39fea560f9f']
```

### Getting Insights Related to Fishing Events for the Vessel Searched

**Important:** `start_date` must be on or after `January 1, 2020`
> **Important:** `start_date` must be on or after `January 1, 2020`. [Insights](https://globalfishingwatch.org/our-apis/documentation#insights-api) are available from `January 1, 2020` onwards.

```python
start_datetime = min(
[
self_reported_info.transmission_date_from
for self_reported_info in vessel_self_reported_infos
]
)
start_date = start_datetime.date()
start_date = start_date = min(vessels_result.transmission_dates_from)

@yaaNuamahGFW yaaNuamahGFW Jun 26, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tiny executable-doc typo: this assigns start_date twice. It should just be start_date = min(vessels_result.transmission_dates_from).

start_date = max(start_date, datetime.date.fromisoformat("2020-01-01"))


end_datetime = max(
[
self_reported_info.transmission_date_to
for self_reported_info in vessel_self_reported_infos
]
)
end_date = end_datetime.date()

dataset_id = "public-global-vessel-identity:latest"
dataset_ids_vessel_ids = [
{"dataset_id": dataset_id, "vessel_id": vessel_id} for vessel_id in vessel_ids
]
end_date = max(vessels_result.transmission_dates_to)

insights_result = await gfw_client.insights.get_vessel_insights(
includes=["FISHING"],
start_date=start_date,
end_date=end_date,
vessels=dataset_ids_vessel_ids,
vessels=vessel_ids,
)

insights_df = insights_result.df()
Expand All @@ -163,7 +136,7 @@ print(insights_df.info())
**Output:**

```
<class 'pandas.core.frame.DataFrame'>
<class 'pandas.DataFrame'>
RangeIndex: 1 entries, 0 to 0
Data columns (total 6 columns):
# Column Non-Null Count Dtype
Expand All @@ -187,7 +160,10 @@ print(dict(insights_data.apparent_fishing.period_selected_counters))
**Output:**

```
{'events': 398, 'events_gap_off': None, 'events_in_rfmo_without_known_authorization': 144, 'events_in_no_take_mpas': 0}
{'events': 263,
'events_gap_off': None,
'events_in_rfmo_without_known_authorization': 163,
'events_in_no_take_mpas': 0}
```

### Getting Fishing Events for the Vessels Searched
Expand All @@ -208,27 +184,27 @@ print(events_df.info())
**Output:**

```
<class 'pandas.core.frame.DataFrame'>
RangeIndex: 398 entries, 0 to 397
<class 'pandas.DataFrame'>
RangeIndex: 263 entries, 0 to 262
Data columns (total 14 columns):
# Column Non-Null Count Dtype
--- ------ -------------- -----
0 start 398 non-null datetime64[ns, UTC]
1 end 398 non-null datetime64[ns, UTC]
2 id 398 non-null object
3 type 398 non-null object
4 position 398 non-null object
5 regions 398 non-null object
6 bounding_box 398 non-null object
7 distances 398 non-null object
8 vessel 398 non-null object
0 start 263 non-null datetime64[us, UTC]
1 end 263 non-null datetime64[us, UTC]
2 id 263 non-null str
3 type 263 non-null str
4 position 263 non-null object
5 regions 263 non-null object
6 bounding_box 263 non-null object
7 distances 263 non-null object
8 vessel 263 non-null object
9 encounter 0 non-null object
10 fishing 398 non-null object
10 fishing 263 non-null object
11 gap 0 non-null object
12 loitering 0 non-null object
13 port_visit 0 non-null object
dtypes: datetime64[ns, UTC](2), object(12)
memory usage: 43.7+ KB
dtypes: datetime64[us, UTC](2), object(10), str(2)
memory usage: 28.9+ KB
```

## Next Steps
Expand Down
Loading
Loading