API Authentication

How to register and obtain your GJD API key

Overview

All examples in this section interact with the Green Jurisdictions Database through its REST API. To make authenticated requests, you need a personal API key.

Every API request has two parts:

The endpoint URL: https://api.greenjurisdictions.org/api/v1/... (with path and query parameters for filters)
The API key: sent as the X-API-TOKEN header

Diagram explaining the GJD API endpoint and authentication header — How the GJD API works

Step 1: Create an Account

If you don’t have an account yet, head to greenjurisdictions.org and sign up for free.

Step 2: Navigate to Your Profile

Once logged in, click on your username in the top navigation bar. A dropdown menu will appear — select Profile.

Navigate to Profile from the top menu

Step 3: Copy Your API Key

On the Profile page you will find your personal API key. Your session status should show as Active. Click the copy button next to the key to copy it to your clipboard.

Profile page showing the API key

Step 4: Store Your Key Safely

Never hardcode your API key

Do not paste your API key directly into your scripts. Use environment variables instead.

Create a .Renviron file in the project root with the following content:

GJD_API_KEY=your-api-key-here

The repository includes a .Renviron.example file as a template. You can copy it and fill in your key:

cp .Renviron.example .Renviron

Then edit .Renviron and replace your-api-key-here with the key you copied from your profile.

.gitignore

The .Renviron file is already listed in .gitignore, so it will never be committed to the repository. Only .Renviron.example (without your real key) is tracked by Git.

Step 5: Verify Your Setup

Open an R console (in RStudio, VS Code, or a terminal running R) and run the following code. This makes a small test request to the GJD API — fetching deforestation data for the Amazonas jurisdiction in Colombia:

library(httr2)

test_url <- paste0(
  "https://api.greenjurisdictions.org/api/v1/dataPlaces/false/true/false",
  "?ID_Topic=11",
  '&ID_Countries=["CO"]',
  '&ID_Jurisdictions=["CO-AMA"]',
  "&ID_Municipalities=[]"
)

response <- request(test_url) |>
  req_headers(
    "X-API-TOKEN"  = Sys.getenv("GJD_API_KEY"),
    "Accept"       = "application/json",
    "Content-Type" = "application/json"
  ) |>
  req_perform()

cat("Status:", resp_status(response), "\n")

body <- resp_body_json(response)
cat("Message:", body$message, "\n")
cat("Records:", body$data$total_data, "\n")

If everything is configured correctly you should see:

Status: 200
Message: Resources retrieved successfully.
Records: 56

Where to run this?

You can run the code above in any of these places:

RStudio — Open the R console (bottom-left panel) and paste the code.
VS Code / Cursor — Open a terminal, type R to start an R session, and paste the code.
Terminal — Run Rscript -e "..." directly from the command line.

Make sure you run it from the project root directory so that R can find the .Renviron file.

You can also verify with a cURL command directly from your terminal:

cURL command example for testing the GJD API — cURL example for testing the API

curl -X GET "https://api.greenjurisdictions.org/api/v1/dataPlaces/false/true/false?ID_Topic=11&ID_Countries=%5B%22CO%22%5D&ID_Jurisdictions=%5B%22CO-AMA%22%5D&ID_Municipalities=%5B%5D" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-TOKEN: YOUR_API_KEY"

Next Steps

With your API key configured, you are all set to run the use cases. Head to the Use Cases section in the sidebar.

--- title: "API Authentication" subtitle: "How to register and obtain your GJD API key" --- ## Overview All examples in this section interact with the **Green Jurisdictions Database** through its REST API. To make authenticated requests, you need a personal **API key**. Every API request has two parts: - **The endpoint URL**: `https://api.greenjurisdictions.org/api/v1/...` (with path and query parameters for filters) - **The API key**: sent as the `X-API-TOKEN` header ![How the GJD API works](../public/img/gjd-api-endpoint-explained.png){fig-alt="Diagram explaining the GJD API endpoint and authentication header" width="100%"} ## Step 1: Create an Account If you don't have an account yet, head to [greenjurisdictions.org](https://greenjurisdictions.org/) and sign up for free. ## Step 2: Navigate to Your Profile Once logged in, click on your **username** in the top navigation bar. A dropdown menu will appear — select **Profile**. ![Navigate to Profile from the top menu](../public/img/gjd-homepage-profile-menu.png){fig-alt="GJD homepage showing the user dropdown menu with the Profile option" width="100%"} ## Step 3: Copy Your API Key On the Profile page you will find your personal API key. Your session status should show as **Active**. Click the **copy button** next to the key to copy it to your clipboard. ![Profile page showing the API key](../public/img/gjd-profile-api-key.png){fig-alt="GJD profile page displaying the API key with copy button" width="100%"} ## Step 4: Store Your Key Safely ::: {.callout-warning} ## Never hardcode your API key Do not paste your API key directly into your scripts. Use environment variables instead. ::: Create a `.Renviron` file in the **project root** with the following content: ```bash GJD_API_KEY=your-api-key-here ``` The repository includes a `.Renviron.example` file as a template. You can copy it and fill in your key: ```bash cp .Renviron.example .Renviron ``` Then edit `.Renviron` and replace `your-api-key-here` with the key you copied from your profile. ::: {.callout-tip} ## .gitignore The `.Renviron` file is already listed in `.gitignore`, so it will never be committed to the repository. Only `.Renviron.example` (without your real key) is tracked by Git. ::: ## Step 5: Verify Your Setup Open an **R console** (in RStudio, VS Code, or a terminal running `R`) and run the following code. This makes a small test request to the GJD API — fetching deforestation data for the Amazonas jurisdiction in Colombia: ```{r} #| eval: false library(httr2) test_url <- paste0( "https://api.greenjurisdictions.org/api/v1/dataPlaces/false/true/false", "?ID_Topic=11", '&ID_Countries=["CO"]', '&ID_Jurisdictions=["CO-AMA"]', "&ID_Municipalities=[]" ) response <- request(test_url) |> req_headers( "X-API-TOKEN" = Sys.getenv("GJD_API_KEY"), "Accept" = "application/json", "Content-Type" = "application/json" ) |> req_perform() cat("Status:", resp_status(response), "\n") body <- resp_body_json(response) cat("Message:", body$message, "\n") cat("Records:", body$data$total_data, "\n") ``` If everything is configured correctly you should see: ``` Status: 200 Message: Resources retrieved successfully. Records: 56 ``` ::: {.callout-note} ## Where to run this? You can run the code above in any of these places: - **RStudio** — Open the R console (bottom-left panel) and paste the code. - **VS Code / Cursor** — Open a terminal, type `R` to start an R session, and paste the code. - **Terminal** — Run `Rscript -e "..."` directly from the command line. Make sure you run it from the **project root directory** so that R can find the `.Renviron` file. ::: You can also verify with a **cURL command** directly from your terminal: ![cURL example for testing the API](../public/img/gjd-api-curl-example.png){fig-alt="cURL command example for testing the GJD API" width="100%"} ```bash curl -X GET "https://api.greenjurisdictions.org/api/v1/dataPlaces/false/true/false?ID_Topic=11&ID_Countries=%5B%22CO%22%5D&ID_Jurisdictions=%5B%22CO-AMA%22%5D&ID_Municipalities=%5B%5D" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-API-TOKEN: YOUR_API_KEY" ``` ## Next Steps With your API key configured, you are all set to run the use cases. Head to the **Use Cases** section in the sidebar.