# api-ubigeo

NestJS REST API for Peruvian geographic codes (UBIGEO) and world countries. Provides departments, provinces, and districts sourced from INEI 2025, with full-text search and Redis cache.

## Stack

- NestJS 11 + TypeScript 5.7
- Prisma 7 + PostgreSQL 16 (driver adapter pg)
- Redis (cache-manager + @keyv/redis)
- Swagger / OpenAPI
- Helmet + compression
- Docker + Docker Compose

## Features

- List and search all 25 Peruvian departments
- List and search provinces (filter by department)
- List and search districts (filter by province)
- Universal UBIGEO lookup by code (2, 4, or 6 digits)
- Full-text search across departments, provinces, and districts
- World countries endpoint with ISO codes, region, coordinates
- Filter countries by region
- HTTP cache headers (24h `Cache-Control` on all read endpoints)
- Swagger UI at `/api/docs`
- Health check endpoint
- Seeded database via `prisma/seed`

## Getting Started

### Prerequisites

- Node.js 22
- PostgreSQL 16
- Redis (optional, for distributed cache)

### Installation

```bash
npm install
```

### Database Setup

```bash
# Run migrations
npm run prisma:migrate

# Generate Prisma client
npm run prisma:generate

# Seed the database
npm run seed
```

### Running

```bash
# Development
npm run start:dev

# Production
npm run start:prod
```

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `DATABASE_URL` | PostgreSQL connection string | Yes |
| `PORT` | Server port | No (default: `3200`) |
| `NODE_ENV` | Environment (`development` / `production`) | No |

## API Endpoints

All routes are prefixed with `/api/v1`.

### UBIGEO

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/ubigeo/stats` | General stats (counts per level) |
| `GET` | `/api/v1/ubigeo/lookup/:codigo` | Universal lookup by code (2, 4, or 6 digits) |
| `GET` | `/api/v1/ubigeo/departamentos` | List all departments (supports `?q=` search) |
| `GET` | `/api/v1/ubigeo/departamentos/:codigo` | Get department with its provinces |
| `GET` | `/api/v1/ubigeo/provincias` | List provinces (supports `?q=` search, `?dep=` filter) |
| `GET` | `/api/v1/ubigeo/provincias/:codigo` | Get province with its districts |
| `GET` | `/api/v1/ubigeo/distritos` | List districts (supports `?q=` search, `?prov=` filter) |
| `GET` | `/api/v1/ubigeo/distritos/:codigo` | Get district by 6-digit code |

### Countries

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/paises/stats` | Country statistics |
| `GET` | `/api/v1/paises/regiones` | List world regions |
| `GET` | `/api/v1/paises` | List countries (supports `?q=` search, `?region=` filter) |
| `GET` | `/api/v1/paises/:codigo` | Get country by ISO alpha-2 (PE) or alpha-3 (PER) |

### Health

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/health` | Health check |

## Deployment

Docker Compose setup included for local development and production.

```bash
# Local development
docker-compose up -d

# Production
docker-compose -f docker-compose.production.yml up -d
```

Swagger documentation: `http://localhost:3200/api/docs`

## License

Private