Supply chain / trade network map

Trade flows, logistics corridors, migration patterns, and sanctions chains all share the same shape: a set of hubs connected by directed paths. This recipe shows how to combine markers (hubs), routes (connections), and annotations (tooltip context) into a single embeddable map with no client-side JavaScript.

What you'll build

A world map with six hub markers, directed great-circle routes, and a hover tooltip on each marker.

The map below takes a shortcut the steps then correct: its routes are written as ISO country codes, so they run between country centroids rather than the airport coordinates the markers sit on. That is why some lines do not quite meet their marker. Steps 1–3 show how to terminate routes exactly on the hubs.

Steps

1. Identify your hubs and their coordinates. For city-level precision, use lat,lon literals rather than ISO country codes — ISO codes resolve to geographic centroids, which rarely fall on the airport or port you care about.

   Hub	Lat	Lon
   Washington DC	38.90	-77.04
   Berlin	52.52	13.40
   Tokyo	35.68	139.69
   Beijing	39.90	116.40
   Sydney	-33.87	151.21
   India (country centroid)	20.59	78.96

2. Define your markers. Use lat,lon:icon:label syntax, semicolons between markers. Choose an icon that communicates the hub type — airport for air freight, anchor for ports, factory for manufacturing sites, building for offices.

   markers=38.90,-77.04:airport:Washington;52.52,13.40:airport:Berlin;35.68,139.69:airport:Tokyo;39.90,116.40:airport:Beijing;-33.87,151.21:airport:Sydney;20.59,78.96:airport:India

   The label is drawn beside the glyph and becomes the marker's <title>, so it doubles as the hover tooltip when the SVG is rendered directly in a browser.

3. Define your routes. Use from>to syntax with the same lat,lon literals so routes terminate exactly at the marker position. Add per-route styling — arrow for directed flow, dashed for a different tier or status, #rrggbb for color coding.

   routes=38.90,-77.04>52.52,13.40:arrow;38.90,-77.04>35.68,139.69:arrow;52.52,13.40>39.90,116.40:%2360a5fa:2:dashed:arrow;35.68,139.69>-33.87,151.21:arrow;39.90,116.40>20.59,78.96:%23ec4899:2:arrow

   Always encode # as %23. A literal # starts the URL fragment, so everything after it — the color, and every route that follows — is never sent to the server. The map still renders, with the routes silently falling back to the default color and width, which makes this a nasty one to spot. > is safer: it may be sent literally and is accepted, though encoding it as %3E is the portable choice when a server or template engine assembles the URL.

4. Add a title and choose a dark theme. Dark themes (dark, dark-blue, dark-mono) make routes and markers stand out more clearly than light backgrounds.

   theme=dark&title=Global+logistics+network&subtitle=Air+freight+corridors+2025

5. Assemble the final URL.

   https://api.maproll.io/map.svg?scope=world&theme=dark&title=Global+logistics+network&subtitle=Air+freight+corridors+2025&routes=38.90,-77.04>52.52,13.40:arrow;38.90,-77.04>35.68,139.69:arrow;52.52,13.40>39.90,116.40:%2360a5fa:2:dashed:arrow;35.68,139.69>-33.87,151.21:arrow;39.90,116.40>20.59,78.96:%23ec4899:2:arrow&markers=38.90,-77.04:airport:Washington;52.52,13.40:airport:Berlin;35.68,139.69:airport:Tokyo;39.90,116.40:airport:Beijing;-33.87,151.21:airport:Sydney;20.59,78.96:airport:India

   

6. Add hover tooltips via annotations. Annotations attach free text to the <title> element of each region path. Use them on country-level entries to add context that appears on hover without adding visual clutter:

   annotations=US:Primary+hub,DE:EU+distribution+center,CN:Manufacturing+origin,JP:Asia+gateway,AU:Pacific+relay

   See Annotations for the full syntax.

Variations

• Star topology (hub and spoke). Radiate all routes from a single origin — a classic for trade or distribution diagrams:

  routes=US>GB:arrow;US>FR:arrow;US>DE:arrow;US>JP:arrow;US>AU:arrow;US>BR:arrow

• Color-code route tiers. Use one color for primary corridors, another for secondary:

  routes=US>DE:%23ffffff:3:arrow;US>CN:%23ffffff:3:arrow;US>BR:%2360a5fa:1:dashed:arrow

• Add a choropleth layer. Shade countries by shipment volume to combine flow information with a quantitative layer:

  data=US:500,DE:320,CN:450,JP:280,AU:150&proportional=US:500,DE:320,CN:450

• Use the POST endpoint when your route list is generated dynamically:

  curl -X POST https://api.maproll.io/render/map \
    -H 'content-type: application/json' \
    -d '{
      "scope": "world",
      "theme": "dark",
      "title": "Supply chain Q2 2025",
      "markers": [
        { "lat": 38.90, "lon": -77.04, "icon": "airport", "label": "Washington" },
        { "lat": 52.52, "lon": 13.40,  "icon": "airport", "label": "Berlin" }
      ],
      "routes": [
        { "from": "US", "to": "DE", "arrow": true, "color": "#60a5fa" }
      ]
    }'

  When mixing lat/lon markers with ISO-code routes, note that ISO routes resolve to the country centroid — use fromLatLon/toLatLon in the JSON body for city-level precision.

Related

• Markers — 30-icon library, label positioning, JSON-only fields (color, size, rotation)
• Routes — great-circle paths, per-route styling, lat/lon literals vs ISO codes
• Annotations — per-region hover tooltips
• Themes — dark vs light theme highlight and route contrast