Skip to main content

Routes

Routes draw curved A→B lines that follow the great circle — the shortest path on a sphere. Use them for trade flows, supply chains, migration corridors, or any map that needs to show a connection between two places. Endpoints can be ISO country codes (resolved to centroids) or explicit lat,lon coordinates.

Examples​

Three routes with mixed styles:

https://api.maproll.io/map.svg?scope=world&theme=dark&routes=DE%3EBR:%2360a5fa:2:dashed:arrow%3BRO%3EAU:%23ec4899:2%3BJP%3EIN
Three routes with mixed styles

Hub-and-spoke: six routes radiating from the US:

https://api.maproll.io/map.svg?scope=world&theme=light&routes=US%3EGB:arrow%3BUS%3EFR:arrow%3BUS%3EDE:arrow%3BUS%3EJP:arrow%3BUS%3EAU:arrow%3BUS%3EBR:arrow
Hub-and-spoke routes from the US

Literal lat/lon endpoints — useful when the destination is a city, not a country centroid:

https://api.maproll.io/map.svg?scope=world&theme=dark&routes=44.43,26.10%3E52.52,13.40:%23ff8c00:3:arrow
Route between two lat/lon coordinates

Routes with marker icons at each endpoint:

https://api.maproll.io/map.svg?scope=world&theme=dark&routes=DE%3EBR:arrow%3BUS%3ECN:dashed:arrow&markers=52.52,13.40:airport:Berlin%3B-23.55,-46.63:pin:S%C3%A3o+Paulo:bottom%3B38.90,-77.04:flag:Washington%3B39.90,116.40:star:Beijing:right
Routes with markers at endpoints

Parameters​

ParamTypeDefaultAllowedNotes
routesstring—See URL syntaxSemicolon-separated route definitions
colorstringtheme text color6-digit hex #rrggbbMust start with #
widthnumber21–20 (px)Integer stroke width
stylestringsolidsolid, dashed
arrowflagoffarrow (presence)Terminal arrowhead at the destination

URL syntax​

routes=from>to[:options];from>to[:options];...

Options after the >to endpoint are type-distinguished — specify them in any order:

OptionDetected byExample
ColorStarts with ##ff0000
WidthAll digits, 1–203
StyleLiteral solid or dasheddashed
ArrowLiteral arrowarrow

Endpoints are either:

  • ISO codes — case-insensitive, resolved to the country's geographic centroid. Example: DE, US, RO-B (subnational).
  • lat,lon literals — a comma in the token signals a coordinate. Example: 44.43,26.10. Mix ISO and coordinates freely: DE>44.43,26.10.

The > separator was chosen over - so subnational ISO codes like RO-AG or US-CA remain unambiguous.

URL-encode > as %3E, # as %23, and ; as %3B in query strings.

# Simple ISO pair
routes=RO%3EDE

# With color and width
routes=RO%3EDE:%23ff0000:3

# Dashed with arrow
routes=RO%3EDE:dashed:arrow

# Lat/lon literal endpoints
routes=44.43,26.10%3E52.52,13.40

# Multiple routes
routes=DE%3EBR:dashed%3BUS%3ECN:arrow

JSON body syntax​

Use POST /render/map with routes: RouteInput[]. The fromLatLon/toLatLon fields accept [lat, lon] and override the ISO lookup:

{
  "scope": "world",
  "theme": "dark",
  "routes": [
    { "from": "RO", "to": "DE", "color": "#ff0000", "width": 3, "arrow": true },
    { "from": "US", "to": "CN", "style": "dashed" },
    { "from": "XX", "to": "YY", "fromLatLon": [44.43, 26.10], "toLatLon": [52.52, 13.40] }
  ]
}

Notes​

  • Great-circle curves. Routes are interpolated with 64 samples via d3.geoInterpolate, giving a smooth arc at world scale.
  • Antimeridian split. When a great circle crosses the ±180° meridian (the date line), the renderer automatically splits it into two segments meeting at the map edges. No client-side handling needed.
  • Routes draw below markers. Marker icons sit on top of route endpoints, so the line tip doesn't poke through the icon.
  • Unknown ISO codes. If an endpoint can't be resolved to a feature in the current scope, the route is skipped and the pair is reported in the X-Geo-Warnings: unknown-routes:A>B response header. The render still returns 200.
  • Centroid vs. city position. from=DE resolves to Germany's geographic centroid (central Germany), not Berlin. For routes that must connect city markers, pass explicit lat,lon literals matching the marker's coordinates.
  • Limit: 500 routes per render. Exceeding this returns 400 invalid_routes.
  • No multi-stop routes. Workaround: pass A>B and B>C as separate routes.
  • Arrow markers are deduped by (color, width). Twenty routes sharing a color and width share one SVG <marker> definition.