metrosp: metro ridership in São Paulo

This package distributes demand data from the São Paulo metro system inside R. The data covers 2012 to 2026 and comes from several operators. Most of it is already public, but it is scattered across poorly structured CSV and PDF files.

METRÔ publishes lines 1, 2, 3, 15, and line 5 through July 2018 on its open data portal. Line 4, and line 5 from August 2018 onward, come from the Insper Dataverse.

All datasets are tibble objects bundled with the package, so they load without a download. The data is cleaned and standardized to make it easier to work with.

Line coverage

The package covers every metro line in São Paulo. Commuter train (CPTM) demand is not included, though train lines and stations do appear in the spatial datasets.

Coverage refers to line_entries_monthly, which is missing July 2017 for every METRO-sourced line. The other datasets start later for some lines. The Metro Demand Data article gives the coverage window of every dataset by line.

Installation

Install the released version from CRAN.

install.packages("metrosp")

The development version is on R-universe.

install.packages('metrosp', repos = c('https://viniciusoike.r-universe.dev', 'https://cloud.r-project.org'))

Datasets

Four datasets carry the demand data: line_entries_monthly, line_transported_monthly, station_transported_monthly, and station_entries_daily. The rest are auxiliary tables that support analysis and visualization.

Every demand dataset counts individual passengers. The data dictionary defines every column, and the Metro Demand Data article covers coverage windows, source defects, and the conventions behind the numbers.

Data vintage

The bundled data is a fixed snapshot, current through July 2026. It is regenerated when the column schema changes, not when new months are published, so examples and analyses stay reproducible across package versions. METRÔ publishes on an irregular schedule and revises past years, so these numbers drift from the source over time.

read_metro_demand() reads the newer data. Every pipeline run publishes a fresh build of the four demand datasets to the rolling data-latest release, plus a dated tag for that month. A later run in the same month replaces the dated batch, so monthly vintages are revisable.

# Latest published data
entrance <- read_metro_demand("line_entries_monthly")

# A monthly batch, so an analysis can name the vintage it used
entrance_sep <- read_metro_demand("line_entries_monthly", vintage = "2026-09")

Downloads use the platform-specific user cache returned by tools::R_user_dir(). Use metrosp_cache() to inspect it, metrosp_cache_clear() to remove files, or cache = FALSE to keep a download only for the current session. Columns match the bundled datasets, so the same code works with either.

Usage

The data is bundled with the package, meaning it works out of the box and doesn’t rely on internet connection. To use a dataset simply call its name.

library(metrosp)
# To work with spatial datasets (rail lines and stations)
library(sf)
# For better tables load dplyr or tibble
library(dplyr)

# Passenger entries by line
line_entries_monthly

# Station-level weekday averages
station_transported_monthly

# Spatial line routes
rail_lines

Explorer dashboard

An interactive dashboard for browsing and downloading these datasets lives in a separate repository: metrosp-explorer.

Data sources

• METRÔ: Companhia do Metropolitano de São Paulo (METRO).
• Lines 4/5 data: Insper Dataverse (ViaQuatro / ViaMobilidade).
• Spatial data: GeoSampa, Prefeitura de São Paulo.

Next steps

This package is still in development. While the datasets are stable and checked on every new release, there may still be errors. If you find any, please open an issue.