Skip to main content

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 five hub airports, great-circle routes between them, and hover tooltips on each marker.

Supply chain map with hub airports and great-circle routes

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.

    HubLatLon
    Washington DC38.90-77.04
    Berlin52.5213.40
    Tokyo35.68139.69
    Beijing39.90116.40
    Sydney-33.87151.21

  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

  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

    URL-encode # as %23 and > as %3E when the URL is assembled by a server or template engine. In a plain browser address bar the literal characters work in most cases.

  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
    Assembled supply chain map

  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.

  • 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