# Mira

> Mira provides access to DGEEC data about teachers and researchers in Portuguese higher education through a React web interface and a FastAPI REST API.

## API Usage

The API exposes data exploration, statistical analysis, filtering and download endpoints. The API is served by the FastAPI backend.

- [OpenAPI Specification](/api/openapi.json): Machine-readable API specification, including parameters and response schemas.
- [Available Filters](/api/filters): Current values for the shared filters used by the analysis and exploration endpoints.

## Complete Data Endpoints

When an LLM or automated client needs every result for analysis, summarisation, comparison or question answering, prefer the corresponding `/complete` endpoint. These endpoints return the complete result set without pagination.

- `/api/analysis/eti_percent_tempo/complete`: ETI and percentage of time analysis.
- `/api/analysis/horas_totais_docente/complete`: Total teaching hours per teacher.
- `/api/analysis/media_horas_docente_anos_letivos/complete`: Average teaching hours by teacher and school year.
- `/api/analysis/individuos_mult_contratos_soma_de_horas_anual/complete`: Individuals with multiple contracts and their annual hours.
- `/api/analysis/categoria_por_ano/complete`: Percentage of individuals by category and year.
- `/api/analysis/categoria_por_ano_letivo/complete`: Percentage of individuals by category and academic year.
- `/api/analysis/media_horas_letivas_por_ano_letivo/complete`: Average teaching hours by academic year.
- `/api/analysis/media_percent_horas_por_ano/complete`: Average percentage of time by year.
- `/api/explore/pessoas/complete`: Complete people exploration results, including aggregated qualifications and contract categories.

The corresponding endpoint without `/complete` is paginated and should be used when only part of the result set is needed or when the response would be too large. Pagination uses `page` and `pageSize`.

## Query Parameters

Analysis and exploration endpoints may support the following filters, depending on the endpoint:

- `ano` and `anoLetivo`: Year or academic year. Repeat the parameter to provide multiple values, for example `?ano=2023&ano=2024`.
- `setor`: Education sector, such as public or private.
- `regime`: Institution regime.
- `tipoEnsino`: Type of higher education, such as university or polytechnic.
- `estabelecimentos`: Institution names.
- `unidadesOrganicas`: Organic unit names.
- `categorias`: Contract categories.
- `niveisFormacao`: Qualification levels.
- `modalidadesVinculacao`: Contractual linkage modalities. This is available on people exploration endpoints.
- `ids`: Teacher or person identifiers on the teacher-hours analysis endpoints.
- `search`: Text search where supported.
- `sortBy` and `sortOrder`: Sorting controls. `sortOrder` must be `asc` or `desc`.

Inspect the OpenAPI specification for the exact parameters supported by each endpoint and the response schema.

## Downloads

Each analysis and exploration family provides a `/download` variant that returns the filtered results as a downloadable CSV file.

- `/api/analysis/{analysis_name}/download`: Download analysis results.
- `/api/explore/pessoas/download`: Download people exploration results.
- `/api/download/database`: Download the SQLite database.
- `/api/download/table/{table}`: Download a raw database table as CSV. Valid table names are documented in OpenAPI.

Use the same filters and sorting parameters as the corresponding data endpoint where supported.

## Administrative Endpoints

Administrative operations require authentication and should not be used for public data analysis.

## Usage Guidelines

1. Prefer `/complete` endpoints when the task requires all available results.
2. Use paginated endpoints when only a subset is needed or the complete response would be unnecessarily large.
3. Inspect `/openapi.json` for required parameters, response schemas and endpoint-specific behavior.
4. Call `/filters` before constructing filter-driven queries when valid values are not already known.
5. Repeat query parameters for list values rather than sending a comma-separated string.
6. Respect response-size, authentication and rate-limit constraints imposed by the deployment.