Municipality Aggregate Data Model¶
The Municipality object represents aggregated building and solar metrics for a German municipality.
Each municipality is identified by its official AGS (Amtlicher Gemeindeschlüssel).
Returned by:
GET /municipalityPOST /municipalitiesGET /bbox/municipalitiesPOST /bbox/municipalities
Typical use cases:
- Regional dashboards
- Campaign planning
- Sales territory analysis
- Administrative reporting
Reference AGS: Gemeinsames Statistikportal des Bundes und der Länder
Core Identifiers¶
| Field | Type | Description |
|---|---|---|
ags |
string (8) | Official municipality key (Amtlicher Gemeindeschlüssel) |
municipality |
string | Name of the municipality |
county |
string | Landkreis |
state |
string | Bundesland |
The ags field uniquely identifies a municipality and is used for:
- Batch queries
- Campaign region selection
- Exclusion in bbox queries
Administrative Context¶
| Field | Type | Description |
|---|---|---|
postcodes |
array[string] | Postcodes within the municipality |
This allows linking municipality-level aggregates with postcode-level workflows.
Building Counts¶
| Field | Type | Description |
|---|---|---|
count_buildings |
integer | Number of residential buildings |
count_single_family_houses |
integer | Number of single-family houses |
count_terraced_houses |
integer | Number of terraced houses |
count_apartment_buildings |
integer | Number of apartment buildings |
count_unclassified_buildings |
integer | Number of unclassified buildings |
count_pv |
integer | Number of buildings with PV installed |
count_solar_thermal |
integer | Number of buildings with solar thermal collectors installed |
count_heritage_buildings |
integer | Number of buildings subject to heritage protection |
These metrics are aggregated from building-level data.
Marktstammdatenregister Metrics¶
| Field | Type | Description |
|---|---|---|
count_pv_mastr |
integer | Estimated number of residential photovoltaic installations according to the Marktstammdatenregister |
count_pv_lt_4kwp_mastr |
integer | Number of residential photovoltaic installations with less than 4 kWp capacity according to the Marktstammdatenregister |
count_pv_4_15kwp_mastr |
integer | Number of residential photovoltaic installations with 4-15 kWp capacity according to the Marktstammdatenregister |
count_pv_gt_15kwp_mastr |
integer | Number of residential photovoltaic installations with more than 15 kWp capacity according to the Marktstammdatenregister |
sum_kwp_mastr |
integer | Total installed photovoltaic capacity in kWp according to the Marktstammdatenregister |
count_batteries_mastr |
integer | Number of photovoltaic installations with battery storage according to the Marktstammdatenregister |
count_installations_pre_2000_mastr |
integer | Number of photovoltaic installations commissioned before 2000 according to the Marktstammdatenregister |
count_installations_2000_mastr |
integer | Number of photovoltaic installations commissioned in 2000 according to the Marktstammdatenregister |
count_installations_2001_mastr |
integer | Number of photovoltaic installations commissioned in 2001 according to the Marktstammdatenregister |
count_installations_2002_mastr |
integer | Number of photovoltaic installations commissioned in 2002 according to the Marktstammdatenregister |
count_installations_2003_mastr |
integer | Number of photovoltaic installations commissioned in 2003 according to the Marktstammdatenregister |
count_installations_2004_mastr |
integer | Number of photovoltaic installations commissioned in 2004 according to the Marktstammdatenregister |
count_installations_2005_mastr |
integer | Number of photovoltaic installations commissioned in 2005 according to the Marktstammdatenregister |
count_installations_2006_mastr |
integer | Number of photovoltaic installations commissioned in 2006 according to the Marktstammdatenregister |
count_installations_2007_mastr |
integer | Number of photovoltaic installations commissioned in 2007 according to the Marktstammdatenregister |
count_installations_2008_mastr |
integer | Number of photovoltaic installations commissioned in 2008 according to the Marktstammdatenregister |
count_installations_2009_mastr |
integer | Number of photovoltaic installations commissioned in 2009 according to the Marktstammdatenregister |
count_installations_2010_mastr |
integer | Number of photovoltaic installations commissioned in 2010 according to the Marktstammdatenregister |
count_installations_2011_mastr |
integer | Number of photovoltaic installations commissioned in 2011 according to the Marktstammdatenregister |
count_installations_2012_mastr |
integer | Number of photovoltaic installations commissioned in 2012 according to the Marktstammdatenregister |
count_installations_2013_mastr |
integer | Number of photovoltaic installations commissioned in 2013 according to the Marktstammdatenregister |
count_installations_2014_mastr |
integer | Number of photovoltaic installations commissioned in 2014 according to the Marktstammdatenregister |
count_installations_2015_mastr |
integer | Number of photovoltaic installations commissioned in 2015 according to the Marktstammdatenregister |
count_installations_2016_mastr |
integer | Number of photovoltaic installations commissioned in 2016 according to the Marktstammdatenregister |
count_installations_2017_mastr |
integer | Number of photovoltaic installations commissioned in 2017 according to the Marktstammdatenregister |
count_installations_2018_mastr |
integer | Number of photovoltaic installations commissioned in 2018 according to the Marktstammdatenregister |
count_installations_2019_mastr |
integer | Number of photovoltaic installations commissioned in 2019 according to the Marktstammdatenregister |
count_installations_2020_mastr |
integer | Number of photovoltaic installations commissioned in 2020 according to the Marktstammdatenregister |
count_installations_2021_mastr |
integer | Number of photovoltaic installations commissioned in 2021 according to the Marktstammdatenregister |
count_installations_2022_mastr |
integer | Number of photovoltaic installations commissioned in 2022 according to the Marktstammdatenregister |
count_installations_2023_mastr |
integer | Number of photovoltaic installations commissioned in 2023 according to the Marktstammdatenregister |
count_installations_2024_mastr |
integer | Number of photovoltaic installations commissioned in 2024 according to the Marktstammdatenregister |
count_installations_2025_mastr |
integer | Number of photovoltaic installations commissioned in 2025 according to the Marktstammdatenregister |
count_installations_2026_mastr |
integer | Number of photovoltaic installations commissioned in 2026 according to the Marktstammdatenregister |
These metrics complement the building-derived count_pv field. While count_pv counts buildings with detected PV installations in Urban Analytica's own data, the _mastr fields are based on the Marktstammdatenregister and represent registered residential photovoltaic installations.
The capacity-bucket fields (count_pv_lt_4kwp_mastr, count_pv_4_15kwp_mastr, count_pv_gt_15kwp_mastr) split registered residential PV installations by system size.
The two approaches differ conceptually and methodologically, which can lead to systematic differences in the counts.
Urban Analytica’s count_pv is based on image-based detection and is strictly limited to clearly identified residential buildings. This results in a conservative estimate that focuses on high-confidence residential rooftop systems.
In contrast, the Marktstammdatenregister does not explicitly classify installations as residential. Therefore, residential PV systems are approximated using size-based heuristics. In particular, installations are considered residential if they meet criteria such as:
- limited unit size (e.g. ≤ 25 kWp per unit)
- limited total capacity per location (e.g. 2–25 kWp)
- limited number of units per location (e.g. ≤ 5)
These rules are designed to capture typical residential installations, but they may also include small commercial or mixed-use systems.
As a result:
_mastrcounts are typically higher thancount_pv_mastrmay include non-residential edge cases (e.g. small commercial systems)count_pvmay miss installations due to detection limits (e.g. occlusion, outdated imagery, PV installations on non-residential buildings)
Both perspectives are complementary and can be used together to better understand photovoltaic adoption.
Sales Opportunity Metrics¶
| Field | Type | Description |
|---|---|---|
sales_opportunity_score |
number (0–10) | Aggregated sales opportunity score |
count_super_deal_size |
integer | Count of buildings with potentially "super" deal size |
count_good_deal_size |
integer | Count of buildings with potentially "good" deal size |
count_other_deal_size |
integer | Count of buildings with "other" deal size |
These metrics are commonly used for:
- Regional prioritization
- Territory performance analysis
- Campaign targeting
Solar Potential Metrics¶
| Field | Type | Description |
|---|---|---|
avg_radiation |
integer | Average annual radiation (kWh/m²) |
avg_roof_area |
integer | Average roof area (m²) |
avg_suitable_roof_area |
integer | Average usable roof area (m²) |
avg_kwh |
integer | Average expected production (kWh) |
avg_kwp |
integer | Average expected capacity (kWp) |
avg_panels |
integer | Average number of panels |
avg_building_height |
number | Average number height of buildings (m) |
These values represent municipality-wide averages.
Socioeconomic / Building Age / Heating Metrics¶
| Field | Type | Description |
|---|---|---|
share_owned |
number (0–1) | Share of owner-occupied buildings |
share_2020s |
number (0–1) | Share built in 2020s |
share_2010s |
number (0–1) | Share built in 2010s |
share_2000s |
number (0–1) | Share built in 2000s |
share_1990s |
number (0–1) | Share built in 1990s |
share_pre_1990s |
number (0–1) | Share built before 1990 |
share_heating_oil |
number (0–1) | Share of buildings using heating oil as their main heating source |
share_heating_gas |
number (0–1) | Share of buildings using gas as their main heating source |
share_heating_renewable |
number (0–1) | Share of buildings using renewable heating systems such as heat pumps |
share_heating_district |
number (0–1) | Share of buildings using district heating |
share_heating_others |
number (0–1) | Share of buildings using other heating sources |
share_heating_unknown |
number (0–1) | Share of buildings with an unknown main heating source |
population |
integer | Population in the municipality |
These support:
- Demographic profiling
- Regional comparison
- Heating-system analysis
Image Metadata¶
| Field | Type | Description |
|---|---|---|
img_year |
integer | Year of aerial imagery used for PV classification |
Geometry¶
| Field | Type | Description |
|---|---|---|
geometry |
GeoJSON Polygon | Municipality boundary geometry |
Coordinates:
- WGS84 reference system
[longitude, latitude]order
This geometry can be rendered directly in mapping applications.
Example (simplified)¶
{
"ags": "09564000",
"municipality": "Nürnberg",
"county": "Nürnberg",
"state": "Bayern",
"count_buildings": 73308,
"count_pv": 12500,
"sales_opportunity_score": 8.4,
"avg_roof_area": 136,
"share_owned": 0.57,
"population": 523026,
"share_heating_district": 0.22,
"geometry": {
"type": "Polygon",
"coordinates": [...]
}
}
Projection-Friendly Variant¶
Some endpoints return a MunicipalityOut object.
Characteristics:
- Always includes
ags - Includes additional fields only if requested via
options.select
Example:
{
"ags": "09564000",
"count_buildings": 73308,
"sales_opportunity_score": 8.4
}
Typical Usage Patterns¶
Administrative Dashboards¶
Select:
agsmunicipalitycount_buildingscount_single_family_housescount_terraced_housessales_opportunity_score
Sales Territory Planning¶
Select:
agssales_opportunity_scorecount_super_deal_sizeshare_ownedpopulationshare_heating_gas
Map Visualization¶
Select:
agssales_opportunity_scoregeometry
Best Practices¶
- Always use projection (
options.select) - Use municipality-level aggregation for large-scale reporting
- Use building-level extraction for detailed campaign execution
Summary¶
The Municipality model provides:
- Administrative identification
- Aggregated building metrics
- Solar potential averages
- Sales opportunity scoring
- Socioeconomic context
- Heating context
- Map-ready geometry
It is well suited for strategic planning, regional comparison, and campaign prioritization.