Skip to main content

Getting Started with TotalView API

Welcome to the TotalView API! This guide will help you make your first API request and understand the core workflow for assessing the environmental impact of renewable energy projects.

What is TotalView API?​

The TotalView API enables you to submit renewable energy projects (solar, wind, hybrid, battery storage) for comprehensive environmental impact assessment. You'll receive detailed Life Cycle Impact Assessment (LCIA) results across three key categories:

  • Public Health - Quantified as Disability-Adjusted Life Years (DALYs)
  • Biodiversity - Measured as Potentially Disappeared Fractions (PDFs)
  • Economic Value - Monetized environmental externalities (USD)

Base URL​

All API requests are made to:

https://api.totalview.energy/api/v1

Authentication​

All API endpoints (except /healthz and /version) require authentication. TotalView supports two authentication methods:

1. OAuth2 Password Flow​

Exchange your credentials for a JWT access token:

curl -X POST "https://api.totalview.energy/api/v1/auth/login/access-token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your-username&password=your-password"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

2. OIDC Single Sign-On (SSO)​

For enterprise customers with Google or Amazon SSO:

curl -X POST "https://api.totalview.energy/api/v1/auth/login/oidc" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "id_token": "your-oidc-id-token"
  }'
Token Expiry

JWT tokens expire after 60 minutes. Store the token securely and refresh before expiration.

Using Your Token​

Include the token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Quick Start: Your First Project​

Let's walk through submitting a simple solar project and retrieving results.

Step 1: Create a Project​

curl -X POST "https://api.totalview.energy/api/v1/projects/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "My First Solar Project",
    "latitude": 34.0522,
    "longitude": -118.2437,
    "state": "CA",
    "nameplate_capacity": 50.0,
    "tech_type_id": "electricity production, photovoltaic, 570kWp open ground installation, multi-Si",
    "cod_date": "2024-01-01",
    "existing_project_flag": false
  }'

Key Parameters:

  • latitude / longitude - Project location (auto-infers grid region)
  • nameplate_capacity - Project size in MW (megawatts)
  • tech_type_id - Technology type identifier (see Technology Types)
  • cod_date - Commercial Operation Date (ISO 8601 format)
  • existing_project_flag - false for future projects, true for historical analysis

Response:

{
  "project_id": "a1b2c3d4-e5f6-4789-0abc-def123456789",
  "config": {
    "project_name": "My First Solar Project",
    "nameplate_capacity": 50.0,
    "latitude": 34.0522,
    "longitude": -118.2437,
    "eia_ba_code": "LDWP",
    "project_nerc_code": "US-WECC",
    ...
  },
  "latest_run": null,
  "latest_run_status": null,
  "latest_run_id": null
}
Auto-Inference

TotalView automatically infers your project's Balancing Authority (eia_ba_code) and NERC region (project_nerc_code) from coordinates. You can override these if needed.

Step 2: Queue a Model Run​

Submit your project for environmental impact modeling:

curl -X POST "https://api.totalview.energy/api/v1/projects/a1b2c3d4-e5f6-4789-0abc-def123456789/queue" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "message": "Project a1b2c3d4-e5f6-4789-0abc-def123456789 queued successfully",
  "model_run_id": "run-1234-5678-90ab-cdef"
}
Run Duration
  • Future projects (like this example): ~1-2 minutes
  • Existing projects with hourly data: ~1-2 minutes

Step 3: Check Run Status​

Poll the run status until completion:

curl -X GET "https://api.totalview.energy/api/v1/projects/a1b2c3d4-e5f6-4789-0abc-def123456789/runs/latest" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (while running):

{
  "id": "run-1234-5678-90ab-cdef",
  "project_id": "a1b2c3d4-e5f6-4789-0abc-def123456789",
  "status": "running",
  "created_at": "2024-01-15T10:30:00Z",
  ...
}

Status values:

  • queued - Waiting to start
  • running - Model execution in progress
  • completed - Results ready
  • failed - Error occurred (check logs)

Step 4: Retrieve Results​

Once status is completed, fetch the LCIA results:

curl -X GET "https://api.totalview.energy/api/v1/projects/a1b2c3d4-e5f6-4789-0abc-def123456789/results" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (simplified):

{
  "Generation": {
    "Solar": {
      "Historical": 2985.0,
      "Projected": 4629.0,
      "Difference": 1644.0
    },
    "Coal": {
      "Historical": 7763.0,
      "Projected": 6969.0,
      "Difference": -794.0
    },
    "Natural Gas": {
      "Historical": 8905.0,
      "Projected": 8055.0,
      "Difference": -850.0
    }
  },
  "Impacts": {
    "Net_Analysis": {
      "Total": {
        "DALYs": 1700.0,
        "PDFs": 3.9,
        "USD": 450000000.0
      },
      "Public_Health": [
        {
          "Impact_Category": "Carbon",
          "Unit": "DALYs",
          "Total_Impact": 1100.0,
          "USD": 194744627.0
        },
        {
          "Impact_Category": "Particulate Matter",
          "Unit": "DALYs",
          "Total_Impact": 260.0,
          "USD": 46030548.0
        }
      ],
      "Biodiversity": [...],
      "Economic": [...]
    }
  },
  "Emissions": {
    "Net_Analysis": {
      "air": [
        { "Name": "Carbon", "Unit": "Tonnes CO2-Eq", "Value": 1200000.0 },
        { "Name": "Particulate Matter", "Unit": "Tonnes PM2.5-Eq", "Value": 410.0 }
      ],
      "resource": [
        { "Name": "Energy Resources: Non-Renewable, Fossil", "Unit": "Tonnes oil-Eq", "Value": 360000.0 }
      ]
    }
  }
}
Congratulations!

You've successfully submitted a project and retrieved environmental impact results! 🎉

Positive values represent environmental benefits - avoided emissions and impacts from displacing fossil fuel generation.

Understanding Results​

Generation Changes​

The Generation section shows how your project changes the regional grid mix (in GWh):

  • Historical: Grid generation without your project
  • Projected: Grid generation with your project added
  • Difference: Your project's contribution (positive for renewables added, negative for fossil fuels displaced)

Impact Categories​

  • DALYs (Disability-Adjusted Life Years): Health benefits from avoided air pollution. 1,700 DALYs = 1,700 years of disability/premature death prevented.
  • PDFs (Potentially Disappeared Fractions): Biodiversity protection from reduced ecosystem damage.
  • USD: Economic value of avoided environmental damages. $450M in total benefits.

Rate Limits​

All accounts have usage limits to ensure fair access:

  • API Requests: 60 requests/minute globally, 5 requests/minute for login
  • Monthly Model Runs: Varies by plan (Basic: 10/month, Premium: 50/month, Enterprise: custom)
  • Monthly MW Capacity: Varies by plan (Basic: 200 MW/month)

Check your current usage:

curl -X GET "https://api.totalview.energy/api/v1/gating/status" \
  -H "Authorization: Bearer YOUR_TOKEN"

Next Steps​

Now that you've completed your first project, explore:

Need Help?​