pySpainMobility: Unlocking Spanish Open Mobility Data for Spatial Inequality Research

Human mobility shapes access to resources, opportunities, and services, making movement data a powerful lens for studying spatial and social inequality. Yet despite the growing availability of official open mobility datasets, their research potential is rarely realized because the technical overhead of retrieving, harmonizing, and processing them often crowds out substantive analysis. To address this, we introduce pySpainMobility, a Python package that automates the retrieval and harmonization of Spain's open mobility data across spatial resolutions and demographic strata, streamlining national-scale, reproducible analysis. Using the package, we study income-stratified mobility inequality across Spain's inter-province network, drawing on district-level origin-destination flows for four representative weeks spanning the seasons of 2023. We construct income-specific mobility layers and show that socioeconomic stratification is deeply embedded in the structure of the national mobility system: low-income mobility is disproportionately concentrated in a narrow set of destinations and shorter in spatial reach, while high-income groups access a broader and more distant hierarchy of destinations. Low- and high-income layers consistently follow weakly aligned destination hierarchies across seasons, indicating that income groups navigate distinct mobility geographies rather than a shared one at different volumes. We further show that destination provinces themselves differ systematically in the income composition of the travelers they receive, with several provinces attracting arrivals disproportionately skewed toward one income group relative to the national seasonal baseline. These results demonstrate how official open mobility data, combined with accessible tooling, can be operationalized to reveal spatial inequality as a structural property of national mobility networks.