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

npm install

Database Setup

# Run migrations
npm run prisma:migrate

# Generate Prisma client
npm run prisma:generate

# Seed the database
npm run seed

Running

# 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.

# 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