# Planting Trees

## Plant Trees

<mark style="color:green;">`POST`</mark> `https://app.thegoodapi.com/plant/trees`

Yes, planting trees is really **this** easy!

#### Headers

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| Authorization<mark style="color:red;">\*</mark> | string | \<API Key>  |

#### Request Body

<table><thead><tr><th>Name</th><th width="362">Type</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>count</td><td>integer</td><td>The number of trees you'd like to plant</td><td>yes</td></tr><tr><td>attribution</td><td>string</td><td>Use this to tag an order with a non-unique look up key. This can be used later to filter orders down all trees with the attribution key</td><td>no</td></tr><tr><td>metadata</td><td>JSON</td><td>Use this to tag an order with various k/v pairs.</td><td>no</td></tr><tr><td>idempotency_key</td><td>string</td><td>Use this for idempotency </td><td>no</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```
{
  "total_planted_trees": 45,
  "tree_details": [
    {
      "id": "i2SeocFjwNayo7PI7DpI", 
      "count": 1,
      "fractional_count": 0,
      "created_at": "2025-07-01T22:07:31.374582-04:00",
      "idempotency_key": "",
      "metadata": {
        "key1": "val1",
        "key2": 786
      },
      "attribution": "saif@thegoodapi.com"
    }
  ],
  "total_planted_trees_month": 0
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Please make sure to get an [API Key from signing up first.](https://docs.thegoodapi.com/master#sign-up) To receive your beta\_token, email <saif@thegoodapi.com> and we'll get you sorted
{% endhint %}

## Get Total Trees Planted&#x20;

<mark style="color:blue;">`GET`</mark> `https://app.thegoodapi.com/plant/trees`

#### Headers

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| Authorization<mark style="color:red;">\*</mark> | String | \<API Key>  |

#### Query Params (All optional)

| Name             | Type   | Description                                                                                                                                                                                             |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| attribution\_key | String | Fetch by attribution key                                                                                                                                                                                |
| id               | String | Fetch by Tree ID                                                                                                                                                                                        |
| created\_at      | String | All trees registered after created date (fmt: xxxx-xx-xx)                                                                                                                                               |
| end\_at          | string | All trees registered before an end date (fmt: xxxx-xx-xx)                                                                                                                                               |
| metadata         | json   | JSON to filter by metadata. Applies in "AND" operations. For example: {"key1": "val1", "key2":"val2"} will return all records that have the key1:val1 AND key2:val2 k/v pairs as part of their metadata |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "total_planted_trees": 45,
  "tree_details": [
    {
      "id": "i2SeocFjwNayo7PI7DpI",
      "count": 1,
      "created_at": "2025-07-02T02:07:31.374582Z",
      "idempotency_key": "",
      "metadata": {
        "key1": "val1",
        "key2": 786
      },
      "attribution": "user1@test.com"
    },
    {
      "id": "1NdT0fiH6Yi4ffsmmnmE",
      "count": 1,
      "created_at": "2025-07-02T02:06:57.723507Z",
      "idempotency_key": "",
      "metadata": null,
      "attribution": "user2@test.com"
    },
    {
      "id": "EOsdQ5HKjZbCKkmCZd2D",
      "count": 1,
      "created_at": "2025-07-02T02:03:28.667646Z",
      "idempotency_key": "",
      "metadata": null,
      "attribution": "user2@test.com"
    },
....
....
....
....
....
}
```

{% endtab %}
{% endtabs %}

### Tree Planting Verification Stats

<mark style="color:blue;">`GET`</mark> `https://app.thegoodapi.com/evidence`

Returns aggregated planting evidence data including photos, videos, and impact metrics from verified tree planting projects.

Currently this provides data for GoodAPI as an overall org. Very soon we'll be adding individual Tree Record data as well.

#### Authentication

| Header          | Required | Description                                        |
| --------------- | -------- | -------------------------------------------------- |
| `Authorization` | Yes      | Bearer token with your API key: `Bearer <API_KEY>` |

#### Response

```json
{
  "summary": {
    "total_trees": 1847811,
    "trees_planted": 330447,
    "trees_allocated": 1517364,
    "carbon_offset_tons": 81748.316,
    "area_restored_hectares": 190.37407,
    "working_days": 682.334,
    "species_diversity": 0,
    "countries": ["Brazil", "Canada", "Haiti", "Indonesia", "Kenya", "Madagascar", "United States"],
    "evidence_count": 2342
  },
  "regions": [
    {
      "id": "23",
      "name": "Kwale",
      "country": "Kenya",
      "center": {
        "lat": -4.089119481106232,
        "lng": 39.57107618382457
      },
      "evidence": [
        {
          "id": "735545",
          "type": "image",
          "url": "https://d38us48sb13m7f.cloudfront.net/...",
          "lat": -4.61068,
          "lng": 39.24851833,
          "date": "2025-09-23T14:11:17.000000Z"
        },
        ....
        ....
        ....
      ]
    }
  ]
}
```

#### Example Request

```bash
curl -X GET "https://api.thegoodapi.com/evidence" \
  -H "Authorization: Bearer your_api_key"
```

#### Notes

* Response is cached for 30 days for performance
* Evidence items are grouped by geographic region based on coordinates
* All media URLs are served via Veritree's CDN