It appears that I have missed this Developer documents section of the GFW Help Center, which provides guidance on how to use and set up auth tokens + API key, and construct POST requests for querying data.

The https://data-api.globalforestwatch.org/datasets endpoint reveals all of the datasets available in the GFW API.

Let's take the GFW Integrated Alerts, which is a new "integrated deforestation alerts layer [that] combines the analytical power of GLAD, GLAD-S2 and RADD deforestation alerts to provide a faster, more confident view of forest disturbances than any one individual system."

At the GFW Integrated Alerts dataset endpoint at https://data-api.globalforestwatch.org/dataset/gfw_integrated_alerts/, there is a versions array with daily updates. To access data for that specific version: https://data-api.globalforestwatch.org/dataset/gfw_integrated_alerts/{version}. But better yet - latest resolves to the latest version available.

We can construct a query with SQL parameters for this POST endpoint: https://data-api.globalforestwatch.org/dataset/gfw_integrated_alerts/latest/query.

Example of a POST request structure provided in the documentation:
curl --location --request POST 'https://data-api.globalforestwatch.org/dataset/umd_tree_cover_loss/latest/query' \ --header 'x-api-key: <API_KEY>' \ --header 'Content-Type: application/json' \ --data-raw '{ "geometry": { "type": "Polygon", "coordinates": [[ [103.19732666015625, 0.5537709801264608], [103.24882507324219, 0.5647567848663363], [103.21277618408203, 0.5932511181408705], [103.19732666015625, 0.5537709801264608] ]] }, "sql": "SELECT SUM(area__ha) FROM results WHERE umd_tree_cover_loss__year=2019" }'


However, I have not found a list of possible SQL queries, so I'm not sure yet how to apply this for our use case. It's not clear if we can request raw GeoJSON, or how the SQL query for doing so would need to be written. Rather than going through the process of trying to figure it out, I have asked GFW for more guidance on this.

Turns out it's pretty straightforward. Sample query:

curl --location --request POST 'https://data-api.globalforestwatch.org/dataset/gfw_integrated_alerts/latest/query' \ --header 'x-api-key: <API_KEY>' \ --header 'Content-Type: application/json' \ --data-raw '{ "geometry": { "type": "Polygon", "coordinates": [[ [103.19732666015625, 0.5537709801264608], [103.24882507324219, 0.5647567848663363], [103.21277618408203, 0.5932511181408705], [103.19732666015625, 0.5537709801264608] ]] }, "sql": "SELECT latitude, longitude, gfw_integated_alerts__date, gfw_integrated_alerts__confidence FROM results WHERE gfw_integrated_alerts__date >= '2023-01-01'" }'


This will return an array of results, like this:

  {
      "latitude": -6.90075,
      "longitude": -76.13315,
      "umd_glad_landsat_alerts__date": "2021-01-03",
      "umd_glad_landsat_alerts__confidence": "high"
  },
  {
      "latitude": -6.90085,
      "longitude": -76.13315,
      "umd_glad_landsat_alerts__date": "2021-01-03",
      "umd_glad_landsat_alerts__confidence": "high"
  }

Using this, we can construct a GeoJSON feature collection composed of points to use on the front end.

The GFW API does raster analysis on the fly, and there are payload limitations to bear in mind.

I encountered this when trying to query data for one of our partner territories:

'Raster analysis lambda received an unexpected response: {\n "errorMessage": "Response payload size exceeded maximum allowed payload size (6291556 bytes).",\n "errorType": "Function.ResponseSizeTooLarge"\n}' }