Map / Geolocation

Overview

The Map field renders a Leaflet map. The respondent draws geography according to mapDrawingMode. Each map field uses exactly one tool — if you need both a pin and a boundary on the same form, add two map fields. Common patterns:

1. Coordinate — set mapDrawingMode to coordinate. Respondent places one pin; use for delivery drops, incidents, or store locator.
2. Polygon — polygon. Multiple vertices close a region; use for parcels, zones, or irregular coverage areas. Area is computed in m² and shown with areaUnit.
3. Rectangle — rectangle. Two opposite corners define an axis-aligned box; quick site pads or simple lots. Area behaves like polygon.
4. Circle — circle. Center plus radius in meters; use for service radius, coverage, or geofenced promos. Submission includes radius and circle area in m².
5. Line — line. Two or more vertices form an open path; use for routes, corridors, or trails. Total length is in meters (lengthUnit controls display).

Published answers are keyed by each field's id (UUID), not by label. Every coordinate pair is [latitude, longitude] in decimal degrees — in the schema as mapCoordinates / mapCenter, and in submissions as coordinates (see Stored value).

Properties

Saved form JSON

Exported definitions wrap every field list in the same three top-level keys you see in Developer / JSON view. They are not part of the map field itself — they describe the form document that contains your map (and any other fields).

name

Internal or display name of the form version. May be empty while drafting. Useful when syncing templates or matching definitions in storage — it does not change how the map draws.

weightage

Numeric weight used when the product scores or orders forms (often 0). Unrelated to map geometry; keep it if your export pipeline expects it.

fields

Ordered array of field objects. Each element is one control (text, select, map, …). Map entries sit alongside other fields; array order is the default render order. Every object needs its own id so submissions, reporting, and conditional logic stay stable when labels change.

Coordinate (single pin)

Respondent clicks once to place a pin (or moves it). The field stores a single position in mapCoordinates as [[lat, lng]] when answered. Best when the answer is one location: pickup point, ticket pin, kiosk, or “where did this happen?”

Polygon (area)

Respondent places three or more vertices; the first and last vertex close the ring. calculatedArea is the enclosed area in m² (converted for display via areaUnit). Use for property lines, watersheds, service territories with irregular edges, or any region that is not a simple box or circle.

Rectangle (box)

Two clicks set opposite corners of an axis-aligned rectangle on the map. Faster than tracing a polygon when the site is roughly rectangular (parking slab, building footprint, campus block). Area uses the same metric pipeline as polygon.

Circle (radius)

First click is the center; second sets edge distance so the radius is stored in meters. Submissions include radius plus circle area in m². Ideal for delivery radius, coverage around a tower, clinic catchment, or any “how far from this point?” question.

Line (path)

Two or more clicks create a polyline (open path). calculatedLength sums segment lengths in meters. Use for pipeline or utility corridors, parade or race segments, trails, or fence lines along roads — anywhere the answer is a route, not a filled region.

JSON examples

Polygon field (single map in a form)

Typical export: one map field inside the fields array, with reporting metadata and zoom bounds.

{
  "name": "",
  "weightage": 0,
  "fields": [
    {
      "id": "781cde32-2591-48e1-9998-7f78ffeb0576",
      "type": "map",
      "label": "Parcel boundary",
      "required": true,
      "isHidden": false,
      "placeholder": "Enter map...",
      "mapDrawingMode": "polygon",
      "mapCoordinates": [],
      "calculatedArea": 0,
      "calculatedLength": 0,
      "mapCenter": [27.717201, 85.323998],
      "mapZoom": 13,
      "areaUnit": "hectare",
      "lengthUnit": "km",
      "mapMinZoom": 2,
      "mapMaxZoom": 18,
      "isDisabled": false,
      "instruction": "Draw the parcel boundary on the map.",
      "reporting": {
        "includeInTable": true,
        "sortable": true,
        "labelOverride": "Parcel area"
      },
      "integrationKey": "parcel_map"
    }
  ]
}

Coordinate field (minimal)

Same wrapper keys; only the map-specific properties change for a pin field.

{
  "name": "Site survey",
  "weightage": 0,
  "fields": [
    {
      "id": "d7f44c48-9984-4106-adc5-028ab1fa35dd",
      "type": "map",
      "label": "Incident location",
      "required": false,
      "isHidden": false,
      "placeholder": "Enter map...",
      "mapDrawingMode": "coordinate",
      "mapCoordinates": [],
      "calculatedArea": 0,
      "calculatedLength": 0,
      "mapCenter": [27.7172, 85.324],
      "mapZoom": 13,
      "areaUnit": "m²",
      "lengthUnit": "m"
    }
  ]
}

One form, five map fields (one mode each)

Below, fields holds five separate map definitions. Each row is a different question with its own id and tool — this is how you collect pin + area + route on one page without mixing modes in a single field.

{
  "name": "Field ops",
  "weightage": 0,
  "fields": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "type": "map",
      "label": "Drop-off pin",
      "required": true,
      "isHidden": false,
      "mapDrawingMode": "coordinate",
      "mapCoordinates": [],
      "calculatedArea": 0,
      "calculatedLength": 0,
      "mapCenter": [27.7172, 85.324],
      "mapZoom": 13,
      "areaUnit": "m²",
      "lengthUnit": "m"
    },
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "type": "map",
      "label": "Affected zone (polygon)",
      "required": true,
      "isHidden": false,
      "mapDrawingMode": "polygon",
      "mapCoordinates": [],
      "calculatedArea": 0,
      "calculatedLength": 0,
      "mapCenter": [27.7172, 85.324],
      "mapZoom": 13,
      "areaUnit": "m²",
      "lengthUnit": "m"
    },
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "type": "map",
      "label": "Building pad (rectangle)",
      "required": false,
      "isHidden": false,
      "mapDrawingMode": "rectangle",
      "mapCoordinates": [],
      "calculatedArea": 0,
      "calculatedLength": 0,
      "mapCenter": [27.7172, 85.324],
      "mapZoom": 14,
      "areaUnit": "m²",
      "lengthUnit": "m"
    },
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "type": "map",
      "label": "Service radius (circle)",
      "required": false,
      "isHidden": false,
      "mapDrawingMode": "circle",
      "mapCoordinates": [],
      "calculatedArea": 0,
      "calculatedLength": 0,
      "mapCenter": [27.7172, 85.324],
      "mapZoom": 12,
      "areaUnit": "m²",
      "lengthUnit": "m"
    },
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "type": "map",
      "label": "Access route (line)",
      "required": false,
      "isHidden": false,
      "mapDrawingMode": "line",
      "mapCoordinates": [],
      "calculatedArea": 0,
      "calculatedLength": 0,
      "mapCenter": [27.7172, 85.324],
      "mapZoom": 13,
      "mapMinZoom": 3,
      "mapMaxZoom": 18,
      "areaUnit": "m²",
      "lengthUnit": "m"
    }
  ]
}

1. Field 1 (coordinate) — collects exactly one pin for vehicle hand-off or incident reporting.
2. Field 2 (polygon) — irregular coverage or damage area where corners matter more than a circle approximation.
3. Field 3 (rectangle) — quick rectangular lot or floor plate when four right angles are acceptable.
4. Field 4 (circle) — distance-based service or coverage from a hub; radius is stored in meters.
5. Field 5 (line) — linear infrastructure or path; length accumulates along the polyline.

Stored value

Submissions store one object per map field id. Typical keys mirror the runtime map value:

• coordinates: [lat, lng][] — same order as geometry on the map.
• drawingMode: echoes mapDrawingMode.
• calculatedArea: m² for polygon, rectangle, or circle when applicable.
• calculatedLength: total meters for line mode.
• radius: meters, circle mode only.

Use cases by pattern

• Coordinate: delivery or pickup pin, ticket location, kiosk placement.
• Polygon: property boundary, catchment area, conservation zone.
• Rectangle: quick site pad, retail floor plate, parking lot outline.
• Circle: service radius around a clinic, tower coverage, geofenced promo.
• Line: utility corridor, race route segment, fence line along a road.