Guía: Integrar GraphHopper en una aplicación Java paso a paso

Personalizar un cálculo de ruta dentro de una aplicación Java puede parecer complejo, especialmente cuando se trata de manipular grafos de rutas y datos OSM. Sin embargo, GraphHopper ofrece una API elegante y modular, lista para integrarse en su proyecto. En esta guía, descubrirá cada fase – desde la instalación hasta el afinamiento del rendimiento – con ejemplos concretos y consejos para dominar las sutilezas de la configuración.

Presentación de GraphHopper

GraphHopper es una biblioteca de código abierto diseñada para proporcionar rutas de carretera en modo offline. Se basa en los datos de OpenStreetMap (OSM) y permite calcular trayectos optimizados según varios criterios: distancia, tiempo, perfil de vehículo (coche, bicicleta, a pie). En realidad, GraphHopper no se limita a un simple cálculo del camino más corto: puede definir restricciones, usar instrucciones de voz e incluso aprovechar superficies para bicicletas y vehículos especializados.

Origen y casos de uso

Inicialmente lanzado para servicios web de geolocalización, GraphHopper interesó rápidamente a desarrolladores Java de escritorio y embebidos. Aplicaciones de entrega, herramientas de planificación de viajes y software de gestión de flotas se apoyan en su motor. Por ejemplo, se puede integrar GraphHopper en una aplicación Android, pero también en un servicio backend que expone rutas vía una API REST.

Requisitos previos e instalación inicial

Creación de un proyecto Java

Comience creando un proyecto Maven o Gradle si aún no tiene uno. En Eclipse o IntelliJ IDEA, seleccione un proyecto Java estándar y asegúrese de usar Java 8 o superior. GraphHopper aprovecha streams y algunas API modernas de Java, por lo que un JDK 11 o 17 suele recomendarse para beneficiarse del rendimiento y estabilidad.

Añadir la dependencia de GraphHopper

En su archivo pom.xml, añada:

<dependency>
  <groupId>com.graphhopper</groupId>
  <artifactId>graphhopper-core</artifactId>
  <version>8.3</version>
</dependency>

Si usa Gradle:

implementation "com.graphhopper:graphhopper-core:8.3"

Esta única dependencia incluye el motor de enrutamiento, así como los módulos para leer archivos PBF provenientes de OSM.

Preparar los datos OpenStreetMap

Para que un enrutador funcione, necesita un extracto OSM que cubra la zona geográfica objetivo. Puede descargar un archivo .pbf desde Geofabrik u otro espejo. Un consejo: limítese a la zona precisa (por ejemplo, un departamento), para reducir el tiempo de procesamiento y la memoria consumida.

Antes de importar, a veces es útil limpiar o editar ligeramente el archivo OSM. En proyectos colaborativos, se comparan herramientas de edición OpenStreetMap para ajustar las etiquetas.

Integración paso a paso

1. Cargar los datos

Instancie un objeto GraphHopper e indique la ruta hacia su PBF:

GraphHopper hopper = new GraphHopper()
  .setGraphHopperLocation("data/graph-cache")
  .setOSMFile("data/map.osm.pbf");
hopper.importOrLoad();

La primera ejecución creará en caché un grafo optimizado, mientras que las llamadas siguientes cargarán directamente esos archivos.

2. Inicializar el enrutador

Antes de lanzar una consulta, puede ajustar los perfiles de vehículo:

hopper.setProfiles(
  new Profile("car").setVehicle("car").setWeighting("fastest"),
  new Profile("bike").setVehicle("bike").setWeighting("shortest")
);

Cada perfil controla la estrategia de enrutamiento y el tipo de ruta que GraphHopper debe privilegiar. Es posible crear perfiles para camiones, peatones o incluso scooters.

3. Ejecutar una consulta de ruta

Para obtener un trayecto, construya una consulta:

GHRequest req = new GHRequest(48.8566, 2.3522, 43.6047, 1.4442)
  .setProfile("car")
  .setLocale(Locale.FRENCH);
GHResponse resp = hopper.route(req);

El resultado contiene la distancia, el tiempo y una lista de puntos geográficos. También puede solicitar instrucciones detalladas (giro a giro).

4. Gestionar los resultados

La clase GHResponse ofrece varios métodos:

• getBest() para recuperar el mejor camino
• getPoints() para la geometría
• getInstructions() para la lista de acciones

Estos datos se prestan para su visualización en un mapa interactivo o para exportar en GeoJSON.

Optimizaciones avanzadas

Una vez que el flujo básico está operativo, se le ofrecen dos palancas principales:

• Compresión de memoria: active la opción dataAccess en modo MMap para una carga más ligera.
• Multihilo: instancie varios hilos en el módulo de enrutamiento para procesar múltiples consultas simultáneamente.

También puede adaptar la granularidad de los datos OSM (manteniendo solo las rutas principales) o generar scripts de poda para eliminar caminos pequeños no relevantes.

Ejemplos prácticos y perspectivas

Imagine que desea mostrar una ruta en un mapa de carreteras de Francia nacional. Tras el cálculo, exporta sus puntos en GeoJSON y superpone la traza sobre una capa Leaflet o Mapbox. Esta integración le da la flexibilidad de añadir puntos intermedios, recalcular la ruta en tiempo real o mostrar estadísticas de distancia y desnivel.

En otro caso, puede ejecutar GraphHopper en modo servidor (jar autónomo) y enviarle consultas vía HTTP, transformando su aplicación Java en un microservicio de enrutamiento capaz de atender miles de llamadas por segundo.

FAQ

P: ¿Qué versión de Java se debe usar con GraphHopper?
R: GraphHopper recomienda Java 11 o superior para aprovechar las APIs recientes y una mejor gestión de memoria.

P: ¿Se pueden integrar puntos de interés (POI) en los cálculos?
R: Sí, basta con añadir sus POI en forma de waypoints en la solicitud GHRequest, o personalizar el grafo añadiendo nodos específicos.

P: ¿Cómo reducir el tamaño del grafo en memoria?
R: Use la configuración .setDataAccessType(DataAccessType.MMAP) y limite la zona OSM a lo esencial mediante un extracto PBF focalizado.

P: ¿GraphHopper gestiona las restricciones de circulación?
R: Sí, las propiedades OSM como access=no o las etiquetas motor_vehicle=no se tienen en cuenta durante la importación.