Create a new Bulk Report

Create a bulk download report that allow you to get bulk access to large data slices, starting with fixed infrastructure detections from Sentinel-1 and Sentinel-2 imagery.

Create a Bulk Report examples

These examples are available:

Example 1 (POST) - Generate SAR fixed infrastructure report for Argentina EEZ with filter by label = 'oil' and structure_start_date
Example 2 (POST) - Generate report for Argentina EEZ with filter by label_confidence = 'high'
Example 3 (POST) - Generate report for Argentina EEZ with filter by label_confidence = 'medium'
Example 4 (POST) - Generate report for Argentina EEZ with filter by label_confidence = 'low'
Example 5 (POST) - Generate report for Argentina EEZ with filter by structure_id = 313068
Example 6 (POST) - Generate report for Argentina EEZ with filters by structure_start_date and structure_end_date
Example 7 (POST) - Generate report using custom GeoJSON region with filters by label and date range

Bulk Report - Specifications

POST https://gateway.api.globalfishingwatch.org/v3/bulk-reports

Authorization

ApiKeyAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

dataset*string

Specify the dataset that will be used to generate the report.

filters*array<string>

Filter to apply to the report

format?string

Output format

Value in

"CSV"
"JSON"

geojson?

Geojson of the region to filter

name*string

Name of the report

region?

Geojson of the region to filter

curl -X POST "https://example.com/api/v3/bulk-reports" \  -H "Content-Type: application/json" \  -d '{    "dataset": "public-global-dataset:latest",    "filters": [      "type = \'fishing\'"    ],    "name": "my-report"  }'

{  "createdAt": "2019-08-24T14:15:22Z",  "dataset": "string",  "fileSize": 0,  "filepath": "fixed_infrastructure_202407.csv",  "filters": [    "type = 'fishing'"  ],  "format": "",  "geom": {},  "id": "",  "name": "my-report",  "ownerId": 0,  "ownerType": "string",  "status": "pending",  "updatedAt": "2019-08-24T14:15:22Z"}

{  "error": "Unauthorized",  "messages": [    {      "detail": "No authorized",      "metadata": {},      "title": "Unauthorized"    }  ],  "statusCode": 401}

{  "error": "Forbidden",  "messages": [    {      "detail": "You do not have permissions to do the action",      "metadata": {},      "title": "Forbidden"    }  ],  "statusCode": 403}

{  "error": "Unprocessable Entity",  "messages": [    {      "detail": "Validation exception",      "metadata": {},      "title": "Unprocessable Entity"    }  ],  "statusCode": 422}

{  "error": "Service Unavailable",  "messages": [    {      "detail": "Service unavailable",      "metadata": {},      "title": "Service Unavailable"    }  ],  "statusCode": 503}

Bulk Report POST - Body

Parameter	Description	Required	Format	Param Type
`name`	Name of your report	true	string	body
`dataset`	Specify the dataset used to generate the report (e.g., `public-fixed-infrastructure-data:latest`)	true	string	body
`geojson`	GeoJSON object defining a custom region to filter	true	string (GeoJSON)	body
`format`	Output format of the report. Available options: `CSV` or `JSON`	true	Enum: [`CSV`, `JSON`]	body
`region`	Predefined region object including `dataset` and `id` (e.g., EEZ, MPA, RFMO). See region dataset	false	object	body
`filters`	Array of filters to apply. For `public-fixed-infrastructure-data:latest`, available filters include: • `label` (`oil`, `wind`, `unknown`) • `structure_start_date` (date format `YYYY-MM-DD`) • `structure_end_date` (date format `YYYY-MM-DD`) • `label_confidence` (`low`, `medium`, `high`) • `structure_id` (integer or string) Example: `["label = 'oil'", "structure_start_date between '2020-01-01' and '2025-01-01'"]`	true	array of strings	body

Bulk Report - Response fields

Since this is the same dataset Fixed infrastructure detections from Sentinel-1 and Sentinel-2 from our Data Download Portal, you can find the definitions of each field there.

Name	Type	Required	Restrictions	Description
`id`	string	true	UUID format	Unique identifier of the report
`dataset`	string	true	e.g. `public-fixed-infrastructure-data:v1.1`	API dataset used to generate the report. The response may contain the resolved version of an alias such as `latest`.
`name`	string	true		Name assigned to the report
`filepath`	string	true	e.g. `fixed_infrastructure_202407.csv`	File name inside of the dataset
`format`	string	true	Enum: `CSV`, `JSON`	Format of the report output
`filters`	array	true	Array of strings	List of applied filters (e.g. date range, label, confidence)
`geom`	object	true		Geography used for the report (region ID or custom GeoJSON)
`status`	string	true	Enum: `pending`, `processing`, `done`, `failed`	Current status of the report
`ownerId`	number	true		ID of the user or application that generated the report
`ownerType`	string	true		Type of owner (e.g. `user-application`)
`createdAt`	datetime	true	ISO 8601 format	Timestamp when the report was created
`updatedAt`	datetime	true	ISO 8601 format	Timestamp when the report was last updated
`fileSize`	number	false		Size of the final report file (if available)