pySpainMobility Documentation¶

Standardized access to Spain’s official mobility datasets

Welcome to the documentation for pySpainMobility, an open-source Python package for accessing and analysing mobility data published by the Spanish Ministry of Transportation and Sustainable Mobility.

Note

Please report issues or suggestions via our GitHub repository.

What you can do¶

Mobility downloads and processes origin-destination trips, overnight stays and trip-count distributions from MITMA.
Zones provides zone geometries, names, populations and territorial correspondences for interpreting those observations.
Both classes support districts and municipalities, plus large urban areas in version 2. Derived provincial products are also available.
Network analysis uses the processed flows to build sparse matrices, calculate flow measures and compare periods or spatial groupings.

Start with Mobility and Zones to obtain the data and its geographic context. The network helpers support subsequent analysis of those data.

Note

This site follows the repository’s main branch. Source changes made after a package release may appear here before they are available through pip or conda. Check the release history for the version you have installed.

Getting Started¶

Installation¶

pip install pyspainmobility

For a conda environment, create an environment with Python and pip first, then use the same pip command. Check the package metadata for the Python version required by the release you install.

Download mobility data and zones¶

This example downloads one day of municipality-level trips and loads the corresponding geometries. It requires access to the MITMA server.

from pathlib import Path
from pyspainmobility import Mobility, Zones

output = str(Path("mobility_data").resolve())
mobility = Mobility(
    version=2, zones="municipalities", start_date="2024-01-01",
    output_directory=output,
)
od = mobility.get_od_data(return_df=True)
zones = Zones(version=2, zones="municipalities", output_directory=output)
geometries = zones.get_zone_geodataframe()

print(od.head())
print(geometries.head())

od is a pandas DataFrame with dates, hours, origin/destination IDs, trip counts and total trip-kilometres. A processed Parquet file is also saved.
geometries is a GeoDataFrame indexed by the zone IDs used in od.
For other products and territorial levels, see Mobility and Zones.
When ready to analyse flows as a network, follow the small, runnable examples in Network examples. External algorithm adapters have their own installation instructions.

Citing pySpainMobility¶

If you use this package in your research, please cite:

Beneduce, C., et al. (2025). pySpainMobility: A Python Package to Access and
Manage Spanish Open Mobility Data.

BibTeX entry:

@misc{beneduce2025pyspainmobility,
   title={pySpainMobility: a Python Package to Access and Manage Spanish Open Mobility Data},
   author={Ciro Beneduce and Tania Gullón Muñoz-Repiso and Bruno Lepri and Massimiliano Luca},
   year={2025},
   eprint={2506.13385},
   archivePrefix={arXiv},
   primaryClass={cs.CY},
   url={https://arxiv.org/abs/2506.13385},
}

Documentation Contents¶

Core API

Network analysis