Documentation v0.3.0

GHSL Built-up Zonal Statistics

Built-up surface, volume, non-residential use, and height derived from GHSL raster data.

Granularity
City, ADM1 split, ADM2 split
Format
Parquet
Time resolution
Source epochs
Module version
v0.3.0
License
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License

Coverage and granularity#

Includes released parent cities and their ADM1 and ADM2 splits when the source raster metric is available.

9,849 of 9,849 parent cities · 1975–2025 · 160,392 rows across the package

  • City: 9,849 of 9,849 boundary IDs
  • ADM1: 387 of 387 boundary IDs
  • ADM2: 3,130 of 3,130 boundary IDs

Row key: id, version, ghsl_year

Examples in the City Explorer: Hong Kong, Busan, Lusaka.

Source: European Commission, Joint Research Centre — Global Human Settlement Layer, GHS-BUILT-S, GHS-BUILT-V and GHS-BUILT-H R2023A

Joining this data#

A Python example using GeoPandas and pandas. Replace the file paths with your local downloads. See boundary levels and join keys.

Python 
import geopandas as gpd
import pandas as pd

# Match the boundary file to the module's geographic level.
level = "PARENT"
boundaries = gpd.read_file("parent.gpkg")
observations = pd.read_parquet("ddl-ghsl-builtup.parquet")
observations = observations.loc[observations["boundary_level"].eq(level)]

joined = boundaries.merge(
    observations, on="id", how="left", validate="one_to_many"
)
print(joined.head())

Methodology#

Source raster values are summarized within each released UGC polygon with coverage-fraction weighting. Validity shares report how much of each zone contributes to each metric.

Schema#

NameTypeUnitsDescription
idstring—Parent or child city identifier.
versionstring—Boundary version.
boundary_levelstring—PARENT, ADM1, or ADM2.
ghsl_releasestring—GHSL release used for every non-null metric in the row.
ghsl_yearint64—Configured GHSL raster epoch; see Notes for details.
built_up_surface_sum_m2float64m²Area-weighted sum of GHSL built-up surface pixels across the source boundary. May be null.
built_up_surface_avg_m2float64m²Area-weighted mean of GHSL built-up surface pixels across the source boundary. May be null.
built_up_volume_sum_m3float64m³Area-weighted sum of GHSL built-up volume pixels across the source boundary. May be null.
built_up_volume_avg_m3float64m³Area-weighted mean of GHSL built-up volume pixels across the source boundary. May be null.
nonres_built_up_surface_sum_m2float64m²Area-weighted sum of GHSL built-up surface pixels classified as non-residential across the source boundary. May be null.
nonres_built_up_surface_avg_m2float64m²Area-weighted mean of GHSL built-up surface pixels classified as non-residential across the source boundary. May be null.
nonres_built_up_volume_sum_m3float64m³Area-weighted sum of GHSL built-up volume pixels classified as non-residential across the source boundary. May be null.
nonres_built_up_volume_avg_m3float64m³Area-weighted mean of GHSL built-up volume pixels classified as non-residential across the source boundary. May be null.
gross_built_up_height_avg_mfloat64mArea-weighted mean gross built-up height of GHSL built-up pixels across the source boundary May be null.
net_built_up_height_avg_mfloat64mArea-weighted mean net built-up height of GHSL built-up pixels across the source boundary. May be null.
built_up_surface_valid_coverage_sharefloat64—Share of zone area covered by valid pixels for the corresponding metric.
built_up_volume_valid_coverage_sharefloat64—Share of zone area covered by valid pixels for the corresponding metric.
nonres_built_up_surface_valid_coverage_sharefloat64—Share of zone area covered by valid pixels for the corresponding metric.
nonres_built_up_volume_valid_coverage_sharefloat64—Share of zone area covered by valid pixels for the corresponding metric.
gross_built_up_height_valid_coverage_sharefloat64—Share of zone area covered by valid pixels for the corresponding metric.
net_built_up_height_valid_coverage_sharefloat64—Share of zone area covered by valid pixels for the corresponding metric.

Notes#

  • ghsl_year is 1975/1980/1985/1990/1995/2000/2005/2010/2015/2020/2025 for Built-up surface and volume data; gross and net height come from GHS-BUILT-H, which is from 2018.
  • Selecting on ghsl_year is therefore necessary to select the appropriate raster product. 2018 will not have any built-up surface or volume data while the other years will not have any height data.
  • Filter boundary_level before aggregation so parent and administrative zones are not double counted.
  • The built-up surface and volume metrics for 2025 are projections from the 2020 data.
  • The building volume measure is mechanically constructed by multiplying the built-up surface by the net built-up height in 2018. Therefore the ratio of built up volume to surface is the same across all years.
  • Net building height is calculated as built-up volume over valid built-up surface area. Gross building height is calculated as built-up volume over the entire surface area.
  • Keep every metric with its corresponding validity-coverage share; null metrics are unavailable, not zero. A share of 0 means the raster was absent or no valid pixel fell inside the zone.

Citation#

When using these data, cite Urban Growth Center and the original source below, where applicable.

Original source

Citation 
European Commission, Joint Research Centre — Global Human Settlement Layer, GHS-BUILT-S, GHS-BUILT-V and GHS-BUILT-H R2023A. https://human-settlement.emergency.copernicus.eu/p2023Release.php

View original source

Urban Growth Center

Citation 
Development Data Lab. (2026). Urban Growth Center. https://cities.devdatalab.org/