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)

Query parameters

Name	Type	Required	Description
evidence_stage	string	Optional	Test / mock parameter to simulate any milestone stage: registered, funds_distributed, or planted (or planted_and_verified). Seeded from verified Kenya planting telemetry.

Authentication

Header	Required	Description
Authorization	Yes	<your_api_key>

Example request

Fetch live verification status:

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

Simulate completed ground verification for testing:

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

Response — 200 OK

{
  "tree_id": "i2SeocFjwNayo7PI7DpI",
  "record_id": "i2SeocFjwNayo7PI7DpI",
  "impact_type": "trees",
  "impact_provider": "veritree",
  "status": "planted",
  "provider_meta": {
    "order_id": 456,
    "public_id": "VO-456",
    "allocation_id": 789,
    "field_update_id": 12,
    "planting_session_id": 12
  },
  "timeline": [
    {
      "step": 1,
      "event": "registered",
      "title": "Tree Registered",
      "status": "completed",
      "date": "2025-07-02T02:07:31.374582Z",
      "timestamp": "2025-07-02T02:07:31.374582Z",
      "description": "The tree was successfully registered on The Good API platform.",
      "evidence": {
        "tree_id": "i2SeocFjwNayo7PI7DpI",
        "record_id": "i2SeocFjwNayo7PI7DpI",
        "registered_at": "2025-07-02T02:07:31.374582Z",
        "count": 1,
        "fractional_count": 0,
        "attribution": "user1@test.com"
      }
    },
    {
      "step": 2,
      "event": "funds_distributed",
      "title": "Funds Distributed to Veritree",
      "status": "completed",
      "date": "2025-07-02T03:07:31Z",
      "timestamp": "2025-07-02T03:07:31Z",
      "description": "Included in monthly Veritree Order #456 (VO-456).",
      "evidence": {
        "partner": "veritree",
        "order_id": 456,
        "order_public_id": "VO-456",
        "tree_order_id": 456,
        "tree_order_public_id": "VO-456",
        "tree_amount": 1000,
        "buyer_name": "The Good API"
      }
    },
    {
      "step": 3,
      "event": "planted_and_verified",
      "title": "Planted & Ground-Verified",
      "status": "completed",
      "date": "2025-07-02T05:07:31Z",
      "timestamp": "2025-07-02T05:07:31Z",
      "description": "Tree planting completed and ground-verified by Veritree telemetry.",
      "evidence": {
        "partner": "veritree",
        "planting_site_name": "Site A",
        "subsite_name": "Kwale Mangroves Subsite 3",
        "organization_name": "Eden Reforestation",
        "assessor_name": "Harrison Kazungu",
        "verifier": "Veritree Ground Intelligence Platform",
        "date_verified": "2025-07-03",
        "session_total_planted": 500,
        "species": [
          "Rhizophora mucronata",
          "Ceriops tagal"
        ],
        "image_url": "https://d38us48sb13m7f.cloudfront.net/site-a-overview.jpg",
        "allocation_id": 789,
        "field_update_id": 12,
        "planting_session_id": 12,
        "latitude": "-4.174210",
        "longitude": "39.460450",
        "photos": [
          "https://d38us48sb13m7f.cloudfront.net/planted_evidence_735545.jpg"
        ]
      }
    }
  ]
}

Timeline States

The verification process progresses chronologically through three sequential stages in the timeline array (indicated by step: 1, 2, 3):

1. registered: Initial registry of the tree planting order on The Good API platform. Contains transaction detail counts, attribution, and record_id.
2. funds_distributed: Pooling of funds into monthly planting batches distributed to reforestation partners (e.g. Veritree). Contains public tree order identifiers and batch volumes.
3. planted_and_verified: Complete ground verification in the field. Includes GPS coordinates, planting site/subsite telemetry, photographic evidence geotagged at planting coordinates, verifier details, and timestamps (date and timestamp).

[!NOTE]

• Stages that have not yet occurred will remain with a "status": "pending" indicator, and their "date", "timestamp", and "evidence" fields will be omitted from the event.
• For multi-impact compatibility across API versions, both tree_id and canonical record_id are returned, and both legacy date and RFC3339 timestamp fields are populated on all completed milestones.

Notes

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