This tutorial shows how to programmatically retrieve a solar design summary from Aurora.

How It Works

On performance simulation completion, typically the last step in creating a solar design in Aurora, you can retrieve the design summary that includes the bill of materials and energy production.

Getting Started

To complete this tutorial, you will need:

your Aurora tenant to be on a Business plan,
your Aurora tenant to use the current API version,
your Aurora bearer token,
your Aurora tenant_id,
design_id for the design summary to retrieve,
URL to deliver Aurora webhooks to.

You or any Administrator for your Aurora tenant can retrieve the token and tenant id from the API Settings page.

Step 1. Subscribe to the performance simulation completed webhook event.

Subscribe to the performance_simulation_job_completed webhook event, pointing webhooks to the application you are building to process them.

//POST https://api-sandbox.aurorasolar.com/tenants/{tenant_id}/webhooks

  {
  "webhook": {
    "description": "Performance Simulation Completed",
    "event": "performance_simulation_job_completed",
    "url_template": "https://www.yourcompany.com/aurora_performance_simulation_webhooks?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>",
    "enabled": true
  }
}

Step 2. Retrieve design summary on webhook receipt.

On the webhook receipt, retrieve the design summary using the design_id included in the webhook.

//Webhook query string payload

?design_id=5fd85f64-5717-4562-b3fc-2c963f66afa3&job_id=1bc85f64-5717-4562-b3fc-2c963f66aab9&status=succeeded

//GET https://api-sandbox.aurorasolar.com/tenants/{tenant_id}/designs/{design_id}/summary

{
  "design": {
    "design_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "external_provider_id": "YourId123",
    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bill_of_materials": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "SNPM GxB 300",
        "component_type": "modules",
        "quantity": 1
      }
    ],
    "system_size_ac": 5000,
    "system_size_ptc": 6000,
    "system_size_stc": 6500,
    "arrays": [
      {
        "size": 6500,
        "azimuth": 271.61,
        "configuration": "string inverter",
        "dc_optimizer": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "manufacturer": "Tigo Energy Inc.",
          "name": "MM-2ES50",
          "count": 11
        },
        "module": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "manufacturer": "Sunpreme",
          "rating_stc": 300.25,
          "name": "SNPM GxB 300",
          "count": 11,
          "orientation": "landscape"
        },
        "face": 1,
        "pitch": 20.25,
        "string_inverter": {
          "index": 1
        },
        "shading": {
          "solar_access": {
            "annual": 87.3,
            "monthly": [
              81.1,
              82.2,
              83,
              84,
              85,
              86,
              87,
              88,
              89,
              90,
              91,
              92
            ]
          },
          "total_solar_resource_fraction": {
            "annual": 87.3
          }
        }
      }
    ],
    "string_inverters": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "manufacturer": "SMA Solar Technology AG",
        "name": "SB-7000TL-US-22 (240V)",
        "rated_power": 42000
      }
    ],
    "energy_production": {
      "up_to_date": true,
      "annual": 2550.3,
      "annual_offset": "87%",
      "monthly": [
        150.1,
        150.2,
        150,
        200,
        200,
        200,
        300,
        300,
        300,
        200,
        200,
        200
      ],
      "hourly": null
    }
  }
}

Considerations

Consider using a webhook test site like https://webhook.site to verify that your webhook subscription is live.
You can also add manual (as opposed to webhook-based) design summary retrieval. Some of our customers, for example, add a button to their internal applications' user interface to retrieve the Aurora design summary. The button triggers an API call to /tenants/{tenant_id}/designs/{design_id}/summary.