Documentation

Learn PolyMapper

Everything you need to know to capture precise polygons, organise layers, and export production-ready GeoJSON files.

Quick Start
Get up and running in under five minutes.
  1. Create an account, confirm your email, then review Premium checkout. Eligible new subscribers can start a 7-day trial with a payment method.
  2. Visit the map workspace and create your first layer from the sidebar.
  3. Click the map to add polygon vertices, then press Enter to finish.
  4. Name the polygon, review the summary in the layer panel, and save.
  5. Use the export menu to generate GeoJSON when your layer is ready.
Try the editor

Guides & Tutorials

Guide
Getting Started
Set up your account, create your first layer, and understand the workspace layout.
Workflow
Creating Polygons
Draw, edit, and organise polygons with polygon tools and explicit save controls.
Cheatsheet
Keyboard Shortcuts
Speed up mapping with editor shortcuts for creation, edits, and navigation.
Reference
Import & Export
Bring GeoJSON data into PolyMapper and export clean files for external tools.
API
API Usage
Authenticate with API keys and call versioned REST endpoints.

Getting started with PolyMapper

PolyMapper pairs a Supabase back end with a high-performance Mapbox canvas. After signing in, your workspace opens with a blank layer list and map focused on your last known position. Use the layer manager to add a new layer, then give it a descriptive name so you can find it quickly.

Tip: organise related layers—for example, districts versus precincts—so exports stay light and remain easy to filter later in GIS software.

Drawing and editing polygons

Choose Create polygon in the toolbar or press C. In Freehand mode, click to add vertices, then press Enter to complete the polygon. To edit an existing polygon, select it, move its vertex handles, and choose Save changes. Cancel discards the current edit.

  • Click an edge midpoint to add a vertex.
  • Right-click a vertex, or focus its handle and press Delete, to remove it. A polygon needs at least three vertices.
  • Use the polygon name field while editing. Imported properties are preserved; there is no general properties editor.
Checklist before saving
Keep your geometry clean and ready for export.

✅ No self-intersections or overlapping edges.

✅ Polygon named clearly (e.g. “District 3 – draft”).

✅ Imported properties checked in the source GeoJSON.

Keyboard shortcuts at a glance

Shortcuts are inactive while you type in a form. Undo/redo currently covers polygon creation in this session, not edits, deletion, split, or merge. Keep an export before making large changes.

C

Enter create polygon mode

⌘ / Ctrl + Z

Undo polygon creation in this session

⌘ / Ctrl + Y

Redo polygon creation in this session

⌘ / Ctrl + S

Save the active polygon

Delete

Remove the selected polygon

Esc

Cancel drawing or close the active dialog

Importing and exporting data

PolyMapper accepts valid GeoJSON Polygon and MultiPolygon features. Use the import dialog in the layer panel to upload files, then review the preview table before committing changes. Exports respect your current layer selection and include polygon metadata.

  1. Open the layer actions menu and choose Import GeoJSON.
  2. Drag in a file or paste raw JSON; validation highlights geometry issues instantly.
  3. Confirm mappings, then click Import to create polygons in the active layer.
  4. When finished, click Export to download a GeoJSON bundle with metadata.
For scripted workflows, call /api/layers/[layerId]/geojson with an authenticated request to fetch the same export payload programmatically.

API Usage

Premium users can create API keys in Account → API Keys. Send your key using the Authorization: Bearer header to call versioned endpoints under /api/v1.

Example (HTTP):
GET https://www.polymapper.com/api/v1/polygons
Authorization: Bearer pmk_live_<prefix>_<secret>
Query parameters:
  • limit — max rows (default 500, max 5000)
  • offset — zero-based offset for pagination
  • includeCount — include total and next_offset when true
  • includeGeometry — include heavy geometry column when true (default false)
HTTP examples:
GET https://www.polymapper.com/api/v1/polygons?limit=1000&offset=0&includeCount=true
Authorization: Bearer pmk_live_<prefix>_<secret>
GET https://www.polymapper.com/api/v1/polygons?limit=1000&offset=1000
Authorization: Bearer pmk_live_<prefix>_<secret>
GET https://www.polymapper.com/api/v1/polygons?limit=500&includeGeometry=true
Authorization: Bearer pmk_live_<prefix>_<secret>
Example response (includeGeometry=true)
{
  "polygons": [
    {
      "id": "69541fc9-3df1-4b71-b338-678e923e240f",
      "layer_id": "d896f16d-d3ac-4816-92e6-803b02239be8",
      "layer_name": "Lake Example",
      "name": "Albania",
      "polygon_name": "Albania",
      "properties": { "source": "geoBoundaries", "iso3": "ALB", "level": 0 },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [ [20.12345, 41.23456], [20.23456, 41.23489], [20.34567, 41.14567], [20.12345, 41.23456] ]
        ]
      },
      "created_at": "2025-10-24T10:02:41.586438+00:00",
      "updated_at": "2025-10-24T10:02:41.586438+00:00"
    }
  ],
  "limit": 1,
  "offset": 0,
  "has_more": true,
  "total": 1,
  "next_offset": null
}
Fields
  • layer_name: the human-readable name of the layer the polygon belongs to.
  • name / polygon_name: optional per‑polygon label (auto‑filled on boundary imports; editable in the UI).
  • geometry: GeoJSON geometry object, included only when includeGeometry=true.
  • properties: free‑form JSON metadata (e.g., source, boundary_id, iso3, level).
Chunking examples
10,000 polygons in 1,000-row pages (fetch)
const BASE = 'https://www.polymapper.com'
const KEY = 'pmk_live_<prefix>_<secret>'
async function fetchAll(limit = 1000) {
  let offset = 0
  const all = []
  while (true) {
    const url = BASE + '/api/v1/polygons?limit=' + limit + '&offset=' + offset
    const res = await fetch(url, { headers: { Authorization: 'Bearer ' + KEY } })
    if (!res.ok) throw new Error('Request failed: ' + res.status)
    const json = await res.json()
    all.push(...json.polygons)
    if (!json.has_more) break
    offset += json.polygons.length
  }
  return all
}
Node (fetch until has_more)
const BASE = 'https://www.polymapper.com'
const KEY = 'pmk_live_<prefix>_<secret>'
async function fetchAll(limit = 1000) {
  let offset = 0
  const all = []
  while (true) {
    const url = BASE + '/api/v1/polygons?limit=' + limit + '&offset=' + offset
    const res = await fetch(url, { headers: { Authorization: 'Bearer ' + KEY } })
    const json = await res.json()
    all.push(...json.polygons)
    if (!json.has_more) break
    offset += json.polygons.length
  }
  return all
}
Note: geometry is excluded by default for performance. When needed, use ?includeGeometry=true and a smallerlimit like 500. Prefer paging over single large responses.
  • Keys are shown once; rotate by creating a new key and revoking the old.
  • On downgrade to Free, all keys are revoked automatically.
  • Prefer server-to-server calls. Browser calls require CORS and careful secret handling.