Postcode Aggregate Data Model¶
The Postcode object represents aggregated building and solar metrics for a German postcode area.
It is returned by:
GET /postcodePOST /postcodesGET /bbox/postcodesPOST /bbox/postcodes
Typical use cases:
- Campaign targeting by postcode
- Regional performance comparison
- Sales territory planning
- Dashboard visualizations
Core Identifiers¶
| Field | Type | Description |
|---|---|---|
postcode |
string (5) | German postcode (PLZ) |
The postcode field uniquely identifies the aggregate area and is used for:
- Batch queries
- Region selection in
/query/buildings - Exclusion in bbox workflows
Administrative Context¶
| Field | Type | Description |
|---|---|---|
municipalities |
array[string] | Municipalities within the postcode |
counties |
array[string] | Counties within the postcode |
states |
array[string] | Federal states within the postcode |
These provide context for regional analysis and cross-referencing.
Note that postcode areas can span accross multiple municipalities, counties and states.
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 opportunity score |
count_super_deal_size |
integer | Count of "super" buildings |
count_good_deal_size |
integer | Count of "good" buildings |
count_other_deal_size |
integer | Count of "other" buildings |
These are commonly used for:
- Campaign prioritization
- Heatmaps
- Regional ranking
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 postcode-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 metrics support:
- Demographic profiling
- Regional segmentation
Image Metadata¶
| Field | Type | Description |
|---|---|---|
img_year |
integer | Year of aerial imagery used for PV classification |
Geometry¶
| Field | Type | Description |
|---|---|---|
geometry |
GeoJSON Polygon | Postcode boundary geometry |
Coordinates:
- WGS84 reference system
[longitude, latitude]order
This geometry can be rendered directly in mapping applications.
Example (simplified)¶
{
"postcode": "90461",
"count_buildings": 1930,
"count_pv": 421,
"sales_opportunity_score": 0.41,
"avg_roof_area": 174,
"share_owned": 0.27,
"geometry": {
"type": "Polygon",
"coordinates": [...]
}
}
Projection-Friendly Variant¶
Some endpoints return a PostcodeOut object.
Characteristics:
- Always includes
postcode - Includes additional fields only if requested via
options.select
Example:
{
"postcode": "90461",
"count_buildings": 1930,
"sales_opportunity_score": 6.8
}
Typical Usage Patterns¶
Campaign Planning¶
Select:
postcodecount_super_deal_sizesales_opportunity_score
Regional Dashboard¶
Select:
postcodecount_buildingscount_pvshare_owned
Map Visualization¶
Select:
postcodesales_opportunity_scoregeometry
Best Practices¶
- Always use projection (
options.select) - Use postcode-level aggregation for campaign planning
- Use building-level extraction for detailed execution
Summary¶
The Postcode model provides:
- Regional identification
- Aggregated building metrics
- Solar potential averages
- Sales opportunity scoring
- Socioeconomic context
- Map-ready geometry
It is particularly well suited for campaign segmentation and postcode-based sales targeting.