Getting started using Global Forest Watch Data API

After signing up, check your mail for a confirmation email that will allow you to set a password.

2. Using GFW Website

When creating the account through Global Forest Watch's website, be aware not to login through Facebook, Google etc. This is problematic for the later steps as this approach won't allow setting a password. Therefore, please click the Sign up! link.

To sign up through the Global Forest Watch website, click here

Token

Now that an account has been created, you are ready to retrieve an access token from the Global Forest Watch API. This can be done through a POST request to /auth/token. To make sure the keys and values are properly URL-encoded, you should use --data-urlencode to make sure special characters won't break the request.

Username is the email address you used when signed up.

Here is an example request using the terminal:

If successful, you will in return get the access token which you can use to retrieve an API Key. The response will look something like this:

Remember that the access token will at some point expire, which means that you have to retrieve it again.

Retrieving the API Key

Now that our access token is acquired, we can retrieve an API Key. To authenticate the request, you will have to add your access token in an authorization header. You are also required to set the following parameters: an alias, your email, and an organization.

You can also add a list of domains for you applications. If you don’t specify any domains, your API key will default to the lowest rate limit tier. To ensure requests are accepted, include an origin header that matches one of the domains in your allowlist. You can use wildcards like *.yourdomain.com to cover subdomains, but keep in mind they won’t match the root — so be sure to include yourdomain.com as well if needed. Also, www.yourdomain.com and yourdomain.com are treated as distinct for security purposes, so include both if needed. Don’t add port numbers (e.g. localhost:3000). An example that also enables local development could be: ["www.yourdomain.com", "*.yourdomain.com", "yourdomain.com", "localhost"].

If successful, you will receive a JSON response with status and data properties. You will find the value of your API key in the api_key sub-property:

Your API key will expire after one year. If you require a longer expiration period or the service quota associated with your key does not serve your needs, please contact Global Forest Watch at [email protected].

Remember to save your api_key somewhere safe so that no unauthorized parties can access or misuse it.

Find your dataset

Now that you are able to authenticate, you are ready to start finding your data of interest. To find relevant data, you could use the API to list all datasets, or check out our page on Global Forest Watch Data API, to find our recommended datasets.

List all datasets

To retrieve a list of all datasets available from the Global Forest Watch API, you can use a GET request to the /datasets endpoint. The example below demonstrates how to fetch the first page of results with a specified page size. You can control how many results are returned by adjusting the page[size] parameter. To navigate through the dataset list, modify the page[number] parameter.

If successful, this will return a response like this. The dataset value is used by the API as an identifier for the dataset.

Retrieve a specific dataset

To receive data about a specific dataset, you can use a GET request to the /dataset/<DATASET> endpoint. Replace the <DATASET> with an id found in the results from the /datasets request, or one from the table found below.

If successful, this will return a response like this:

Dataset identifiers from datasets available in our data catalog

Get the fields for querying

Before querying a dataset, you will need to know what fields you are able to get from the dataset of interest. To retrieve this, you can use a GET request to /dataset/<DATASET>/<DATASET_VERSION>/fields.

Let's say you want to know the fields of Tree Cover Loss, which has the dataset identifier umd_tree_cover_loss. You can retrieve the available versions of this dataset using the /dataset/umd_tree_cover_loss endpoint

For any given version, the available fields depend on the type of the default asset:

• Vector default asset: The fields are the attributes of the features in the base vector dataset.
• Raster default asset: The fields include all raster tile sets that use the same grid as the raster default asset. Additionally, special fields like area__ha, latitude, and longitude are included.

To query the dataset:

• Use the name field for vector data.
• Use the pixel_meaning field for raster data

Query datasets

To query a dataset, you will need the DATASET identifier, a DATASET_VERSION, and a SQL query. To create a sql query, see Construct the SQL query below. If you want the API to return the data in csv format instead of json, you can replace /json with /csv. Be sure to replace <YOUR_API_KEY> with your actual API key for authentication.

Construct an SQL query

In order to create a SQL query, you will have to know what data you are interested in. The SQL query is constructed of the dataset fields, which were covered in the previous step. To keep it simple, this article will cover the following SQL statements:

SELECT

Here, you can list the fields you are interested in. You are also able to use aggregate functions like SUM.

FROM

Name of intermediate table (you can name this anything).

WHERE

Able to limit the results by using fields and potential values.

An example of a query could be the following, where we get the total area of tree cover loss from 2019.

If you want to do a more specific complicated search, check out e.g. W3Schools to get familiar with the SQL language.

Replace your created SQL statement with the <SQL> in the POST request like this:

Because umd_tree_cover is a raster tileset, it will require a geometry. This will be covered in the next step below.

Limit data to area of interest

The Global Forest Watch API also enables the possibility to only get data in certain areas 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.

1. Using POST request

The /query endpoint also enables you to do a post request, in order to add a geojson geometry. The GEOMETRY_TYPE could either be a Polygon or MultiPolygon.

2. Using Geostore

Geostore is great way to reuse GeoJSON objects. Let's say your application want to get data from different datasets, but your application is only interested in data from Africa. Instead of inserting the same GeoJSON object in all the requests, you can use a geostore.

To use geostore as a query parameter in the /query endpoint, you will first have to create a geostore. This can be done through a GET request to the /geostore endpoint. The endpoint can receive either a Geometry, a Feature, or a FeatureCollection. See the OpenAPI for more information. The example below will create a Geostore containing a FeatureCollection.

If successful, the response will return a gfw_geostore_id which can be used in our queries.

Download

You are also able to download datasets through the Global Forest Watch Data API. You are able to download datasets in the following formats, however, not all datasets are applicable to all formats

• JSON (/download/json)
• CSV (/download/csv)
• Geotiff (/download/geotiff)
• Shapefile (/download/shp)
• Geopackage (/download/gpkp)

Dataset Assets

To determine which data formats are available for a given dataset, you can send a GET request to the /assets endpoint. If you’re interested in specific formats, you can refine the request using the asset_type query parameter. Limit the search using the page[size] and page[number] parameters.

For the purposes of this article, the asset types of interest include:

• Raster tile set
• Database table
• Geo database table
• ESRI Shapefile
• Geopackage

You can also check which formats are available for a specific dataset by querying the /<dataset>/<version>/assets endpoint.

JSON and CSV

To be able to download the dataset in either JSON or CSV format, the asset_type should be either a Dataset table or Geo dataset table, and the asset's is_downloadable param must be true.

When creating your request, you are required to include a SQL query. If you want to limit your search further, you are also able to limit your data using a geostore_id. If you want your file to have a specific name, you are able to change the exported filename using the filename query parameter. Default is export.json or export.csv. If you are interested in csv format, you are also able to set the delimiter using the delimiter parameter. The accepted values are ,, \t, | and ;.

JSON

CSV

Geotiff

Geotiff is a raster tile format. To be able to download the dataset in this format, the asset_type should be a Raster tile set, and the asset's is_downloadable param must be true.

A limit to the geotiff endpoint is that you are only able to download one pixel_meaning, for a tile, for a specific grid. Because downloading multiple geotiffs with the Global Forest Watch API might be a struggle, a better approach might be to download the assets from the https://data.globalforestwatch.org/ site.

Not all datasets support all grid possibilities. Therefore, use the /<dataset>/version>/assets endpoint mentioned above to find which grid's are supported by the dataset. In the response, check the asset_uri for which grid and pixel_meaning the asset provides.

E.g. s3://.../espy-3857/zoom_0/coverage_gradient/geotiff/....tif.

This example provides grid zoom_0 and pixel_meaning coverage_gradient.

Then, to find the tile_id you want to download, use the /asset/asset_id/tiles_info.

Which will return a response like this:

Each feature should have a name under properties, which contains our tile_id. In the example above, the tile_id is 000R_000C.

Shapefile and Geopackage

To be able to download the dataset in one of these formats, the asset_type should be either a ESRI Shapefile or Geopackage, and the asset's is_downloadable param must be true.

Shapefile

Geopackage

Dataset Example

If you want a dataset specific example, please check out our How-To on retrieving Integrated Deforestation Alerts using the Global Forest Watch Dataset API