Build a Green Finance Feature in 30 Minutes with the GreenCalc API

The EU is spending billions on the Renovation Wave — 35 million buildings to be retrofitted by 2030. France, Germany, Italy, Belgium, and Spain each have their own subsidy programs with different eligibility rules.

If you're building a PropTech app, energy audit tool, or renovation marketplace, your users will ask: "How much subsidy can I get?"

This tutorial shows you how to answer that question with a single API call.

What We're Building

A feature that takes a household profile and returns:

• Which subsidy programs they qualify for
• Estimated amounts in EUR
• Net cost after all subsidies

We'll use the GreenCalc API — a REST API covering 12 subsidy programs across 5 EU countries.

Prerequisites

• A free sandbox API key (works immediately, no sign-up required)
• Any HTTP client (we'll show cURL, JavaScript, and Python)

Sandbox key for testing:

gc_sandbox_000000000000000000000000000000000

Step 1: Check What's Available

First, let's see which countries and work types are supported:

# List countries
curl https://greencalc.io/api/v1/eligibility/countries \
  -H "X-Api-Key: gc_sandbox_000000000000000000000000000000000"

# List work types
curl https://greencalc.io/api/v1/eligibility/work-types \
  -H "X-Api-Key: gc_sandbox_000000000000000000000000000000000"

Countries return with their available program count, work types include things like WALL_INSULATION, HEAT_PUMP, SOLAR_PANELS, etc.

Step 2: Check Eligibility

The /eligibility/check endpoint tells you which programs a household qualifies for without running a full financial simulation:

const response = await fetch("https://greencalc.io/api/v1/eligibility/check", {
  method: "POST",
  headers: {
    "X-Api-Key": "gc_sandbox_000000000000000000000000000000000",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country_code: "FR",
    household_income: 25000,
    household_persons: 3,
    property_type: "HOUSE",
    property_age_years: 25,
    work_types: ["WALL_INSULATION", "HEAT_PUMP"],
  }),
});

const result = await response.json();
console.log(result.eligible);       // true
console.log(result.programs.length); // 2-3 programs
console.log(result.total_estimated); // e.g. 12300

This household qualifies for MaPrimeRénov' and CEE in France — around €12,300 in subsidies.

Step 3: Run a Full Simulation

Add estimated_cost to get the complete financial picture:

import requests

result = requests.post(
    "https://greencalc.io/api/v1/eligibility/simulate",
    headers={
        "X-Api-Key": "gc_sandbox_000000000000000000000000000000000",
        "Content-Type": "application/json",
    },
    json={
        "country_code": "FR",
        "household_income": 25000,
        "household_persons": 3,
        "property_type": "HOUSE",
        "property_age_years": 25,
        "owner_occupant": True,
        "work_types": ["WALL_INSULATION", "HEAT_PUMP"],
        "estimated_cost": 18000,
    },
).json()

print(f"Renovation cost: €{result['estimated_cost']}")
print(f"Subsidies:       €{result['total_subsidies']}")
print(f"You pay:         €{result['net_cost']}")
print(f"Savings:         {result['savings_percentage']}%")

Output:

Renovation cost: €18,000
Subsidies:       €12,300
You pay:         €5,700
Savings:         68.3%

The simulation also returns zero-interest loan eligibility (like France's Éco-PTZ up to €30,000) — so you can show users their financing options alongside grants.

Step 4: Compare Countries

Building for a multi-country audience? The /compare endpoint runs simulations across multiple countries in one request:

curl https://greencalc.io/api/v1/eligibility/compare \
  -X POST \
  -H "X-Api-Key: gc_sandbox_000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "country_codes": ["FR", "DE", "IT"],
    "household_income": 30000,
    "household_persons": 4,
    "property_type": "HOUSE",
    "property_age_years": 20,
    "work_types": ["HEAT_PUMP", "SOLAR_PANELS"],
    "estimated_cost": 22000
  }'

This returns a side-by-side comparison — useful for showing users which country offers the best deal or for cross-border analytics.

Handling Errors

The API returns RFC 7807 Problem Details for errors:

{
  "status": 400,
  "title": "Validation Error",
  "detail": "country_code must be one of: FR, DE, IT, BE, ES"
}

Common status codes:

• 400 — Invalid input (missing field, bad country code)
• 401 — Invalid or missing API key
• 422 — Business rule violation (e.g., incompatible work types)
• 429 — Rate limit exceeded (sandbox: 100 req/min)

Integrating Into Your UI

Here's a minimal React component that uses the simulation endpoint:

function SubsidyCalculator({ profile }) {
  const [result, setResult] = useState(null);

  async function calculate() {
    const res = await fetch("/api/v1/eligibility/simulate", {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.GREENCALC_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(profile),
    });
    setResult(await res.json());
  }

  return (
    <div>
      <button onClick={calculate}>Calculate Subsidies</button>
      {result && (
        <div>
          <p>You could save <strong>€{result.total_subsidies}</strong></p>
          <p>Net cost: €{result.net_cost} ({result.savings_percentage}% off)</p>
          <ul>
            {result.programs.map(p => (
              <li key={p.program_id}>{p.name}: €{p.estimated_amount}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

What's Next

• Webhooks — Get notified when subsidy rules change in a country you're tracking
• More countries — Netherlands, Portugal, Austria coming soon
• Batch simulations — Run hundreds of profiles in one request

The sandbox key works for all endpoints with no sign-up. Start building:

• API Documentation
• Postman Collection
• GitHub Examples

---

Built by AZMORIS Group. Questions? Open an issue or reach out at [e-mail].