This tutorial shows how to programmatically retrieve roof measurements from Aurora.

How It Works

On performance simulation completion, typically the last step in creating a solar design in Aurora, you can retrieve the roof summary that includes the area, area of panels, and the total length of each roof edge type on the roof.

Getting Started

To complete this tutorial, you will need:

• your Aurora tenant to be on the Custom or Business plan,
• your Aurora bearer token,
• your Aurora tenant_id,
• design_id for the design’s roof 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 via API or Webhooks Dashboard, 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.yourcomany.com/aurora_performance_simulation_webhooks?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>",
    "enabled": true
  }
}

Step 2. Retrieve roof summary on webhook receipt.

On the webhook receipt, retrieve the roof 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}/roof_summary

{
  "roofs": [
    {
      "area": 1500,
      "modules_area": 500,
      "pitch": null,
      "panels": true,
      "edges_length": {
        "eave": 100,
        "hip": 100,
        "rake": 100,
        "ridge": 100,
        "valley": 100
      },
      "faces": [
        {
          "area": 1000,
          "modules_area": 500,
          "azimuth": 75,
          "pitch": 20,
          "panels": true
        },
        {
          "area": 500,
          "modules_area": 500,
          "azimuth": 25,
          "pitch": 22,
          "panels": false
        }
      ]
    },
		{
      "area": 250,
      "modules_area": 0,
      "pitch": 5,
      "panels": false,
      "edges_length": {
        "eave": 100,
        "hip": 0,
        "rake": 50,
        "ridge": 0,
        "valley": 0
      },
      "faces": [
        {
          "area": 250,
          "modules_area": 0,
          "azimuth": 25,
          "pitch": 5,
          "panels": false
        }
      ]
    }
  ]
}

Considerations

• The roof summary API will consider a roof as a set of roof faces within 1 square foot of each other. This means that designs with multiple buildings, such as a detached garage or carport, will be returned as separate roofs. You can determine which roof is the primary structure via the panels field, which will be true for any roof that has solar panels placed on it.
• When modeling a roof in Aurora, roof edge types will be set automatically when using Aurora SmartRoof, SmartRoof AI, or Aurora Expert Design Service. When modeling a roof by hand using simple roof faces, you will need to make sure roof edge types are set manually to ensure the roof summary API returns accurate results.
• The roof summary API will return lengths for **all** roof edges on a roof, including internal or “barn” edges.