</br> </br>

---

</br>

Urbanity

Urbanity is a network and graph based Python package developed at the NUS Urban Analytics Lab since 2022. Urbanity helps users to automate the construction of feature rich (contextual and semantic) urban networks and graphs at any geographical scale. Through an accessible and simple to use interface, users can build analysis ready graphs and networks for diverse urban tasks.

<p align="center"> <img src="https://raw.githubusercontent.com/winstonyym/urbanity/main/images/citynetworks.png" width = 1000% alt="Logo"> <h5 align="center">Network of cities around the world</h5> </p>

Motivation

Cities are under growing pressure to become both sustainable and equitable as they confront rapid urbanization and the slow-burn realities of climate change. Meeting these challenges increasingly depends on data-driven insights—enabled by the explosion of large-scale geospatial data and advances in computational methods—that reveal how cities grow, function, and evolve. Yet our review finds that most modeling efforts still develop in disciplinary silos , leaving them ill-equipped to address complex, interlocking issues such as housing, transportation, and climate resilience.

At the same time, graphs are ubiquitous across multiple domains from co-citation graphs to biological graphs of proteins and molecules. Graphs allow us a powerful way to represent diverse types of complex systems in a robust manner. Building on this insight, we introduce urban graph analytics---an extension of traditional street networks---that enables more integrated and interpretable urban science.

<p align="center"> <img src="https://raw.githubusercontent.com/winstonyym/urbanity/main/images/citygraphs.png" width = 1000% alt="Logo"> <h5 align="center">Graphs of cities around the world</h5> </p>

Our position paper describing the conceptual motivation for urban graph analytics was presented at the The 19th International Conference on Computational Urban Planning & Urban Management on 25 June 2025, UCL London.

What can I do with Urbanity?

We demonstrate how you can conduct a diverse range of urban analytical tasks (such as graph machine learning, network assortativity analysis, and benchmarking across cities) with Urbanity. Check out the documentation and examples/tutorials in the documentation site examples.

Sample dataset and notebooks to follow examples can be accessed at this repository.

Use cases

One popular use case for Urbanity is for graph machine learning on urban networks. These tasks are consistent with GraphML literature and include node level, edge level, and graph level predictive tasks.

• Road network classification
• Building operating energy prediction

Questions concerning use cases can be directed to the author: winstonyym@u.nus.edu </br>

Tutorials

Generate Feature Rich Urban Networks

Generate Graph ML Ready Graphs

Building Use Classification

Features

• Rapid city-scale network and graph generation
• Seamless computation of metric, topological, contextual, and semantic network indicators
• Node and edge spatial context computation
• Areal statistics for arbitrary urban subzones
• Validity checks for OpenStreetMap attribute completeness (no. of buildings, percentage with height, percentage with levels, etc.)
• Primal planar, dual, and spatial graph generation
• Conversion to graph machine learning ready formats
• Generating graph machine learning ready graphs

Global Graph Dataset

To facilitate quicker access to city scale graphs, we provide a set of analysis-ready graphs for many cities with a wide set of useful urban attributes. Users can directly download these datasets and use them quickly in their workflows:

• Global Feature Rich Urban Networks
• Global Urban Graph Dataset

Designed for urban planners

Urbanity is designed in an object-oriented approach that parallels the urban planning process. The urban data science pipeline starts with a base map which users can use to explore their site. Subsequently, there are two ways to specify geographical area of interest: 1) drawing with the polygon and box tools provided; or 2) providing your own polygon shapefiles (all common formats .shp/.geojson are supported).

Towards exploring complexities underlying urban systems and facilitating comparative study between cities, Urbanity is developed to facilitate downstream descriptive, modelling, and predictive urban analytical tasks.

Quickstart

Urbanity is built on several geospatial packages (e.g., GeoPandas, ipyleaflet, rasterio, etc.,) that are best compiled through conda-forge. To speed up installation, heavy OpenStreetMap dependency pyrosm is now optional.

We provide an environment.yml file for users to create their own conda environment. Please follow the steps below to ensure proper installation:

1. Navigate to a location of choice (e.g., Desktop or project folder).
2. Download environment.yml and setup.sh file and place it at the location of choice (Step 1).
3. Open up a terminal/command prompt and input the following command:

$ chmod +x ./setup.sh
$ ./setup.sh

Urbanity includes optional integration with external APIs

Google Earth Engine

Google earth engine (GEE) API and community catalog provides open access to thousands of remote sensing data layers. Academic users can register for a free Google Earth Engine research account here

Authenticate Google Earth Engine

import ee
ee.Authenticate()
ee.Initialize(project='your-project-id')

Mapillary

Mapillary hosts the world's largest selection of crowdsourced streetview imagery which covers most cities in the world. Request for an access token here

Mapbox

Mapbox hosts a collection of freely available high resolution satellite imagery with global coverage. Request for an access token in account developer page here

</br>

(Optional) External API integration

$ touch .env

Open the .env file and fill out your registered API keys

MAPILLARY_API_SECRET=MLY|XXXXXXXXXXXXXXX|XXXXXXXXXXXXXXX
MAPILLARY_API_TOKEN=MLY|XXXXXXXXXXXXXXX|XXXXXXXXXXXXXXX
MAPBOX_API_TOKEN=pk.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

(Optional) For JupyterLab / JupyterNotebook users, you can additionally add a notebook kernel via:

$ python -m ipykernel install --user --name=urbanity
$ jupyter lab

Citation

If you use Urbanity in your work, please cite: <br></br> [1] Yap, W., Stouffs, R. & Biljecki, F. Urbanity: automated modelling and analysis of multidimensional networks in cities. npj Urban Sustain 3, 45 (2023). https://doi.org/10.1038/s42949-023-00125-w

[2] Yap, W., Chang, J. H., & Biljecki, F. (2023). Incorporating networks in semantic understanding of streetscapes: Contextualising active mobility decisions. Environment and Planning B: Urban Analytics and City Science, 50(6), 1416-1437. https://doi.org/10.1177/23998083221138832

[3] Yap, W., Biljecki, F. A Global Feature-Rich Network Dataset of Cities and Dashboard for Comprehensive Urban Analyses. Sci Data 10, 667 (2023). https://doi.org/10.1038/s41597-023-02578-1

[4] Yap, W., Biljecki, F. (2025, June). Leveraging Urban Graphs for Multi-Scalar Urban Analytics. In 19th International Conference on Computational Urban Planning & Urban Management, CUPUM 2025. https://doi.org/10.17605/OSF.IO/ABYQH

[5] Yap, W., Wu, A. N., Miller, C., & Biljecki, F. (2025). Revealing building operating carbon dynamics for multiple cities. Nature Sustainability, 8(1), 1199-1210. https://doi.org/10.1038/s41893-025-01615-8

License

urbanity was created by winstonyym. It is licensed under the terms of the MIT license.

Credits

• Logo design: April Zhu
• Colab notebooks: Kunihiko Fujiwara
• OSMnx Github