darkcodex/api-ubigeo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README

Browse Source
This commit is contained in:
Gianpierre Mio
2026-04-04 12:34:52 -05:00
parent 2a00d26a10
commit 976c5ee10b
1 changed files with 92 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
README.md
View File

@@ -1,98 +1,121 @@
<p align="center">
<a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
</p>
# api-ubigeo
[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
[circleci-url]: https://circleci.com/gh/nestjs/nest
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.
<p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
<p align="center">
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
<a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
<a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
</p>
<!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
[![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
## Stack
## Description
- NestJS 11 + TypeScript 5.7
- Prisma 7 + PostgreSQL 16 (driver adapter pg)
- Redis (cache-manager + @keyv/redis)
- Swagger / OpenAPI
- Helmet + compression
- Docker + Docker Compose
[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
## Features
## Project setup
- 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
npm install
```
## Compile and run the project
### Database Setup
```bash
# development
$ npm run start
# Run migrations
npm run prisma:migrate
# watch mode
$ npm run start:dev
# Generate Prisma client
npm run prisma:generate
# production mode
$ npm run start:prod
# Seed the database
npm run seed
```
## Run tests
### Running
```bash
# unit tests
$ npm run test
# Development
npm run start:dev
# e2e tests
$ npm run test:e2e
# test coverage
$ npm run test:cov
# 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
When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
Docker Compose setup included for local development and production.
```bash
$ npm install -g @nestjs/mau
$ mau deploy
# Local development
docker-compose up -d
# Production
docker-compose -f docker-compose.production.yml up -d
```
With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
## Resources
Check out a few resources that may come in handy when working with NestJS:
- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
## Support
Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
## Stay in touch
- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
- Website - [https://nestjs.com](https://nestjs.com/)
- Twitter - [@nestframework](https://twitter.com/nestframework)
Swagger documentation: `http://localhost:3200/api/docs`
## License
Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
Private