ZeroCarbon LogoZeroCarbon|Documentation
OverviewGet API Key
API Reference

API Reference

Complete reference for all ZeroCarbon API endpoints and their parameters.

Base URL

https://api.zerocarbon.org.in/v1

Endpoints Overview

Submit Activities

POST /activities

Submit carbon emission activities

Get Emissions

GET /emissions

Retrieve aggregated emissions data

Generate Reports

POST /reports

Create compliance reports

More Endpoints

10+ additional endpoints

Explore more below

Submit Activities

Submit a single or multiple carbon emission activities.

POST/activities

Request Body

request.tstypescript
interface ActivitySubmission {
  activity_type: string;           // "electricity", "fuel", "travel", etc.
  scope: "1" | "2" | "3";          // GHG Protocol scope
  quantity: number;                // Amount consumed
  unit: string;                    // "kWh", "liters", "km", etc.
  period: {
    start: string;                 // ISO 8601 date
    end: string;                   // ISO 8601 date
  };
  location: {
    country: string;               // ISO 3166-1 alpha-2 code
    state?: string;
    city?: string;
    grid_region?: string;
  };
  source?: {
    type: string;                  // "manual", "api", "csv", etc.
    confidence: number;            // 0.0 to 1.0
    name?: string;
    reference?: string;
  };
  metadata?: Record<string, any>; // Custom fields
}

Example Request

submit-activity.tstypescript
const response = await fetch('https://api.zerocarbon.org.in/v1/activities', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    activity_type: "electricity",
    scope: "2",
    quantity: 1500,
    unit: "kWh",
    period: {
      start: "2026-02-01",
      end: "2026-02-28"
    },
    location: {
      country: "IN",
      state: "Maharashtra",
      city: "Mumbai"
    },
    source: {
      type: "manual",
      confidence: 1.0,
      name: "Monthly Utility Bill"
    }
  })
});

const data = await response.json();

Response

response.jsonjson
{
  "success": true,
  "data": {
    "activity_id": "act_abc123xyz789",
    "emissions_kg_co2e": 1125.50,
    "confidence_score": 0.95,
    "emission_factor": {
      "value": 0.751,
      "unit": "kg CO2e/kWh",
      "source": "India Central Electricity Authority 2025",
      "region": "Western Grid"
    },
    "created_at": "2026-02-15T10:30:00Z"
  },
  "meta": {
    "timestamp": "2026-02-15T10:30:00Z",
    "request_id": "req_xyz789abc123"
  }
}

Get Emissions

Retrieve aggregated emissions data for a specified time period.

GET/emissions

Query Parameters

ParameterTypeRequiredDescription
start_datestringYesStart date (ISO 8601)
end_datestringYesEnd date (ISO 8601)
scopestringNoFilter by scope (1, 2, or 3)
group_bystringNoGroup results (day, week, month, year)
activity_typestringNoFilter by activity type

Example Request

terminalbash
curl "https://api.zerocarbon.org.in/v1/emissions?start_date=2026-02-01&end_date=2026-02-28&group_by=month" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

response.jsonjson
{
  "success": true,
  "data": {
    "total_kg_co2e": 45678.90,
    "period": {
      "start": "2026-02-01",
      "end": "2026-02-28"
    },
    "breakdown": [
      {
        "scope": "1",
        "emissions_kg_co2e": 12345.67,
        "percentage": 27.0
      },
      {
        "scope": "2",
        "emissions_kg_co2e": 23456.78,
        "percentage": 51.3
      },
      {
        "scope": "3",
        "emissions_kg_co2e": 9876.45,
        "percentage": 21.7
      }
    ],
    "by_activity_type": [
      {
        "activity_type": "electricity",
        "emissions_kg_co2e": 20000.00,
        "count": 12
      },
      {
        "activity_type": "fuel",
        "emissions_kg_co2e": 15000.00,
        "count": 8
      }
    ]
  }
}

Generate Reports

Generate compliance reports in various formats (PDF, CSV, Excel).

POST/reports

Request Body

request.tstypescript
interface ReportRequest {
  report_type: "brsr" | "ghg_protocol" | "custom";
  period: {
    start: string;
    end: string;
  };
  format: "pdf" | "csv" | "excel" | "json";
  include?: {
    scope_1?: boolean;
    scope_2?: boolean;
    scope_3?: boolean;
    verification?: boolean;
    audit_trail?: boolean;
  };
}

Example Request

generate-report.tstypescript
const response = await fetch('https://api.zerocarbon.org.in/v1/reports', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    report_type: "brsr",
    period: {
      start: "2025-04-01",
      end: "2026-03-31"
    },
    format: "pdf",
    include: {
      scope_1: true,
      scope_2: true,
      scope_3: true,
      verification: true
    }
  })
});

const data = await response.json();

Additional Endpoints

Explore more endpoints in the detailed sections:

POST /activities/bulk

Upload multiple activities via CSV or JSON

→

GET /activities/:id

Retrieve specific activity details

DELETE /activities/:id

Delete an activity (soft delete with audit)

GET /emission-factors

List available emission factors

Error Responses

All errors follow a consistent format:

error.jsonjson
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "status": 400,
    "details": {
      "field": "quantity",
      "reason": "Must be a positive number"
    }
  },
  "meta": {
    "timestamp": "2026-02-15T10:30:00Z",
    "request_id": "req_xyz789"
  }
}

Common error codes:

  • 400 BAD_REQUEST - Invalid request parameters
  • 401 UNAUTHORIZED - Authentication failed
  • 403 FORBIDDEN - Insufficient permissions
  • 404 NOT_FOUND - Resource not found
  • 429 RATE_LIMIT_EXCEEDED - Too many requests
  • 500 INTERNAL_ERROR - Server error
Previous
Authentication
Next
Carbon Activity Model
ZeroCarbon | India's Carbon Accounting & BRSR Reporting Software