Una aplicación web progresiva que reimagina la experiencia de consulta del sistema TransMilenio de Bogotá.
Este proyecto es estrictamente educativo y no tiene fines comerciales. Fue creado como un ejercicio de aprendizaje para explorar el uso de APIs de mapas, diseño de interfaces móviles y desarrollo web moderno. No busca reemplazar ni competir con la app oficial de TransMilenio. Todos los datos de rutas y estaciones pertenecen a TransMilenio S.A.
La idea surgió como un proyecto educativo para aprender a:
- Integrar APIs de mapas (Mapbox GL JS) en aplicaciones web modernas
- Diseñar interfaces mobile-first con estándares de UI/UX actuales
- Consumir y transformar APIs REST de datos de transporte público
- Implementar patrones de desarrollo como búsqueda en tiempo real, geolocalización, y visualización de datos geoespaciales
Al explorar la app oficial de TransMilenio, surgió la pregunta: ¿cómo se podría construir una alternativa que añada funcionalidades útiles como la comparación de múltiples rutas en el mapa? Así nació TransMi.
- Búsqueda inteligente de rutas y estaciones con historial de búsquedas recientes
- Consulta de saldo TuLlave ingresando el número de tarjeta
- Accesos rápidos a rutas favoritas y populares
- Saludo dinámico según la hora del día
- Mapa en tiempo real con Mapbox GL JS y estilo oscuro profesional
- Clusters de estaciones con colores adaptativos para fácil visualización
- Geolocalización para encontrar estaciones cercanas
- Visualización de rutas sobre el mapa con colores diferenciados
- Panel de estación al hacer clic, mostrando rutas disponibles con:
- Indicador de horario activo (🟢) o inactivo (🔴) en tiempo real
- Horarios por convención (L-S, L-V, D-F, S)
- Tipo de servicio (TransMilenio, TransMiZonal)
- Seguimiento de buses en tiempo real sobre la ruta seleccionada
- ETA estimado basado en la posición del bus más cercano
Una funcionalidad que no existe en la app oficial: seleccionar múltiples rutas y verlas simultáneamente en el mapa con colores diferentes. Útil para:
- Comparar recorridos entre dos rutas que van al mismo destino
- Planificar transbordos visualizando rutas superpuestas
- Identificar puntos de intersección entre rutas
- Troncales: Listado completo de troncales con sus estaciones
- Zonas: Exploración por zonas zonales del sistema
- Paradas: Búsqueda y visualización de paradas zonales
- Navegación por tabs con diseño limpio
- Guardar rutas frecuentes para acceso rápido
- Información de tipo de servicio y fecha de guardado
- Ver todas las rutas favoritas en el mapa simultáneamente
- Compartir rutas con otros usuarios
- Modo oscuro y claro adaptativo en toda la aplicación
- Logo oficial de TransMilenio adaptativo al tema
- Interfaz consistente usando tokens semánticos de shadcn/ui
| Tecnología | Uso |
|---|---|
| Next.js 16 | Framework React con App Router y Turbopack |
| React 19 | UI con hooks y componentes funcionales |
| TypeScript 5 | Tipado estático para robustez |
| Tailwind CSS 4 | Estilos utilitarios y sistema de diseño |
| shadcn/ui | Componentes base accesibles (Button, Input, Skeleton, Tabs) |
| Mapbox GL JS | Renderizado de mapas, clusters y rutas geoespaciales |
| localStorage | Persistencia de favoritos, historial y preferencias |
src/
├── app/ # Pages y API routes (Next.js App Router)
│ ├── page.tsx # Inicio — búsqueda, saldo, favoritos
│ ├── mapa/ # Mapa interactivo con buses y rutas
│ ├── explorar/ # Explorador de troncales, zonas, paradas
│ ├── favoritos/ # Listado de rutas favoritas
│ └── api/ # Proxy API routes
│ ├── buses/ # Posición de buses en tiempo real
│ ├── routes/ # Búsqueda y detalle de rutas
│ ├── estaciones/ # Rutas por estación
│ ├── stations/ # Listado de estaciones
│ ├── paradas/ # Paradas zonales
│ ├── troncales/ # Troncales y sus detalles
│ ├── zonas/ # Zonas zonales
│ ├── saldo/ # Consulta de saldo TuLlave
│ └── servicios/ # Tipos de servicio
├── components/
│ ├── home/ # SaldoCard
│ ├── layout/ # AppHeader, BottomNav
│ ├── mapa/ # StationExplorer, MapMarkers
│ ├── search/ # SearchBar, RouteCard
│ └── ui/ # shadcn/ui + TransMiLogo
├── hooks/ # Custom React hooks
│ ├── useFavorites.ts # Gestión de favoritos (localStorage)
│ ├── useGeolocation.ts # API de geolocalización del navegador
│ ├── useRouteSearch.ts # Búsqueda de rutas con debounce
│ ├── useSearchHistory.ts # Historial de búsquedas recientes
│ └── useSelectedRoutes.ts # Selección multi-ruta
├── services/
│ └── transmilenio.ts # Cliente API centralizado
├── types/ # Interfaces TypeScript
└── utils/ # Constantes y utilidades
- Node.js 18+
- pnpm (recomendado) o npm
# 1. Clonar el repositorio
git clone <repo-url>
cd transmi-maps-v2
# 2. Instalar dependencias
pnpm install
# 3. Configurar variables de entorno
cp .env.example .env.local
# Editar .env.local con tu token de Mapbox y URL de API
# 4. Iniciar en desarrollo
pnpm devLa aplicación estará disponible en http://localhost:3000.
| Variable | Requerida | Descripción |
|---|---|---|
NEXT_PUBLIC_MAPBOX_TOKEN |
✅ Sí | Token de acceso de Mapbox GL para renderizar el mapa |
BUS_API_TOKEN |
❌ Opcional | Token de autorización del proxy (x-auth-token) |
PROXY_BASE |
❌ Opcional | URL del proxy que redirige las peticiones a la API de TransMilenio (ver abajo) |
Todas las rutas API que se comunican con tmsa-transmiapp-shvpc.uc.r.appspot.com (/api/buses, /api/saldo, /api/servicios) usan estas dos variables:
BUS_API_TOKEN— Token de autorización del proxy. Se envía como headerx-auth-tokenen todas las peticiones a la API.PROXY_BASE— URL del proxy que reenvía las peticiones a la API de TransMilenio. Si la app se despliega dentro de Colombia, funciona directamente sin proxy. Si estás fuera de Colombia (o tienes bloqueo de red), necesitas configurar esta variable.
# Ejemplo .env
NEXT_PUBLIC_MAPBOX_TOKEN=pk.xxx
BUS_API_TOKEN=tu-token-aqui
# Sin proxy (Colombia) — funciona directo
PROXY_BASE=
# Con proxy (fuera de Colombia)
PROXY_BASE=https://tu-proxy.ejemplo.com/proxy/Cuando PROXY_BASE está configurado, las peticiones se redirigen así:
PROXY_BASE?url=https://tmsa-transmiapp-shvpc.uc.r.appspot.com/endpoint
Si PROXY_BASE no está definido, la app llama directamente a la API sin intermediarios.
La aplicación está diseñada como mobile-first con navegación inferior tipo app nativa:
- Inicio → Búsqueda rápida, saldo TuLlave, favoritos
- Explorar → Troncales, zonas y paradas del sistema
- Mapa → Mapa interactivo con estaciones, rutas y buses
- Favoritos → Rutas guardadas con acceso directo
Este proyecto fue una oportunidad para explorar:
- Mapbox GL JS: Renderizado de mapas vectoriales, clusters, GeoJSON, capas de líneas y puntos animados
- Next.js App Router: Server components, API routes como proxy, streaming y loading states
- shadcn/ui: Sistema de componentes basado en Radix UI con theming semántico
- Diseño Mobile-First: Bottom navigation, safe areas, gestos táctiles, viewport optimizado
- APIs REST de transporte: Estructura de datos de rutas, estaciones, horarios y posiciones GPS
- Geolocalización web: API de
navigator.geolocationcon manejo de permisos - Estado del cliente: LocalStorage para persistencia sin backend, React hooks personalizados
Este proyecto es de uso exclusivamente educativo. No cuenta con licencia comercial. Los datos y la marca TransMilenio pertenecen a TransMilenio S.A.
Hecho con ❤️ como proyecto de aprendizaje — Bogotá, Colombia 🇨🇴