H3 Aggregate Data Model

The H3 object represents aggregated building data within a single H3 hexagonal grid cell.

It is primarily used for:

• Interactive map visualizations
• Regional analysis
• Sales opportunity heatmaps
• Zoom-dependent aggregation

Returned by:

• GET /h3
• POST /h3s
• GET /bbox/h3s
• POST /bbox/h3s

---

What Is H3?

H3 is a hierarchical hexagonal spatial indexing system.

In this API:

• Each hexagon represents a geographic area
• Each hexagon aggregates building-level metrics
• Multiple resolutions are supported (4–10)
• Higher resolution → smaller hexagons

You do not need to understand H3 internals to use the API.

Further information: h3geo.org

---

Core Identifiers

Field	Type	Description
h3_id	string	Unique H3 hexagon ID (decimal representation)
h3_resolution	integer (4–10)	Resolution level of the hexagon

Notes:

• H3 IDs may be provided as decimal or hex when querying.
• Responses always return the decimal representation.

---

Geographic Context

Field	Type	Description
postcodes	array[string]	Postcodes within/intersecting the hexagon
municipalities	array[string]	Municipalities within/intersecting the hexagon
counties	array[string]	Counties within/intersecting the hexagon
states	array[string]	Federal states intersecting the hexagon

These fields describe the administrative areas overlapping the hexagon.

---

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

---

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

The sales_opportunity_score is useful for:

• Heatmaps
• Ranking regions
• Prioritizing sales focus

---

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 are aggregated across buildings within the hexagon.

---

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:

• Regional targeting
• Market segmentation
• Demographic profiling

---

Image Metadata

Field	Type	Description
img_year	integer	Year of aerial imagery used for PV classification

---

Geometry

Field	Type	Description
geometry	GeoJSON Polygon	Polygon of the H3 hexagon

Coordinates:

• WGS84 reference system
• [longitude, latitude] order

This geometry can be directly rendered in map libraries.

---

Example (simplified)

{
  "h3_id": "608532992364642303",
  "h3_resolution": 7,
  "count_buildings": 950,
  "count_pv": 247,
  "sales_opportunity_score": 8.2,
  "avg_roof_area": 104,
  "share_owned": 0.93,
  "geometry": {
    "type": "Polygon",
    "coordinates": [...]
  }
}

---

Projection-Friendly Variant

Some endpoints return an H3Out object.

Characteristics:

• Always includes h3_id
• Always includes h3_resolution
• Includes additional fields only if requested via options.select

Example:

{
  "h3_id": "608532992364642303",
  "h3_resolution": 7,
  "count_buildings": 950,
  "sales_opportunity_score": 8.2
}

---

Empty H3 Cells

When using the POST /bbox/h3s endpoint with the option:

include_empty_cells = "geometries"

the API may return additional objects representing empty H3 cells.

These objects contain only minimal information:

• h3_id
• h3_resolution
• geometry

They intentionally do not include aggregated metrics such as:

• count_buildings
• avg_roof_area
• sales_opportunity_score

This allows clients to distinguish between:

• cells containing data (items)
• cells without residential buildings (empty_items)

---

Typical Usage Patterns

Map Heatmap

Select:

• h3_id
• sales_opportunity_score
• count_buildings
• geometry

Regional Ranking

Select:

• h3_id
• sales_opportunity_score
• count_super_deal_size

Zoom-Level Switching

• Low zoom → low resolution (e.g., 4–6)
• High zoom → high resolution (7–10)

The API can auto-select a suitable resolution when omitted in bbox requests.

---

Best Practices

• Always use projection (options.select)
• Use aggregate layers for zoomed-out maps
• Switch to building layer at high zoom levels

---

Summary

The H3 model provides:

• Aggregated building metrics
• Sales opportunity scoring
• Solar potential averages
• Socioeconomic context
• Map-ready geometry

It is the recommended layer for scalable map visualization and regional analysis.