Bulk Download API

Bulk Download API Introduction

The Bulk Download API is designed to support workflows that require bulk access to data, including integration with platforms and tools used by data engineers and researchers. At the moment we are releasing with the API dataset of Fixed infrastructure detections derived from Sentinel-1 and Sentinel-2 satellite imagery.

Listing endpoints in this API are paginated. See Pagination for how limit, offset, and nextOffset work.

This API allows you to:

• Create bulk reports based on specific filters and spatial parameters
• Monitor report generation status
• Download datasets in CSV or JSON format
• Retrieve region geometry and metadata

Supported Bulk-download API Datasets

Fixed infrastructure detections from Sentinel-1 and Sentinel-2

The API dataset used in this API is: public-fixed-infrastructure-data:latest

Offshore fixed infrastructure is a global dataset detected and classified using Synthetic Aperture Radar (SAR) and Optical imagery from the Sentinel-1 and Sentinel-2 satellite constellations. The dataset is updated daily and includes detections from 2017 to approximately three months before the current date. This dataset supports use cases in maritime domain awareness, vessel monitoring, marine spatial planning, and environmental analysis. Refer to Paolo et al. 2024, Nature: View the paper. This API dataset returns the same data published in our Data Download Portal here.

Detection is performed using a Constant False Alarm Rate (CFAR) algorithm, modified to exclude non-stationary objects. Deep learning (based on the ConvNeXt architecture) is applied to classify detections into the categories: oil, wind, unknown, lake maracaibo, and noise. Post-processing includes clustering, temporal smoothing, and manual expert review. Each detection is assigned a confidence level (high, medium, or low) to support interpretation. For more details on Data Caveats, please visit, Fixed Infrastructure Data Caveats

Difference between this Bulk Download API and the Datasets API regarding fixed infrastructure

This Bulk Download API returns all fixed infrastructure data, including regions like Chile, Canada, and Norway, as well as some noisy data, while the Datasets API and our Map filter out noisy data.

Available Bulk Download API endpoints

1. Create a new Bulk Report – Generate fixed infrastructure reports by specifying spatial filters, dataset, and date range. Supports CSV or JSON formats.
2. Get Bulk Report status by ID – Check the current status of a report (e.g. pending, done, failed) and metadata including creation timestamp.
3. Download report files – Retrieve signed URLs for downloading the data file (DATA), metadata (README), or region geometry (GEOM) used in the report.
4. Query report results in JSON – Access the structured contents of the generated report with pagination and sorting capabilities. Ideal for filtered previews or integration with scripts.

Create a Bulk Report

Bulk Report - HTTP Request

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

Bulk Report - Body only for POST request

Bulk Report - Create a Bulk Report examples

These examples are available:

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

Bulk Report - Response

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.

Bulk Report Object Schema

Get Bulk Report by ID

This endpoint allows you to retrieve metadata and status of a previously created report using its unique report ID. Use this endpoint to check the current status of a bulk report. Depending on the complexity and size of your request (e.g. large region, long time range), generating the report can take several minutes to several hours. We recommend polling this endpoint periodically to monitor the report’s progress.

Get Bulk Report by ID - HTTP Request

GET https://gateway.api.globalfishingwatch.org/v3/bulk-reports/{id}

Get Bulk Report by ID - URL Parameters

Get Bulk Report by ID - HTTP Response

Returns the same structure as the response from Create Bulk Report, including fields such as status, name, createdAt, filters, and more. See the Bulk Report - Response Schema for the complete structure.

EXAMPLE: Get bulk report by id

curl --location 'https://gateway.api.globalfishingwatch.org/v3/bulk-reports/adbb9b62-5c08-4142-82e0-b2b575f3e058' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer TOKEN'

// Make sure to replace [TOKEN] with your API Access Token.
const res = await fetch(
  'https://gateway.api.globalfishingwatch.org/v3/bulk-reports/adbb9b62-5c08-4142-82e0-b2b575f3e058',
  { headers: { Authorization: 'Bearer [TOKEN]' } }
)
const data = await res.json()

EXAMPLE: RESPONSE - Get bulk report by id

{
    "id": "adbb9b62-5c08-4142-82e0-b2b575f3e058",
    "dataset": "public-fixed-infrastructure-data:v1.1",
    "name": "sar-vessel-detection-example-1",
    "filepath": "sar_fixed_infrastructure_202409.csv",
    "filters": [
        "label = 'oil'",
        "structure_start_date between '2020-01-01' and '2025-01-01' "
    ],
    "status": "done",
    "geom": {
        "id": 8466,
        "type": "dataset",
        "dataset": "public-eez-areas"
    },
    "createdAt": "2025-06-27T06:43:35.571Z",
    "updatedAt": "2025-06-27T06:43:35.571Z",
    "ownerId": 509,
    "ownerType": "user-application",
    "format": "CSV",
    "fileSize": 1207
}

Download bulk Report (URL File)

This endpoint allows to download the data once the report is “done”.

Download Bulk Report - HTTP Request

GET https://gateway.api.globalfishingwatch.org/v3/bulk-reports/{id}/download-file-url

The response will return a link to our Google Cloud Platform infrastructure where the data can be downloaded.

Download Bulk Report - URL Parameters for GET Requests

Download Bulk Report – HTTP Response

Once the report is ready (status: done), this endpoint returns a signed URL to download the requested file (DATA, README, or GEOM). The response is a JSON object containing a single url field that points to a downloadable file hosted on Global Fishing Watch's cloud infrastructure.

Download Bulk Report - Examples

These examples are available: In these examples, we use the report generated in the endpoint from the Create bulk endpoint which has as report id: adbb9b62-5c08-4142-82e0-b2b575f3e058.

1. Example 1 (GET) - Get url of the data file to download it - README
2. Example 2 (GET) - Get url of the data file to download it - DATA
3. Example 3 (GET) - Get url of the data file to download it - GEOM

Get Data in JSON Format

The query endpoint allows us to get the data in JSON format

Get Data in JSON Format - HTTP Request

GET https://gateway.api.globalfishingwatch.org/v3/bulk-reports/:id/query

Get Data in JSON Format - URL Parameters

This is a GET request and does not require a body.

Get Data in JSON Format - HTTP Response

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

Returns a paginated list of detections from the Fixed Infrastructure dataset.

Get Data in JSON Format Examples

These examples are available:

1. Example 1 (GET) - Get data as json sort by structure start date DESC
2. Example 2 (GET) - Get data as json sort by detection date ASC
3. Example 3 (GET) - Get data as json sort by label
4. Example 4 (GET) - Get data as json sort by label confidence
5. Example 5 (GET) - Get data as json sort by structure start date DESC and only structure id field
6. Example 6 (GET) - Get data as json sort by structure end date ASC and only 3 fields

Get All Bulk Reports by User

Use this endpoint to retrieve all bulk reports created by your user or application. It supports pagination, sorting, and optional filtering by status or API dataset (see list of datasets available here). You can filter by the API dataset alias, such as public-fixed-infrastructure-data:latest, or by the resolved versioned value returned in the report response, such as public-fixed-infrastructure-data:v1.1.

Bulk Reports GET - HTTP Request

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

Bulk Reports GET - URL Parameters

EXAMPLE (GET) – Retrieve list of bulk reports sorted by creation date

# Make sure to replace [TOKEN] with your API Access Token.
curl --location 'https://gateway.api.globalfishingwatch.org/v3/bulk-reports?limit=10&offset=5&sort=-createdAt&dataset=public-fixed-infrastructure-data:latest' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [TOKEN]'

// Make sure to replace [TOKEN] with your API Access Token.
const res = await fetch(
  'https://gateway.api.globalfishingwatch.org/v3/bulk-reports?limit=10&offset=5&sort=-createdAt&dataset=public-fixed-infrastructure-data:latest',
  { headers: { Authorization: 'Bearer [TOKEN]' } }
)
const data = await res.json()

EXAMPLE: RESPONSE (GET) – Retrieve list of bulk reports sorted by creation date

   {
  "metadata": {},
  "limit": 10,
  "offset": 5,
  "nextOffset": null,
  "total": 10,
  "entries": [
    {
      "id": "d16d2d2a-b415-4f47-a525-54d60c0db2cd",
      "dataset": "public-fixed-infrastructure-data:v1.1",
      "name": "sar-vessel-detection-example-1",
      "filepath": "sar_fixed_infrastructure_202409.csv",
      "filters": [
        "label = 'oil'",
        "structure_start_date between '2020-01-01' and '2025-01-01'"
      ],
      "status": "done",
      "geom": {
        "id": 8466,
        "type": "dataset",
        "dataset": "public-eez-areas"
      },
      "createdAt": "2025-06-24T14:21:27.517Z",
      "updatedAt": "2025-06-24T14:21:27.517Z",
      "ownerId": 385,
      "ownerType": "user-application",
      "format": "CSV",
      "fileSize": 1207
    }
  ]
}

Bulk Reports GET - HTTP Response

Bulk Reports GET - Status Responses