DATASUS - Vaccination Data (SI-PNI)

The load_vaccines() function provides access to the National Immunization Program Information System (SI-PNI). This dataset contains records of vaccine doses applied across Brazil, allowing for the analysis of immunization coverage and public health strategies.

The load_vaccines function offers the following parameters:

  1. year: A numeric value indicating the year of the data to be downloaded.
  2. state: A string indicating the Brazilian state abbreviation for which the data should be downloaded (e.g., "SP", "RJ", "AC").
  3. strategy: Specifies the vaccination strategy.
  4. product: Specifies the specific vaccine or immunobiological product (e.g., "BCG - BCG", "Febre amarela - FA", "Hepatite B - HB").
  5. dose: A character vector indicating the dose categories that were selected when downloading the data.
  6. data: Optional path to a local .xls or .xlsx file downloaded manually.
  7. language: A string indicating the desired language of variable names and labels.

Data ingestion modes

The function supports two distinct data ingestion modes, depending on the availability and stability of the official SI-PNI portals:

  1. Automated web scraping of the legacy SI-PNI Web system (for data up to 2022).
  2. Manual data ingestion, where the user downloads the data directly from the official DATASUS dashboard and the function performs only cleaning, harmonization, and standardization (optional for data up to 2022, but required for 2023 onwards).

Both modes produce a fully harmonized output, consistent with the historical SI-PNI data structure.

1. Automated web scraping (1994 - 2022)

For historical data (1994–2022), load_vaccines() can automatically retrieve consolidated vaccination data directly from the legacy SI-PNI Web portal using web scraping techniques.

This mode:

  1. Requires a stable internet connection.
  2. Depends on the availability and responsiveness of the SI-PNI Web system.
  3. Uses a Chrome-based browser via the chromote package.

No manual intervention is required from the user.

2.1. Manual download (1994 - 2022)

From 1994 to 2022, vaccination data are available through the legacy SI-PNI Web system. Although load_vaccines() can retrieve these data automatically via web scraping, users may also choose to manually download the data and provide the file to the function for harmonization.

In this case, load_vaccines() will perform only the cleaning, harmonization, and standardization steps, ensuring that the resulting dataset follows the same structure as the automatically collected data.

This approach can be useful when:

  1. The SI-PNI website is unstable or slow
  2. The user already possesses previously downloaded data
  3. The user prefers manual control over the data retrieval process

Step-by-step instructions for manual download

  1. Access the DATASUS vaccination dashboard:
    https://sipni.datasus.gov.br/si-pni-web/faces/relatorio/consolidado/dosesAplicadasMensal.jsf

  2. In the filter panel, fill only the following fields:

  • UF
  • Ano
  • Estratégia
  • Produto
  • Dose

(Do not apply any additional filters)

  1. Select the option “Totalizar por Município”.

  2. Click “Pesquisar” and wait for the table to be generated.

  3. Below the table, locate the section “Exportar Para o Formato” and click on the first icon (.xls) to download the data.

  4. Provide the downloaded file to load_vaccines() using the data argument.

2.2. Manual download (2023 - present)

From 2023 onwards, vaccination data are published exclusively through the new DATASUS interactive dashboard. Due to technical and legal constraints, automated scraping is not supported for this platform.

In this case, load_vaccines() will perform only the cleaning, harmonization, and standardization steps.

Step-by-step instructions for manual download

  1. Access the DATASUS vaccination dashboard:
    https://infoms.saude.gov.br/extensions/SEIDIGI_DEMAS_VACINACAO_CALENDARIO_NACIONAL_OCORRENCIA/SEIDIGI_DEMAS_VACINACAO_CALENDARIO_NACIONAL_OCORRENCIA.html

  2. In the filter panel, fill only the following fields:

  • UF Ocorrência
  • Ano Vacina
  • Estratégia de Vacinação
  • Imunobiológico
  • Doses

(Do not apply any additional filters)

  1. Switch to the “Tabelas” tab.

  2. In the table configuration:

  • Add the variable “Tipo Dose” (at the left side) to the table.
  • Expand all rows to display the full table.

  1. Click “Baixar Dados” and save the file in .xlsx format.

  2. Provide the downloaded file to load_vaccines() using the data argument.

Interactive Mode:

If you are unsure of the exact strings for strategy or product, you can run the function providing only the year and state. The function will provide an interactive menu in the R console for you to choose from valid combinations. (The interactive mode is only valid for data between 1994 and 2022)

Examples:

library(datazoom.saude)

# Download data for Yellow Fever via web scraping (Routine strategy) - State of Acre, 2020
data_fa_acre <- load_vaccines(
  year = 2020,
  state = "AC",
  strategy = "Rotina",
  product = "Febre amarela - FA",
  language = "eng"
)

# Download data for BCG via web scraping (Private Service strategy) - State of São Paulo, 2018
data_bcg_sp <- load_vaccines(
  year = 2018,
  state = "SP",
  strategy = "Serviço Privado",
  product = "BCG - BCG",
  language = "pt"
)

# Download data for Trivalent Influenza using a manually downloaded file (Blockade strategy) - State of Acre, 2018
data_fa_acre <- load_vaccines(
  year = 2018,
  state = "AC",
  strategy = "Bloqueio",
  product = "Influenza Trivalente - FLU3V",
  doses = c("D1", "DU", "REV", "DI"), # required for data up to 2022
  data = "C:/path/to/downloaded_file.xls", #.xls
  language = "eng"
)

# Download data for Trivalent Influenza using a manually downloaded file (Blockade strategy) - State of Minas Gerais, 2024
data_fa_acre <- load_vaccines(
  year = 2024,
  state = "MG",
  strategy = "Bloqueio",
  product = "Influenza Trivalente - FLU3V",
  doses = NULL, # not required for data 2023 onwards
  data = "C:/path/to/downloaded_file.xls", #.xls
  language = "pt"
)

# Example of calling the function to trigger interactive selection - State of Minas Gerais, 2010
data_interactive <- load_vaccines(
  year = 2010,
  state = "MG",
  language = "pt")

Technical Note:

  1. Automated web scraping relies on the legacy SI-PNI Web system and is subject to instability, timeouts, and unexpected failures.
  2. For recent years (2023 onwards), manual download via the DATASUS dashboard is the only supported data source.
  3. Regardless of the ingestion mode, load_vaccines() always returns a harmonized dataset with consistent variable names, dose categories, and structure.

Important: For the web scraping mode, please be aware that the SI-PNI website (https://sipni.datasus.gov.br/si-pni-web/faces/relatorio/consolidado/dosesAplicadasMensal.jsf) often experiences significant instability. This may result in connection timeouts, slow response times, or unexpected errors during the scraping process. If the function fails, it is recommended to wait a few minutes and try again. If the error persists, please check the SI-PNI portal status or report the issue on our GitHub repository.