API v3General API Documentation
Pagination
How GFW API responses are structured and how to paginate through collections.
Global Fishing Watch API responses vary depending on whether you request a single resource or a collection. Collections are paginated using limit, offset, and nextOffset.
Response format
The response depends on what you request:
- Single resource: the API returns the result directly.
- Collection of resources: the API returns a paginated JSON object (except when the response is not JSON) with the properties below.
| Property | Type | Description |
|---|---|---|
total | number | Total resources available. |
limit | number | Resources returned in this response. |
offset | number | Resources skipped before this response. |
nextOffset | number | Offset to pass on the next request to paginate correctly. |
metadata | object | Any other valuable information. For search, this can include the query executed, term suggestions, and similar. |
entries | array | The list of resources. |
For example, a paginated response looks like this:
{
"metadata": {
"datasets": ["public-global-fishing-events:v3.0"],
"vessels": ["9b3e9019d-d67f-005a-9593-b66b997559e5"],
"dateRange": {
"from": "2017-01-01",
"to": "2017-01-31"
}
},
"limit": 1,
"offset": 0,
"nextOffset": 1,
"total": 10,
"entries": [
// ...list of resources
]
}