Docs › Network Analysis › Routing

Routing Service

v3.2.1 • Stable

Overview

The Routing Service provides optimized pathfinding, isochrone generation, and distance/time matrix calculations across your geospatial network datasets. Built on top of OGC API - Features and enhanced with proprietary graph algorithms, it delivers sub-second responses for enterprise-scale network analysis.

ℹ️ Note

The Routing Service requires a pre-processed network dataset. Ensure your workspace contains a valid network_graph.json or import shapefiles/GeoJSON with topology defined before making requests.

Configuration

Routing parameters are configured via your workspace YAML or the GeoServer Admin UI. Below is a typical configuration block:

YAML
routing:
  enabled: true
  backend: 'pgrouting' # pgrouting | osrm | valhalla
  network_dataset: 'us_highway_network'
  metrics:
    - distance
    - travel_time
    - fuel_consumption
  constraints:
    max_weight: 40 # tons
    max_height: 4.5 # meters
    turn_restrictions: true
  cache:
    enabled: true
    ttl: 3600 # seconds

API Endpoints

All routing requests require a valid API key in the Authorization header. Base path: /v1/routing

Compute Shortest Path

Finds the optimal route between two or more waypoints using Dijkstra, A*, or Contraction Hierarchies depending on payload size.

cURL
curl -X POST https://api.geoserver.cloud/v1/routing/shortest-path \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Content-Type: application/json' \  -d '{
  "profile": "car_fastest",
  "waypoints": [
    {"lon": -122.4194, "lat": 37.7749},
    {"lon": -122.0839, "lat": 37.3861}
  ],
  "options": {
    "avoid_tolls": true,
    "avoid_highways": false
  }
}'

Generate Isochrones

Returns polygonal areas reachable within a specified time or distance threshold from a central coordinate.

JavaScript
const response = await fetch('https://api.geoserver.cloud/v1/routing/isochrones', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    location: [-118.2437, 34.0522],
    profile: 'bike',
    contours: [
      { time: 5, color: '00b4d8' },
      { time: 15, color: '0f4c75' }
    ]
  })
});

const geojson = await response.json();
console.log(geojson.features[0].geometry); // GeoJSON Polygon

Parameters Reference

Parameter Type Required Description
profile String Yes Routing mode: car_fastest, car_shortest, bike, walk, truck
waypoints Array[Object] Yes Array of coordinate pairs or place IDs. Min: 2, Max: 50
avoid_tolls Boolean No Exclude toll roads from pathfinding calculations
geometry_format String No Output format: geojson (default) or encoded_polyline
steps Boolean No Include turn-by-turn navigation instructions in response

Response Format

All successful requests return a 200 OK with a structured JSON payload. Example response for shortest-path:

JSON
{
  "code": 200,
  "message": "Route computed successfully",
  "data": {
    "route": {
      "distance": 58432.1,
      "duration": 2840.5,
      "geometry": { "type": "LineString", "coordinates": [...] },
      "segments": [
        { "distance": 58432.1, "duration": 2840.5, "steps": [...] }
      ]
    },
    "metadata": {
      "engine": "pgrouting",
      "timestamp": "2025-01-15T08:32:11Z",
      "request_id": "req_7f9a2b8c"
    }
  }
}

Error Handling

GeoServer follows standard HTTP status codes. Common routing errors include:

Status Code Description
400 INVALID_WAYPOINT Coordinate outside network bounds or malformed input
403 NETWORK_DISABLED Requested profile is not enabled in workspace config
422 NO_ROUTE_FOUND Waypoints disconnected or constraints too restrictive
429 RATE_LIMIT_EXCEEDED Too many requests. Check X-RateLimit-Remaining header
⚠️ Warning

Receiving 429 errors? Implement exponential backoff and review your concurrency settings. Enterprise plans include higher throughput limits and dedicated compute nodes.

Performance & Rate Limits

Routing computations are resource-intensive. GeoServer automatically caches frequent routes and optimizes graph queries. Recommended practices:

  • Batch matrix requests instead of sequential shortest-path calls
  • Use encoded_polyline format for mobile/low-bandwidth clients
  • Pre-warm cache by requesting common routes during off-peak hours
  • Standard tier: 100 req/min • Pro tier: 1,000 req/min • Enterprise: Custom

For custom network topologies or offline deployment, contact our solutions engineering team for tailored graph partitioning strategies.