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 across 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 |
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 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 / 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 postcode area |
These metrics support:
- Demographic profiling
- Regional segmentation
- 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 | 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": 4.5,
"avg_roof_area": 174,
"share_owned": 0.27,
"population": 4350,
"share_heating_renewable": 0.18,
"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_ownedpopulationshare_heating_renewable
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
- Heating context
- Map-ready geometry
It is particularly well suited for campaign segmentation and postcode-based sales targeting.