122 lines
3.1 KiB
Markdown
122 lines
3.1 KiB
Markdown
# 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
|