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 |
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 |
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 |
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 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 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 |
These support:
- Demographic profiling
- Regional comparison
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,
"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_owned
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
- Map-ready geometry
It is well suited for strategic planning, regional comparison, and campaign prioritization.