Skip to content

Solar Lake Enterprise API

The Solar Lake Enterprise API provides programmatic access to Urban Analytica’s Solar Lake dataset. It enables clients to retrieve detailed building-level data and aggregated photovoltaic (PV) suitability metrics across multiple geographic levels.

This API is designed for:

  • Map applications (interactive viewport loading)
  • Targeted building lookups
  • Batch workflows
  • Campaign and bulk extraction use cases

The API exposes consistent data structures across endpoints and supports filtering, projection, pagination, and region-based selection.

What You Can Access

The API provides two main categories of data.

1. Building-Level Data

Detailed records for individual residential buildings, including:

  • Address information (street, postcode, municipality, etc.)
  • Building characteristics (building type, building height, roof type, roof area, etc.)
  • Photovoltaic indicators (existing PV, radiation, suitable roof area, etc.)
  • Estimated technical and economic metrics:
    • Expected kWh production
    • kWp capacity
    • Panel count
    • CO₂ savings
    • Earnings, costs, amortization
  • Roof-part–level information (area, direction, pitch, kWh/m²)
  • GeoJSON geometry (building footprint, point location and roof geometries)

2. Aggregated Data

Aggregated metrics at different geographic levels:

  • H3 hexagonal grid cells
  • Postcode areas
  • Municipalities

Aggregates include:

  • Counts of buildings and PV installations
  • Sales opportunity scores
  • Average roof metrics
  • Building construction period shares
  • Socio-demographic indicators (e.g., share owned)
  • GeoJSON geometry for mapping

Core Usage Patterns

The API is structured around three primary usage patterns.

1️⃣ Map Viewport Loading

For interactive web maps:

  • GET /bbox/... endpoints
    → Simple, fast viewport loading

  • POST /bbox/... endpoints
    → Advanced viewport loading with:

    • Filtering
    • Projection (options.select)
    • Pagination
    • Incremental loading (exclude)

Bounding box queries are optimized for performance.
Results may include a small number of objects slightly outside the requested bounding box.

2️⃣ Targeted Lookups

Retrieve specific entities:

  • Building by ID
  • Building by coordinate
  • H3 cell by ID
  • Postcode or municipality by ID
  • Batch lookups (IDs or coordinates)

These endpoints are useful for detail views and drill-down workflows.

3️⃣ Bulk Extraction

For campaign or export workflows:

  • POST /query/buildings

This endpoint allows:

  • Region-based selection (e.g., postcode list, AGS list, H3 list)
  • Filtering using a Mongo-like syntax
  • Field projection
  • Cursor-based pagination for large result sets

This is the recommended approach for bulk data retrieval.

API Base URL

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

Filtering & Query Capabilities

Advanced POST endpoints support a Mongo-like filter syntax.

Supported operators:

  • Equality: $eq, $ne
  • Comparisons: $gt, $gte, $lt, $lte
  • Set membership: $in, $nin

Example:

{
  "pv": false,
  "roof_area": { "$gte": 80 },
  "building_type": { "$in": ["single-family house", "terraced house"] }
}

For best performance, request only required fields using:

{
  "options": {
    "select": ["roof_area", "pv", "sales_opportunity_score"]
  }
}

Authentication

All endpoints require a subscription_key query parameter.

Example:

GET /building?building_id=01c02e568d94065d29c7fd9e&subscription_key=YOUR_KEY

Authentication details and usage examples are documented in the Getting Started section.

Data Format & Conventions

  • Coordinates use WGS84 (longitude/latitude).
  • Geometry fields are returned as GeoJSON objects.
  • ID fields are always included in projection-based responses.
  • Pagination defaults are applied if limit is not specified.
  • Validation errors return HTTP 422.

More details are available in the Conventions section.

API Reference

A complete machine-readable specification (OpenAPI) is available in the Reference section.
Swagger UI provides the authoritative definition of all endpoints, request bodies, and response schemas.

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

Version

Current API version: 0.5.3