browsing byresearchposts

The cityseer Python package for pedestrian-scale network-based urban analysis

Online documentation is available from and the github repository is available at See this blog post for some background reading on how the package came about.


cityseer-api is a Python package consisting of computational tools for fine-grained street network and land-use analysis, helpful in assessing the morphological precursors to vibrant neighbourhoods. It is underpinned by network-based methods developed from the ground-up for localised urban analysis at the pedestrian scale to provide contextually specific metrics for any given street-front location. cityseer-api computes a variety of node or segment-based network centrality methods, land-use accessibility and mixed-use measures, and statistical aggregations. Aggregations are computed dynamically — directly over the street network while taking the direction of approach into account — and can optionally incorporate spatial impedances and network decomposition to accentuate spatial precision. The use of Python facilitates compatibility with popular computational tools for network manipulation (NetworkX), geospatial topology (shapely), and the numpy stack of scientific packages. The provision of graph cleaning tools aids the incorporation of Open Street Map derived network topologies. Underlying loop-intensive algorithms are implemented in Numba JIT compiled code so that the methods scale efficiently to larger networks.


cityseer-api is a network-based spatial analysis package for contextually precise urban analytic workflows. The implemented methods are primarily intended for application at pedestrian walking tolerances, commonly up to 800m and infrequently exceeding 1600m. cityseer-api provides distance-weighted metrics that can — optionally — be combined with network ‘decomposition’ to generate observations at an exceptionally high spatial resolution. These forms of contextually sensitive urban analytic workflows aid the comparative analysis of urban development while providing a tool to gauge the impact of design decisions on considerations such as walkability or pedestrian accessibility to land-uses for a given location.

Computational methods for network-based centrality and land-use analysis rely extensively on shortest-path algorithms, presenting substantial computational complexity due to nested computational loops. Pure Python network-based measures, such as those implemented in NetworkX (Hagberg et al. 2008), can consequently become prohibitively slow if applied to street networks for larger towns and cities. Computational speed improvements can be attained through the use of Python packages such as Graph-Tool (Peixoto 2014), which wrap underlying optimised C or C++ code libraries, and this was the approach adopted by the author before the development of cityseer-api. Nevertheless, whereas high-performance graph-analysis packages can be co-opted for generic forms of network analysis, they do not necessarily offer the degree of extensibility required for convenient experimentation with the underlying algorithmic considerations more specific to analytics from an urbanist’s perspective. Accordingly, attempts to co-opt existing off-the-shelf packages for unanticipated purposes incurs a sufficient degree of code complexity to create a bottleneck to furthered development while causing computational speed advantages to dissipate. This conundrum prompted the development of the codebase that has become formalised as the cityseer-api package, adopting an approach leveraging pure Python and NumPy (Harris et al. 2020), but with computationally intensive algorithms optimised through use of Numba JIT (just-in-time) compilation (Lam et al. 2015). This strategy allows for wide-ranging experimentation and the ensuing customisation of underlying algorithms, thereby facilitating code abstraction, reducing duplicitous code, improving code maintenance through ongoing development and upgrade cycles, and adopting paradigms specifically suited to pedestrian-scale urban analysis. This approach has allowed for a range of particular issues to be addressed:

cityseer-api includes a variety of convenience methods for the general preparation of networks and their conversion into (and out of) the lower-level data structures used by the underlying algorithms. These graph utility methods are designed to work with NetworkX to facilitate ease of use. Broad overviews of these methods and how they can be used as part of typical workflows are provided in the paper, and in the detailed package documentation directly available at

A complement of code tests maintains the integrity of the code-base through general package maintenance and upgrade cycles and, as of the time of writing, is based on Python 3.9. Shortest-path algorithms, harmonic closeness, and betweenness algorithms are tested against NetworkX. Mock data and test plots have been used to visually confirm the intended behaviour for divergent simplest and shortest-path heuristics and for testing the assignment of data points to nearby network nodes given various scenarios.

Please see the linked preprint paper for additional information.

Cooper, C.H.V., 2015. Spatial localization of closeness and betweenness measures: a self-contradictory but useful form of network analysis. International Journal of Geographical Information Science, 29(8), pp.1293–1309. Available at:
Hagberg, A.A., Schult, D.A. & Swart, P.J., 2008. Exploring Network Structure, Dynamics, and Function using NetworkX. In G. Varoquaux, T. Vaught, & J. Millman, eds. Proceedings of the 7th Python in Science Conference. Pasadena, CA USA, pp. 11–15.
Harris, C.R. et al., 2020. Array programming with NumPy. Nature, 585(7825), pp.357–362. Available at:
Hillier, B. & Hanson, J., 1984. The Social Logic of Space, Cambridge: Cambridge University Press.
Lam, S.K., Pitrou, A. & Seibert, S., 2015. Numba: a LLVM-based Python JIT compiler. In Proceedings of the Second Workshop on the LLVM Compiler Infrastructure in HPC. Austin Texas: ACM Press, pp. 1–6. Available at:
Peixoto, T.P., 2014. The graph-tool python library. figshare. Available at:
Porta, S., Crucitti, P. & Latora, V., 2006. The Network Analysis of Urban Streets: A Primal Approach. Environment and Planning B: Planning and Design, 33, pp.705–725. Available at:
Turner, A., 2007. From axial to road-centre lines: a new representation for space syntax and a new model of route choice for transport network analysis. Environment and Planning B: Planning and Design, 34, pp.539–555. Available at:
Copyright © 2014-present Gareth Simons