Skip to content

Changelog

All notable changes to the Urban Analytica Solar Lake Enterprise API are documented here.

0.6.4

Added 2026 to installation counts

Annual installation counts based on the Marktstammdatenregister from 2026 were added to the postcode and municipality data:

  • count_installations_2026_mastr

0.6.3

Added option for address validation to batch coordinate lookup

  • Added optional address validation to POST /buildings-coordinates.
  • Address details can now be supplied for each coordinate using the optional fields street, house_number, postcode, and locality.
  • Supplied address fields are normalized and compared with the address of the building resolved from the coordinates.
  • Validation results include field-level matches for street, house number, postcode, and locality, as well as an overall assessment: exact, probable, different, or insufficient.
  • Address validation is fully compatible with options.select; address fields used internally for validation are only returned when explicitly selected.
  • Existing requests without address information remain unchanged. The address does not influence the coordinate-based building matching.

v0.6.2

Data Model Updates

Buildings

Added new building-level and neighborhood-level attributes:

  • heritage_protection → indicates whether a building is subject to heritage protection
  • grid_share_heating_oil → share of buildings using heating oil as their main heating source in the surrounding 100 × 100 meter grid cell
  • grid_share_heating_gas → share of buildings using gas as their main heating source
  • grid_share_heating_renewable → share of buildings using renewable heating systems such as heat pumps
  • grid_share_heating_district → share of buildings using district heating
  • grid_share_heating_others → share of buildings using other heating sources
  • grid_share_heating_unknown → share of buildings with an unknown main heating source
  • grid_population → population in the surrounding 100 × 100 meter grid cell

H3, postcode, and municipality aggregates

Added the following regional aggregate fields:

  • count_heritage_buildings → number of buildings subject to heritage protection
  • share_heating_oil
  • share_heating_gas
  • share_heating_renewable
  • share_heating_district
  • share_heating_others
  • share_heating_unknown
  • population

The heating fields represent the share of buildings by main heating source within the respective H3 cell, postcode area, or municipality.

Geometry Updates

  • Fixed Polygon and MultiPolygon geometries containing holes
  • Further simplified postcode and municipality geometries for faster map rendering

Filtering

All newly added fields are supported in Mongo-like filters where applicable.

Impact

  • Building targeting can now incorporate heritage protection, local heating structure, and population context.
  • Regional analysis can compare heating technologies and population across H3 cells, postcodes, and municipalities.
  • The new fields can be combined with existing building, solar potential, ownership, and building-age filters.
  • Corrected and simplified geometries improve spatial accuracy and map-rendering performance.

v0.6.1

Fixes

  • Fixed filter validation behavior for POST /query/buildings and POST /bbox/buildings
  • Added support for filtering building queries by neighborhood/grid share fields such as grid_share_pre_1990s
  • Improved consistency and robustness of request validation for Mongo-like filters

Impact

  • Building extraction and viewport queries now support additional neighborhood-based filtering options
  • Filter validation behaves consistently regardless of filter ordering

v0.6.0

Major Infrastructure Upgrade

The Solar Lake Enterprise API has moved to a new production infrastructure and upgraded to the latest application stack.

The new setup improves:

  • interruption-free database updates
  • API stability during data refreshes
  • automated testing and validation of API behavior
  • long-term maintainability and deployment reliability

New API and Documentation URLs

The API base URL has changed:

  • Old: https://ua-api-solar-lake-enterprise.azurewebsites.net
  • New: https://api.sle.urbananalytica.de

The documentation is now available at:

  • https://docs.sle.urbananalytica.de

Clients should update their configured API base URL to the new domain. Endpoints and authentication via subscription_key remain unchanged.

Data Model Updates

Building

  • Added building_area, the area of the building footprint in square meters.
  • Fixed roof_area values. Some roof area values were slightly incorrect before this release.
  • Added municipality, which contains the official name of the municipality (Gemeinde).

Postcode and municipality aggregates

Added Marktstammdatenregister PV installation counts by system size:

  • count_pv_lt_4kwp_mastr → number of residential PV installations with less than 4 kWp capacity
  • count_pv_4_15kwp_mastr → number of residential PV installations with 4-15 kWp capacity
  • count_pv_gt_15kwp_mastr → number of residential PV installations with more than 15 kWp capacity

Others

  • Minor improvements of the OpenAPI documentation

Impact

  • Clients get a more robust API with smoother data updates and stronger test coverage.
  • Building records now expose both building footprint area and roof area.
  • Regional aggregate analysis can distinguish small, medium, and larger residential PV installations based on Marktstammdatenregister data.

v0.5.3

Overview

Coordinate-based building lookup behavior updated

The coordinate lookup endpoints now use a containment-first strategy with a limited nearest-building fallback.

Affected endpoints:

  • GET /building-coordinates
  • POST /buildings-coordinates

Updated matching logic

Previously, coordinate lookups returned a building only when the input point was inside a building footprint.

The new behavior is:

  1. First, try an exact footprint match.
  2. If no footprint contains the point, search for buildings within 2 meters.
  3. Return a fallback match only when exactly one building is within 2 meters.
  4. Otherwise, return no match.

This avoids ambiguous nearest-building assignments when multiple nearby buildings are possible matches.

Response update

POST /buildings-coordinates now includes a new match_type field on each returned item:

  • inside
  • nearest_within_2m

The GET /building-coordinates response model is unchanged and does not include match_type.

Impact

  • Coordinate lookups are more forgiving for points that fall just outside a building footprint.
  • Ambiguous near-building cases remain unresolved by design.
  • Batch clients can now distinguish exact matches from fallback matches explicitly.

v0.5.2

Overview

POST /buildings-coordinates response structure updated

The batch endpoint for resolving buildings by coordinates has been redesigned for improved usability and robustness.

New response format

Each item now includes the original input coordinate:

{
  "input_point": { "lon": 6.8592, "lat": 51.176 },
  "building": {
    "building_id": "01c02e568d94065d29c7fd9e",
    "building_height": 9,
    "pv": false
  }
}

Previously, items contained only building objects without a reference to the input coordinate.

Improved handling of invalid / out-of-scope coordinates

  • Requests no longer fail when coordinates lie outside the supported bounding box of Germany
  • Such points are now returned in missing_points
  • The endpoint now guarantees a full result set for all inputs

Example:

{
  "requested": 2,
  "returned": 1,
  "missing_points": [
    { "lon": 17.1202, "lat": 51.481 }
  ]
}

Rationale

  • Enables deterministic client-side merging of results
  • Improves robustness of batch workflows
  • Eliminates unexpected 500 Internal Server Error responses

v0.5.1

New Features

Marktstammdatenregister aggregates

Postcode and municipality aggregates were extended with photovoltaic installation metrics derived from the Marktstammdatenregister.

The following new fields are available:

  • count_pv_mastr → estimated number of residential photovoltaic installations
  • sum_kwp_mastr → total installed photovoltaic capacity in kWp
  • count_batteries_mastr → number of photovoltaic installations with battery storage

Installation year breakdown

Annual installation counts were added to enable time-based analysis of PV deployment:

  • count_installations_pre_2000_mastr
  • count_installations_2000_mastr ... count_installations_2025_mastr

These fields provide a detailed view of installation dynamics over time and allow users to distinguish between mature and recently growing markets.

Scope

The new Marktstammdatenregister fields are available for:

  • Postcodes
  • Municipalities

H3 aggregates are unchanged and do not include Marktstammdatenregister-based metrics.

Notes

  • All new fields are non-null and greater or equal to zero.
  • The _mastr suffix indicates that the values are derived from the Marktstammdatenregister and are distinct from imagery-based or model-based metrics such as count_pv.
  • The new fields are fully supported in filtering and projection for bounding box and batch endpoints.

v0.5.0

Data Model Improvements

Several building and aggregate data models were updated to improve naming consistency and better reflect the underlying sales opportunity analysis.

Building model updates

  • Replaced legacy sales_opportunity with two fields:
  • sales_opportunity_score → continuous score representing the expected sales potential
  • deal_size_class → categorical classification of potential deal sizes (super, good, other)
  • Replaced the boolean terraced_house with the categorical field building_type (values: multi-family house, terraced house, apartment building unclassified)
  • Added roof_type
  • Standardized img_date as a date field

Aggregate model updates

  • Standardized naming of sales opportunity fields across all aggregate levels (H3, postcodes, municipalities)
  • Renamed fields for consistency:
  • score_sales_opportunity → sales_opportunity_score
  • count_super_sales_opportunity → count_super_deal_size
  • count_good_sales_opportunity → count_good_deal_size
  • count_other_sales_opportunity → count_other_deal_size
  • Removed outdated field count_excellent_sales_opportunity

Updated Sales Opportunity Score

The computation of the sales opportunity score was revised to better reflect real sales potential.

The new score:

  • is based on an economic model of expected values
    • the expected value consists of two components: sales probability and sales volume
  • integrates improved building-level characteristics
  • incorporates neighborhood context
  • provides a more consistent ranking of areas and buildings for sales targeting

The score is available on:

  • Buildings (sales_opportunity_score)
  • Aggregates (H3 cells, postcodes, municipalities)

Viewport / H3 improvements

The POST /bbox/h3s endpoint now supports optionally returning empty H3 cells within the requested bounding box.

Clients can control this behavior via the new request option:

  • include_empty_cells = "no" (default) – only cells with data are returned
  • include_empty_cells = "ids" – IDs of empty cells are returned
  • include_empty_cells = "geometries" – full geometries of empty cells are returned

Empty cells are returned separately from normal items and do not contain any aggregated metrics.

This allows map clients to optionally render a complete H3 grid (for example with faint outlines or background shading) while still distinguishing between cells with data and cells without residential buildings.

Additional response fields may appear when this option is used:

  • empty_h3_ids – list of H3 cell IDs without data
  • empty_items – list of empty cells including geometry
  • empty_cells_suppressed – indicates that empty cells were not returned due to pagination (skip or limit)

This feature is particularly useful for map visualization, where empty cells can help users better interpret areas without residential buildings.

Fixes

  • Added missing regions in Brandenburg.
  • Fixed behavior of limit option for the POST-endpoint bbox/h3s.

Others

  • Increased automated test coverage and added performance benchmarks.
  • Added automated daily health and performance checks.

Impact

  • Improved consistency of data models across API entities
  • Clearer separation between sales opportunity scoring and deal size classification
  • More meaningful ranking of buildings and regions for campaign targeting
  • Further option for styling H3 viewports

v0.4.1

Improvements

  • Simplified geometries of postcode areas and municipalities

v0.4.0

Data Update & PV Classification Expansion

Expanded PV Classification Coverage

  • Photovoltaic (PV) detection and classification is now available for all federal states, instead of being limited to a single state.
  • Building-level PV indicators are now consistently available across the full dataset.

New Field: solar_thermal

  • Added a new building-level field:
    • solar_thermal → indicates whether a building has 1–3 small solar thermal collectors installed.
  • This allows differentiation between:
    • Buildings with photovoltaic systems (PV)
    • Buildings with small solar thermal installations
    • Buildings without solar systems

Updated Sales Opportunity Classification

Building Level
  • The sales opportunity classification remains:
    • super
    • good
    • other
  • Classification logic has been updated to reflect improved PV detection and expanded geographic coverage.
Aggregate Level (H3, Postcodes, Municipalities)
  • Aggregates now:
    • Count buildings by updated sales opportunity categories.
    • Include an additional count of excellent sales opportunities, incorporating neighborhood-level characteristics.
  • The regional sales opportunity score has been recalculated based on the updated building classifications and extended contextual factors.

New Field: return_on_investment

  • Added expected return on investment (%) to the building data

Impact

  • More complete and consistent PV classification nationwide.
  • Improved differentiation between PV and solar thermal installations.
  • More robust and regionally aware sales opportunity scoring.

Fix

  • Renamed share_pre1990 to share_pre_1990s in aggregate data models.

v0.3.4

Improvements

  • Improve selection mechanism of postcodes and municipalities for the GET and POST endpoints bbox/postcodes and bbox/municipalities

Fix

  • Allow missing image dates in building models

v0.3.3

Improvements

  • Improved performance and stability of building batch lookups
  • Simplified batch lookup endpoints (/buildings, /postcodes, /municipalities, /h3s, /buildings-coordinates)
    • These endpoints now behave as strict exact-ID lookups and no longer support pagination options (skip, limit), resulting in clearer and more predictable behavior.
  • Improved OpenAPI examples
    • Updated example IDs and coordinates in Swagger UI to use realistic, working values for easier testing and faster onboarding.

Fixes

  • Fixed incorrect "missing ID" reporting in H3 batch endpoint
  • Stricter validation for building IDs
    • Invalid 24-character ObjectIds now return a 422 Unprocessable Entity error instead of silently failing.

v0.3.2

Improvements

  • Improve auto-resolution option for bbox/h3

v0.3.1

Improvements

  • Refined OpenAPI documentation and schema definitions
  • Improved validation behavior for filters and request bodies
  • Improved error messaging for invalid filters and region selectors

Documentation

  • Extended MkDocs documentation
  • Added dedicated pages for:
    • Buildings
    • Aggregates
    • Bounding Boxes
    • Queries
    • Swagger / OpenAPI reference
    • Troubleshooting

v0.3.0

Major Milestones

Bulk extraction endpoint

  • Added POST /query/buildings
  • Region selector (exactly one required)
  • Mongo-like filtering
  • Field projection via options.select
  • Cursor-based pagination via options.after_building_id

This enables scalable campaign exports and large regional data extraction workflows.

Extended bounding box support

  • Added bounding box endpoints for:
  • /bbox/postcodes
  • /bbox/municipalities

These complement existing building and H3 viewport endpoints and allow fully aggregated map-based workflows across all geographic levels.

Additional improvements

  • Improved filtering validation and consistency
  • Standardized projection handling across POST endpoints
  • Performance optimizations for bounding box queries

v0.2.0

POST variants for all core endpoints

Version 0.2 introduced POST variants for all endpoints originally released in v0.1.

This enabled:

  • Field projection (options.select)
  • Pagination (skip, limit)
  • Structured request bodies
  • More scalable and flexible querying

v0.1.0

Initial release

Initial public release of the Solar Lake Enterprise API including:

  • Building lookup endpoints
  • H3 aggregate lookup
  • Postcode aggregate lookup
  • Municipality aggregate lookup
  • Simple GET bounding box endpoints
  • OpenAPI documentation via Swagger UI

For detailed endpoint documentation, see the respective sections under Endpoints.