Map

A MapKit view showing markers and polyline paths. Feed it the native payload or a GeoJSON FeatureCollection; the camera auto-fits everything it's given. Optionally interactive.

Type

"map"

Relevant Fields

Inherits all Control Definition. Key fields:

Sync Payload Structure

The map receives its data as a JSON string via Sync — or, since it is a JSON-document control, as a plain JSON object/array, which the app encodes for it. That means an HTTP source can point straight at a GeoJSON endpoint with no server in between.

Native payload

{
  "center": [42.3601, -71.0589],
  "markers": [
    { "coordinate": [42.3601, -71.0589], "color": "#FF9F0A", "size": 16, "label": "Depot" },
    { "coordinate": [42.3875, -71.0995], "color": "#FF453A", "size": 20, "label": "Stalled",
      "ripple": { "color": "#FF453A", "period": 1.4, "radius": 56 } }
  ],
  "paths": [
    {
      "points": [[42.36, -71.05], [42.37, -71.06], [42.38, -71.04]],
      "color": "#FF0000"
    }
  ]
}

ripple is data, not a wire event: it rides in the payload, so an HTTP poll can raise it. That's different from Pulse, which flashes the whole control when a MeshSocket frame arrives.

GeoJSON payloads

A payload whose type is FeatureCollection, Feature, or a bare geometry is read as GeoJSON:

• Point / MultiPoint → markers
• LineString / MultiLineString / Polygon rings / MultiPolygon → paths
• GeometryCollection → walked recursively

GeoJSON positions are [longitude, latitude] — the reverse of the native payload's [lat, lng]. The app flips them for you; don't pre-flip your feed. A third element (elevation/depth) is ignored.

Feature properties style each marker. Recognized without configuration: color or marker-color, size or marker-size, label or name, title, ripple: true; paths read color or stroke.

For a feed you don't control, mapConfig points at whatever properties it does have:

Object-array feeds (not GeoJSON)

Many public feeds are plain-JSON arrays of point objects, not GeoJSON — a flight feed { "ac": [ { "lat": …, "lon": …, "flight": … } ] }, a single-point tracker (the ISS: { "latitude": …, "longitude": … }), or a raw [lng, lat, weight] grid. Point the map at those by naming the coordinate fields; all the styling keys above still apply (their "property" is a key on each object). Declaring markersPath or markerLatProperty switches the map into this mode — ordinary payloads are unaffected.

Marker style & SF Symbols

Motion & camera

Example — live flight radar, no server

{
  "type": "map", "id": "flights", "position": [0, 0], "span": [8, 4],
  "mapStyle": "hybrid", "mapZoom": 3.2, "tint": "#30D158",
  "mapConfig": {
    "markersPath": "ac", "markerLatProperty": "lat", "markerLngProperty": "lon",
    "markerIdProperty": "hex", "markerLabelProperty": "flight",
    "markerStyle": "puck", "markerSymbol": "airplane",
    "motion": true, "motionDuration": 8, "recenter": "initial", "maxMarkers": 200
  },
  "sync": [{ "method": "http", "url": "https://api.adsb.lol/v2/lat/40.7/lon/-74/dist/100", "interval": 8 }]
}

Examples

Vehicle tracker

{
  "type": "map",
  "id": "vehicle-location",
  "position": [0, 0],
  "span": [3, 4],
  "mapStyle": "standard",
  "mapInteractive": true,
  "mapZoom": 0.005,
  "label": "Vehicle",
  "tint": "#FF3B30",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "gps_update" }, "valuePath": "map_data" }]
}

Static satellite view (non-interactive)

{
  "type": "map",
  "id": "property-view",
  "position": [0, 0],
  "span": [2, 4],
  "mapStyle": "satellite",
  "mapInteractive": false,
  "mapZoom": 0.002,
  "label": "Property"
}

Fleet map with multiple markers and a ripple

{
  "type": "map",
  "id": "fleet-map",
  "position": [0, 0],
  "span": [6, 4],
  "label": "Fleet",
  "mapZoom": 0.05,
  "tint": "#FF9F0A",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "fleet_positions" }, "valuePath": "map" }]
}

The server broadcasts {"msg_type":"fleet_positions","map":{"markers":[…],"paths":[…]}} — see Native payload for the marker shape.

Live USGS earthquake feed (GeoJSON over HTTP, no server)

{
  "type": "map",
  "id": "quake-map",
  "position": [0, 0],
  "span": [6, 4],
  "label": "USGS — last hour",
  "mapStyle": "hybrid",
  "mapZoom": 20,
  "mapConfig": {
    "markerSizeProperty": "mag",
    "markerSizeDomain": [0, 7],
    "markerSizeRange": [6, 30],
    "markerLabelProperty": "place",
    "rippleProperty": "mag",
    "rippleThreshold": 4.0,
    "ripple": { "color": "#FF453A", "period": 1.8, "radius": 60 }
  },
  "sync": [{ "method": "http", "url": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson", "interval": 300 }]
}

The endpoint's raw response is consumed as-is: each quake's [lng, lat, depth] position becomes a marker, properties.mag scales it, properties.place labels it, and M4.0+ quakes ripple. No valuePath is needed — the whole document is the payload.

Worldwide feed on the globe

{
  "type": "map",
  "id": "quake-globe",
  "position": [0, 0],
  "span": [6, 4],
  "label": "Worldwide seismicity",
  "mapStyle": "globe",
  "mapConfig": {
    "markerSizeProperty": "mag",
    "markerSizeDomain": [0, 8],
    "markerSizeRange": [5, 26],
    "markerLabelProperty": "place"
  },
  "sync": [{ "method": "http", "url": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson", "interval": 300 }]
}

"globe" is the style to reach for whenever the data is global. A fitted region can't express "the whole planet" — MapKit's Mercator projection crops a 180° latitude span to roughly 120° of longitude in a portrait cell, so a worldwide feed opened on a partial world you had to pinch out of. The globe style instead points the camera at the data's centroid from ~42,000 km, which keeps every marker and both poles in frame at any spread.

Route history with multiple paths

{
  "type": "map",
  "id": "route-map",
  "position": [0, 0],
  "span": [4, 4],
  "mapStyle": "standard",
  "mapZoom": 0.02,
  "label": "Today's Routes",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "route_history" }, "valuePath": "map_data" }]
}

Behavior

• Every marker renders as a colored dot with a white ring; label/title shows beneath it
• A center with no markers and no paths draws one pin in the control's tint color
• Paths render as polylines with their individual colors
• The camera auto-fits the bounding box of all markers and path points (padded); with a single point it centers there at mapZoom
• mapStyle: "globe" overrides that fit: satellite imagery with realistic elevation, viewed from ~42,000 km at the data's centroid, so the whole Earth is in frame. Use it for any worldwide feed; mapZoom has no effect on it
• Rippling markers animate an expanding ring at their coordinate; ripples are suppressed under Reduce Motion
• When no data is synced, shows a placeholder with a map icon
• Map interactions (pan/zoom) don't fire any actions — display only
• A re-broadcast that resolves to the same center is ignored, so a live feed doesn't fight the user's panning

Notes

• The sync value may be a JSON string or a JSON object/array — both work
• Multiple paths with different colors can show different routes, zones, etc.
• mapZoom is a coordinate span — smaller values = more zoomed in. It only applies when there's a single point to show; multi-marker data is auto-fitted
• Legacy { "center": …, "paths": … } payloads are unchanged — markers is additive

Related

• Control Definition — Base fields
• Sync — How map data is received