diff --git a/README.md b/README.md index 8f0f65f..de01c87 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,121 @@ -

- Nest Logo -

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

A progressive Node.js framework for building efficient and scalable server-side applications.

-

-NPM Version -Package License -NPM Downloads -CircleCI -Discord -Backers on Open Collective -Sponsors on Open Collective - Donate us - Support us - Follow us on Twitter -

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