Back to how-to articles
Places to watch x Global Forest Watch API
Last updated: July 3, 2025
Before you get started
If you are new to the Global Forest Watch API, it is a good idea to begin with the foundational guide. It covers essential steps like signing up, getting access token and API key. You can find it here:
Steps
- Find the version of the dataset
- Find the fields to query
- Make a query
Find the version
To receive data about the Places to Watch dataset, you can use a GET request to the /dataset/gfw_places_to_watch endpoint.
1curl -X GET 'https://data-api.globalforestwatch.org/dataset/gfw_places_to_watch'If successful, this will return a response like this, with metadata and versions:
1{
2 "data": {
3 "created_on": "2024-11-01T17:00:04.655322",
4 "updated_on": "2025-02-20T18:18:45.911106",
5 "dataset": "gfw_places_to_watch",
6 "is_downloadable": true,
7 "metadata": {...
8 "versions": [
9 "v0",
10 "v20241101"
11 ]
12 },
13 "status": "success"
14}For the next steps v0 is the best version of this dataset
Find the relevant fields
Before querying the dataset, you will need to know what fields to get from the dataset. To retrieve this, you can use a GET request to dataset/gfw_places_to_watch/v0/fields
1curl -L -X GET 'https://data-api.globalforestwatch.org/dataset/gfw_places_to_watch/v0/fields'Available fields for this dataset are:
- ID: Unique identifier for the article entry
- type: "Article" or type of crop; “Soy” or “Oil Palm”
- datestamp: Publication date of alert or article
- title: Title of article (for type = “Article”)
- description: Brief summary of the article's content (for type = “Article”)
- image_link: URL to the featured image (for type = “Article”)
- image_credit: Attribution for the image source (for type = “Article”)
- article_link: URL to the full article (for type = “Article”)
- lat: Latitude of the geographic focus area
- lon: Longitude of the geographic focus area
- geom: Geometry in WGS 84 (hex-encoded point for GIS)
- geom_wm: Geometry in Web Mercator projection (hex-encoded point for GIS)
Query dataset
In addition to the dataset identifier gfw_places_to_watch and version, you need to construct an SQL query. Optionally for vector data sets you can also add a geometry to limit the area of interest.
Limit data to area of interest
There are two ways to do this; using Geostore, or using GeoJson in a Post request. Both methods require geojson format. The possible geometry types available in Global Forest Watch is Polygon and MultiPolygon. To easily generate this format, visit https://geojson.io.
Using POST request with a polygon
Example using polygon:
1curl -X POST 'https://data-api.globalforestwatch.org/dataset/gfw_places_to_watch/v0/query/json' \
2 -H 'x-api-key: <YOUR_API_KEY>' \
3 -H 'Content-Type: application/json' \
4 --data-raw '{
5 "sql": "SELECT * FROM results WHERE datestamp > '\''2024-09-01'\''",
6 "geometry": {
7 "type": "Polygon",
8 "coordinates": [[
9 [-79.336, 2.6449],
10 [-79.336, -28.055],
11 [-29.607, -28.055],
12 [-29.607, 2.644],
13 [-79.336, 2.6449]
14 ]]
15 }
16 }'If successful the response will look something like this:
1{
2 "data": [
3 {
4 "ID": "3",
5 "type": "Article",
6 "datestamp": "2024-09-03",
7 "title": "In Brazil's Amazon, land invasions and fires threaten a protected reserve",
8 "description": "Maranhão, Brazil is under threat from invasions and fires, complicating efforts to protect this area of rich biodiversity from the advance of agriculture and cattle ranching.",
9 "image_link": "https://imgs.mongabay.com/wp-content/uploads/sites/20/2024/08/05222309/Ionova-Gurupi-7-768x512.jpg",
10 "image_credit": "Image: Ana Ionova for Mongabay",
11 "article_link": "https://news.mongabay.com/2024/08/in-brazils-amazon-land-invasions-and-fires-threaten-a-protected-reserve/",
12 "lat": "-3.76522",
13 "lon": "-46.7148",
14 "geom": "0101000020E61000002497FF907E5B47C001F6D1A92B1F0EC0",
15 "geom_wm": "0101000020110F0000E094E7EF62D653C10074CD83D19919C1"
16 },
17 {
18 "ID": "9",
19 "type": "Soy",
20 "datestamp": "2024-12-03",
21 "title": null,
22 "description": null,
23 "image_link": null,
24 "image_credit": null,
25 "article_link": null,
26 "lat": "-9.688",
27 "lon": "-64.77133",
28 "geom": "0101000020E61000001E1B81785D3150C0C74B3789416023C0",
29 "geom_wm": "0101000020110F000050834FDE51815BC1D8AA853FF78830C1"
30 },
31 {
32 "ID": "10",
33 "type": "Soy",
34 "datestamp": "2024-12-03",
35 "title": null,
36 "description": null,
37 "image_link": null,
38 "image_credit": null,
39 "article_link": null,
40 "lat": "-15.688",
41 "lon": "-57.188",
42 "geom": "0101000020E6100000F2D24D6210984CC0C74B378941602FC0",
43 "geom_wm": "0101000020110F000027EF86C2EE4858C11FAA496BABFC3AC1"
44 },
45 {
46 "ID": "11",
47 "type": "Soy",
48 "datestamp": "2024-12-03",
49 "title": null,
50 "description": null,
51 "image_link": null,
52 "image_credit": null,
53 "article_link": null,
54 "lat": "-27.14616",
55 "lon": "-54.27064",
56 "geom": "0101000020E6100000A67EDE54A4224BC0BDFBE3BD6A253BC0",
57 "geom_wm": "0101000020110F00004FF9A000C90B57C19DBD223438F847C1"
58 }
59 ],
60 "status": "success"
61}You can read more about Geostore and constructing SQL queries from in the Global Forest Watch tutorial.
