Planting Trees

Plant trees, fetch the total number of trees you’ve planted, and access aggregated verification evidence.

Plant Trees

POST https://app.thegoodapi.com/plant/trees

Planting trees is this easy.

Headers

Name	Type	Description
Authorization*	string	<your_api_key>

Request body

Name	Type	Required	Description
count	integer	Yes	The number of trees you’d like to plant
attribution	string	No	Tag an order with a non-unique lookup key for filtering
metadata	JSON	No	Tag an order with arbitrary key/value pairs
idempotency_key	string	No	Use this to safely retry requests without double-planting

Response — 200 OK

{
  "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
}

Need an API key?

Sign up at app.thegoodapi.com/fe/login to grab your production and test keys.

Get total trees planted

GET https://app.thegoodapi.com/plant/trees

Headers

Name	Type	Description
Authorization*	string	<your_api_key>

Query parameters

All query parameters are optional.

Name	Type	Description
attribution_key	string	Fetch by attribution key
id	string	Fetch by Tree ID
created_at	string	Trees registered after date (format: YYYY-MM-DD)
end_at	string	Trees registered before date (format: YYYY-MM-DD)
metadata	JSON	JSON filter with AND operations

Response — 200 OK

{
  "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"
    }
  ]
}

Tree planting verification stats

GET https://app.thegoodapi.com/evidence

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

Authentication

Header	Required	Description
Authorization	Yes	<your_api_key>

Example request

curl -X GET "https://app.thegoodapi.com/evidence" \
  -H "Authorization: your_api_key"

Response — 200 OK

{
  "summary": {
    "total_trees": 1847811,
    "trees_planted": 330447,
    "carbon_offset_tons": 81748.316,
    "area_restored_hectares": 190.37407,
    "countries": [
      "Brazil",
      "Canada",
      "Haiti",
      "Indonesia",
      "Kenya",
      "Madagascar",
      "United States"
    ]
  },
  "regions": [
    {
      "id": "23",
      "name": "Kwale",
      "country": "Kenya",
      "evidence": [
        {
          "id": "735545",
          "type": "image",
          "url": "https://d38us48sb13m7f.cloudfront.net/...",
          "date": "2025-09-23T14:11:17.000000Z"
        }
      ]
    }
  ]
}

Notes

• Response is cached for 30 days for performance.
• Evidence items are grouped by geographic region based on coordinates.
• Media URLs are served via Veritree’s CDN.

Tree planting verification evidence by ID

GET https://app.thegoodapi.com/evidence/tree/<treeid>

Beta Endpoint

This endpoint is currently in Beta. All response fields and request parameters are subject to change.

Returns the specific verification timeline, status, and partner evidence for a single tree planting transaction.

Path parameters

Name	Type	Required	Description
treeid	string	Yes	The unique ID of the tree planting (returned when planting or fetching trees)

Authentication

Header	Required	Description
Authorization	Yes	<your_api_key>

Example request

curl -X GET "https://app.thegoodapi.com/evidence/tree/i2SeocFjwNayo7PI7DpI" \
  -H "Authorization: <your_api_key>"

Response — 200 OK

{
  "tree_id": "i2SeocFjwNayo7PI7DpI",
  "status": "planted",
  "timeline": [
    {
      "event": "registered",
      "title": "Tree Registered",
      "status": "completed",
      "date": "2025-07-02T02:07:31.374582Z",
      "description": "The tree was successfully registered on The Good API platform.",
      "evidence": {
        "tree_id": "i2SeocFjwNayo7PI7DpI",
        "registered_at": "2025-07-02T02:07:31.374582Z",
        "count": 1,
        "fractional_count": 0,
        "attribution": "user1@test.com"
      }
    },
    {
      "event": "funds_distributed",
      "title": "Funds Distributed",
      "status": "completed",
      "date": "2025-07-02T03:07:31Z",
      "description": "Funding has been distributed to our planting partner for this tree order.",
      "evidence": {
        "partner": "veritree",
        "tree_order_id": "456",
        "tree_order_public_id": "VO-456",
        "buyer_name": "The Good API"
      }
    },
    {
      "event": "allocated",
      "title": "Allocated to Planting Site",
      "status": "completed",
      "date": "2025-07-02T04:07:31Z",
      "description": "The tree has been allocated to a specific verified planting site and crew.",
      "evidence": {
        "partner": "veritree",
        "allocations": [
          {
            "allocation_id": 789,
            "date_allocated": "2025-07-02 04:07:31",
            "planting_site": {
              "id": 12,
              "name": "Site A",
              "subsite_name": "Kwale Mangroves Subsite 3",
              "organization_name": "Eden Reforestation",
              "latitude": -4.17444,
              "longitude": 39.46028,
              "main_image": "https://d38us48sb13m7f.cloudfront.net/site-a-overview.jpg"
            },
            "crew": {
              "leader": "John Doe",
              "style": "propagule planting",
              "total_members": 5,
              "women_members": 2
            }
          }
        ]
      }
    },
    {
      "event": "planted",
      "title": "Tree Planted",
      "status": "completed",
      "date": "2025-07-02T05:07:31Z",
      "description": "Our partner has physically planted the tree, geolocated it, and captured photo/video evidence.",
      "evidence": {
        "partner": "veritree",
        "date_planted": "2025-07-02 05:07:31",
        "media": [
          {
            "id": 735545,
            "type": "image",
            "url": "https://d38us48sb13m7f.cloudfront.net/planted_evidence_735545.jpg",
            "thumbnail_url": "https://d38us48sb13m7f.cloudfront.net/planted_evidence_735545_thumb.jpg",
            "latitude": -4.17421,
            "longitude": 39.46045
          }
        ]
      }
    }
  ]
}

Timeline States

The verification process progresses chronologically through four stages in the timeline array:

1. registered: Initial registry of the tree planting order on The Good API platform. Contains transaction detail counts and attribution.
2. funds_distributed: Clearing of the funds and distribution to reforestation partners (e.g. Veritree). Contains the public tree order identifiers.
3. allocated: Selection of a specific planting location sub-site and allocation of a physical planting crew. Includes GPS coordinates of the subsite, leader name, and crew composition.
4. planted: Complete verification in the field. Includes high-resolution photographic/video evidence geotagged at the planting coordinate, exact timestamps, and thumbnail media options.

[!NOTE] Stages that have not yet occurred will remain with a "status": "pending" indicator, and their "date" and "evidence" fields will be omitted from the event.

Notes

• Response is cached for 30 days for performance.
• Media URLs and verification photographs are served directly from verified CDNs.