Skip to content

Aggregates

Aggregate endpoints provide pre-computed regional summaries of building and PV metrics.

They are designed for:

  • Map heatmaps and zoom-dependent visualization (H3)
  • Regional targeting and sales territory analysis (Postcode, Municipality)
  • Dashboards and KPI reporting
  • Fast filtering on aggregated metrics (via bbox POST endpoints)

Aggregate types in this API:

  • H3 (hexagonal grid cells, resolutions 4–10)
  • Postcode (German PLZ areas)
  • Municipality (German municipalities identified by AGS)

Authentication: All requests require subscription_key as a query parameter.
See authentication for details.

API Base URL

https://ua-api-solar-lake-enterprise.azurewebsites.net

Aggregate objects (common patterns)

All aggregate objects share a common structure:

  • Identifier (h3_id, postcode, ags)
  • Context fields (e.g., municipalities/counties/states or lists of related IDs)
  • Aggregated metrics (counts, averages, shares, scores)
  • Geometry as GeoJSON Polygon (geometry)

Typical metrics include (availability depends on aggregate type):

  • Counts: count_buildings, count_single_family_houses, count_terraced_houses, count_pv
  • Averages: avg_roof_area, avg_radiation, avg_suitable_roof_area, avg_kwh, avg_kwp, avg_panels
  • Sales Opportunity: sales_opportunity_score, count_super_deal_size, count_good_deal_size, count_other_deal_size
  • Shares: share_owned, share_2020s, share_2010s, share_2000s, share_1990s, share_pre_1990s

For full field definitions, see the model pages:

1) H3 aggregates

H3 is the primary aggregate type for map visualization.

  • Multiple resolutions are supported (4–10)
  • Higher resolution → smaller hexagons
  • H3 IDs may be provided as decimal or hex when querying
  • Responses always return the stored decimal representation

Single lookup

Endpoint

GET /h3

Query parameters

Parameter Type Required Description
subscription_key string ✓ 90-character API key
h3_id string ✓ H3 ID (decimal or hex input accepted)

Example

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/h3?h3_id=599535981644742655&subscription_key=YOUR_KEY"

Batch lookup

Endpoint

POST /h3s

Body

Field Type Required Description
h3_ids array[string] ✓ List of H3 IDs (decimal or hex input accepted)
options.select array[string] Projection (fields to include)

The API always includes h3_id and h3_resolution in responses, even if not listed in select.

Example

curl -X POST "https://ua-api-solar-lake-enterprise.azurewebsites.net/h3s?subscription_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "h3_ids": ["599535981644742655", "599525797203542015"],
        "options": {
          "select": ["h3_id", "h3_resolution", "count_buildings", "sales_opportunity_score"]
        }
      }'

Response shape

{
  "requested": 2,
  "returned": 2,
  "missing_ids": [],
  "items": [
    {
      "h3_id": "599535981644742655",
      "h3_resolution": 5,
      "sales_opportunity_score": 6.2,
      "count_buildings": 6181
    },
    {
      "h3_id": "599525797203542015",
      "h3_resolution": 5,
      "sales_opportunity_score": 5.3,
      "count_buildings": 3164
    }
  ]
}

2) Postcode aggregates (PLZ)

Postcode aggregates summarize building & PV metrics for a German postcode area.

Single lookup

Endpoint

GET /postcode

Query parameters

Parameter Type Required Description
subscription_key string ✓ 90-character API key
postcode string ✓ German postcode (len=5)

Example

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/postcode?postcode=90461&subscription_key=YOUR_KEY"

Batch lookup

Endpoint

POST /postcodes

Body

Field Type Required Description
postcodes array[string] ✓ List of postcodes (len=5 each)
options.select array[string] Projection (fields to include)

The API always includes postcode in responses, even if not listed in select.

Example

curl -X POST "https://ua-api-solar-lake-enterprise.azurewebsites.net/postcodes?subscription_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "postcodes": ["90461", "90471"],
        "options": {
          "select": ["postcode", "count_buildings", "sales_opportunity_score", "share_owned"]
        }
      }'

Response shape

{
  "requested": 2,
  "returned": 2,
  "missing_ids": [],
  "items": [
    {
      "postcode": "90471",
      "count_buildings": 1931,
      "sales_opportunity_score": 6.3,
      "share_owned": 0.68
    },
    {
      "postcode": "90461",
      "count_buildings": 1930,
      "sales_opportunity_score": 7.9,
      "share_owned": 0.27
    }
  ]
}

3) Municipality aggregates (AGS)

Municipality aggregates summarize building & PV metrics for a German municipality.

Municipalities are identified by AGS (Amtlicher Gemeindeschlüssel, len=8).

Single lookup

Endpoint

GET /municipality

Query parameters

Parameter Type Required Description
subscription_key string ✓ 90-character API key
ags string ✓ AGS (len=8)

Example

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/municipality?ags=09564000&subscription_key=YOUR_KEY"

Batch lookup

Endpoint

POST /municipalities

Body

Field Type Required Description
ags_list array[string] ✓ List of AGS codes (len=8 each)
options.select array[string] Projection (fields to include)

The API always includes ags in responses, even if not listed in select.

Example

curl -X POST "https://ua-api-solar-lake-enterprise.azurewebsites.net/municipalities?subscription_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "ags_list": ["09564000", "09562000"],
        "options": {
          "select": ["ags", "municipality", "count_buildings", "sales_opportunity_score"]
        }
      }'

Response shape

{
  "requested": 2,
  "returned": 2,
  "missing_ids": [],
  "items": [
    {
      "ags": "09562000",
      "municipality": "Erlangen",
      "sales_opportunity_score": 8.7,
      "count_buildings": 19548
    },
    {
      "ags": "09564000",
      "municipality": "Nürnberg",
      "sales_opportunity_score": 5.6,
      "count_buildings": 73308
    }
  ]
}

Projection & performance tips

Use projection (options.select) whenever possible

Aggregate objects can include geometry and many metrics. For best performance:

  • Request only the fields you need
  • Avoid geometry unless required for mapping

Example projection:

{
  "options": {
    "select": ["postcode", "count_buildings", "sales_opportunity_score"]
  }
}

Errors

422 — Validation Error

Common causes:

  • Wrong identifier format (e.g., postcode not length 5, AGS not length 8)
  • Invalid body structure (missing list field)
  • Invalid options types

403 — Access Denied

Missing or invalid subscription_key

Empty results in batch endpoints

Batch endpoints return:

  • returned = 0 (or smaller than requested)
  • missing_ids lists identifiers not found

This is not an error and should be handled as “not found”.