# SIORG – Organizational Structure

## Overview

The SIORG API provides the official organizational structure of the Brazilian Federal Executive Branch. SIORG codes identify ministries, agencies, departments, and other organizational units.

Why it matters for `tesouror`: The CUSTOS API uses SIORG codes in the `organizacao_n1`, `organizacao_n2`, and `organizacao_n3` parameters. The SIORG functions serve as dictionaries to look up these codes.

## Looking up organization codes

### Step 1: List top-level organizations (N1)

    library(tesouror)
    library(dplyr)

    # List all federal executive branch organizations
    orgaos <- get_siorg_organizations(power_code = 1, sphere_code = 1)

    # Key columns:
    #   codigo_unidade     – SIORG code (use as organizacao_n1 in CUSTOS)
    #   codigo_unidade_pai – parent unit code
    #   nome               – organization name
    #   sigla              – abbreviation
    #   codigo_tipo_unidade – "orgao" or "entidade"
    #   codigo_natureza_juridica – 1=Empresa Pública, 2=Fundação, 3=Adm.Direta, 4=Autarquia

    # Find the Ministry of Education
    mec <- orgaos |> filter(grepl("Educação", nome), codigo_tipo_unidade == "orgao")
    mec |> select(codigo_unidade, nome, sigla)
    # codigo_unidade = "244" → this is the org_level1 for CUSTOS

### Step 2: Browse sub-units (N2, N3)

The `codigo_unidade_pai` column lets you navigate the hierarchy. Units whose `codigo_unidade_pai` matches the ministry’s code are direct children (N2 level). Their children are N3.

    # All organizations under MEC (direct children = N2)
    mec_children <- orgaos |>
      filter(codigo_unidade_pai == "244") |>  # MEC's code
      select(codigo_unidade, nome, sigla, codigo_tipo_unidade)
    mec_children
    # Examples: INEP (249), FNDE (253), CAPES (478), etc.

    # For deeper structure, use get_siorg_structure()
    estrutura <- get_siorg_structure(unit_code = 244)
    estrutura |> select(codigo_unidade, codigo_unidade_pai, nome, sigla)

### Step 3: Use in CUSTOS queries

SIORG returns plain codes like `"244"`, but the CUSTOS API expects zero-padded 6-digit strings like `"000244"`. The package pads automatically — just pass the SIORG code directly:

    # Active staff costs for MEC — "244" is auto-padded to "000244"
    custos_mec <- get_costs_active_staff(
      year = 2023,
      org_level1 = 244  # numeric or character, both work
    )

    # Drill down to INEP
    custos_inep <- get_costs_active_staff(
      year = 2023,
      org_level1 = 244,
      org_level2 = 249  # auto-padded to "000249"
    )

### Step 4: Get details of a single unit

    # Full details for AGU (code 46)
    agu <- get_siorg_unit(unit_code = 46)
    agu |> select(codigo_unidade, nome, sigla, codigo_natureza_juridica)

## Functions

Portuguese | English | Description
--- | --- | ---
`get_siorg_orgaos()` | `get_siorg_organizations()` | List organizations (organs + entities)
`get_siorg_estrutura()` | `get_siorg_structure()` | Get organizational structure tree
`get_siorg_unidade()` | `get_siorg_unit()` | Get details of a single unit

## Parameter mapping

### `get_siorg_orgaos()` / `get_siorg_organizations()`

Portuguese | English | Description
--- | --- | ---
`codigo_poder` | `power_code` | `1` = Executive, `2` = Legislative, `3` = Judiciary
`codigo_esfera` | `sphere_code` | `1` = Federal, `2` = State, `3` = Municipal

### `get_siorg_estrutura()` / `get_siorg_structure()`

Portuguese | English | Description
--- | --- | ---
`codigo_unidade` | `unit_code` | SIORG code of the unit (required)
`vinculados` | `include_linked` | `"SIM"` or `"NAO"` — include linked entities

## SIORG codes in CUSTOS

The CUSTOS API uses SIORG codes as 6-digit zero-padded strings (e.g., `"000244"`). The package auto-pads plain codes, so you can pass `244`, `"244"`, or `"000244"` — all work.

The CUSTOS response also includes `co_organizacao_n0` (the top-level authority, e.g., Presidência da República = `"000026"`), which is not a query parameter but appears in the results.

CUSTOS parameter | How to find in SIORG | Example
--- | --- | ---
`organizacao_n1` / `org_level1` | Top-level org: `codigo_unidade` where `codigo_tipo_unidade == "orgao"` | `244` → auto-padded to `"000244"` (MEC)
`organizacao_n2` / `org_level2` | Child of N1: `codigo_unidade` where `codigo_unidade_pai == "<N1 code>"` | `249` → `"000249"` (INEP)
`organizacao_n3` / `org_level3` | Child of N2: use `get_siorg_structure()` for deeper levels | `40523` → `"040523"`

## Response columns

Key columns returned by `get_siorg_orgaos()` / `get_siorg_organizations()`:

Column | Description
--- | ---
`codigo_unidade` | SIORG code (use as `organizacao_n1/n2/n3` in CUSTOS)
`codigo_unidade_pai` | Parent unit’s SIORG code (for navigating the hierarchy)
`nome` | Full name of the organization
`sigla` | Abbreviation (e.g., `"MEC"`, `"INEP"`)
`codigo_tipo_unidade` | `"orgao"` or `"entidade"`
`codigo_natureza_juridica` | `1` = Empresa Pública, `2` = Fundação, `3` = Adm. Direta, `4` = Autarquia
`codigo_esfera` | `1` = Federal, `2` = State/District
`codigo_poder` | `1` = Executive, `2` = Legislative, `3` = Judiciary