Skip to content

Changelog

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

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.