Paths API: Draw Lines, Shapes, and Overlays on Maps

Paths are vector overlays drawn directly on the map surface. BuzzTrip supports five path types — line, circle, rectangle, polygon, and text — each of which encodes its geometry as one or more Position values. A Position is a tuple of two or three numbers: [longitude, latitude] or [longitude, latitude, altitude]. Depending on the shape, the points field holds a single Position (e.g. the center of a circle), an array of Position[] (e.g. the vertices of a line or polygon ring), or a nested Position[][] (e.g. a polygon with holes). Measurements (area, perimeter, radius, etc.) and visual styles (stroke color, fill, opacity) are stored alongside the geometry, allowing the client to render and label shapes accurately without recomputing values. All operations require authentication via the authedQuery / authedMutation wrappers.

Schema Reference

pathType

Show Path type values

Value	Description
`"line"`	An open polyline drawn between two or more points.
`"circle"`	A circle defined by a center point and radius.
`"rectangle"`	An axis-aligned bounding rectangle.
`"polygon"`	A closed polygon with optional holes.
`"text"`	A text annotation placed at a point.

points (Position schema)

// A single 2D or 3D coordinate
type Position = [number, number] | [number, number, number];

// Depending on the shape:
type Points =
  | Position      // single point — used for circles, text
  | Position[]    // array of points — used for lines
  | Position[][]  // nested array — used for polygons (ring + optional holes)

measurements

Each path type stores different measurement fields. All measurement objects include perimeter at minimum.

Show Measurement shapes by path type

circleMeasurements — circle

Field	Type	Description
`perimeter`	`number`	Circumference in meters.
`area`	`number` (optional)	Area in square meters.
`radius`	`number`	Radius in meters.
`diameter`	`number`	Diameter in meters.

rectangleMeasurements — rectangle

Field	Type	Description
`perimeter`	`number`	Perimeter in meters.
`area`	`number` (optional)	Area in square meters.
`width`	`number`	Width in meters.
`height`	`number`	Height in meters.

lineMeasurements — line

Field	Type	Description
`perimeter`	`number`	Total length in meters.
`area`	`number` (optional)	Optional — not commonly set for lines.

polygonMeasurements — polygon

Field	Type	Description
`perimeter`	`number`	Perimeter in meters.
`area`	`number` (optional)	Area in square meters.

styles

Show Style fields

Field	Type	Required	Description
`strokeColor`	`string`	✓	Hex or named color for the border/line.
`strokeOpacity`	`number`	—	Opacity of the stroke (0–1).
`strokeWidth`	`number`	—	Width of the stroke in pixels.
`fillColor`	`string`	—	Fill color for closed shapes.
`fillOpacity`	`number`	—	Fill opacity (0–1).

getPathsForMap

Returns all paths belonging to a map, validated against the full pathsSchema. API path: api.maps.paths.getPathsForMap
Type: authedQuery — authentication required

mapId

Id<'maps'>

required

The map whose paths should be returned.

Returns: Path[] | null

Show Response fields (each item)

_id

Id<'paths'>

Unique path document ID.

_creationTime

number

Unix timestamp (ms) when the path was created.

mapId

Id<'maps'>

The map this path belongs to.

pathType

"text" | "circle" | "rectangle" | "polygon" | "line"

The type of shape.

title

string

Display title shown on the path label.

note

string | undefined

Optional user note attached to the path.

points

Position | Position[] | Position[][]

The geometry points for this path.

measurements

Measurements | undefined

Optional measurement data (see schema reference above).

styles

PathStyle | undefined

Optional visual style overrides.

createdBy

Id<'users'>

User who created the path.

updatedAt

string | undefined

ISO 8601 datetime of the last update.

import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const mapId = "abc123" as Id<"maps">;

const paths = useQuery(api.maps.paths.getPathsForMap, { mapId });

paths?.forEach((p) => {
  console.log(p.pathType, p.title, p.points);
});

createPath

Inserts a new path onto a map. The createdBy field is automatically injected from the authenticated user context — you must not include it in your arguments. API path: api.maps.paths.createPath
Type: authedMutation — authentication required

mapId

Id<'maps'>

required

The map to draw the path on.

pathType

"text" | "circle" | "rectangle" | "polygon" | "line"

required

The type of shape to create.

title

string

required

Display label for the path.

points

Position | Position[] | Position[][]

required

Geometry data. A single Position for a circle or text annotation; Position[] for a line; Position[][] for a polygon.

note

string

Optional note attached to this path.

measurements

Measurements

Optional measurement data. Provide the appropriate shape for the pathType (see schema reference above).

styles

PathStyle

Optional visual styles.

Show Style fields

styles.strokeColor

string

required

Border/line color.

styles.strokeOpacity

number

Stroke opacity (0–1).

styles.strokeWidth

number

Stroke width in pixels.

styles.fillColor

string

Fill color for closed shapes.

styles.fillOpacity

number

Fill opacity (0–1).

updatedAt

string

Optional ISO 8601 datetime string.

Returns: Id<'paths'> — the document ID of the newly created path.

import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const createPath = useMutation(api.maps.paths.createPath);

// Draw a walking route between two points
const pathId = await createPath({
  mapId: "abc123" as Id<"maps">,
  pathType: "line",
  title: "Walk to Asakusa",
  points: [
    [139.7016, 35.6586],
    [139.7967, 35.7148],
  ],
  measurements: {
    perimeter: 12400,
  },
  styles: {
    strokeColor: "#3a86ff",
    strokeWidth: 3,
    strokeOpacity: 0.85,
  },
});

console.log("Created path:", pathId);

editPath

Replaces the fields of an existing path and stamps updatedAt with the current ISO datetime. The full pathsEditSchema is accepted (minus system fields _id and _creationTime). API path: api.maps.paths.editPath
Type: authedMutation — authentication required

pathId

Id<'paths'>

required

The path to update.

path

pathsEditSchema

required

The updated path data. All fields from pathsEditSchema are accepted except _id and _creationTime.

Show path fields

path.mapId

Id<'maps'>

required

The map this path belongs to.

path.pathType

"text" | "circle" | "rectangle" | "polygon" | "line"

required

The path type.

path.title

string

required

Updated display title.

path.points

Position | Position[] | Position[][]

required

Updated geometry data.

path.note

string

Updated note.

path.measurements

Measurements

Updated measurements.

path.styles

PathStyle

Updated visual styles.

path.createdBy

Id<'users'>

Optional — the original creator’s user ID.

Returns: Id<'paths'> — the ID of the updated path.

import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const editPath = useMutation(api.maps.paths.editPath);

const pathId = await editPath({
  pathId: "path_xyz" as Id<"paths">,
  path: {
    mapId: "abc123" as Id<"maps">,
    pathType: "line",
    title: "Walk to Asakusa (updated)",
    points: [
      [139.7016, 35.6586],
      [139.7500, 35.6900],
      [139.7967, 35.7148],
    ],
    measurements: {
      perimeter: 13800,
    },
    styles: {
      strokeColor: "#e85d04",
      strokeWidth: 4,
    },
  },
});

console.log("Updated path:", pathId);

deletePath

Permanently deletes a path document. API path: api.maps.paths.deletePath
Type: authedMutation — authentication required

pathId

Id<'paths'>

required

The document ID of the path to delete.

Returns: Id<'paths'> — the ID of the deleted path.

import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const deletePath = useMutation(api.maps.paths.deletePath);

const deletedId = await deletePath({ pathId: "path_xyz" as Id<"paths"> });

console.log("Deleted path:", deletedId);

Overview

Maps API

Users & Places

Configuration

Paths API: Draw Lines, Shapes, and Overlays on Maps

Schema Reference

pathType

points (Position schema)

measurements

styles

getPathsForMap

createPath

editPath

deletePath

Build docs developers (and LLMs) love

Overview

Maps API

Users & Places

Configuration

Documentation Index

​Schema Reference

​pathType

​points (Position schema)

​measurements

​styles

​getPathsForMap

​createPath

​editPath

​deletePath

Build docs developers (and LLMs) love

Schema Reference

pathType

points (Position schema)

measurements

styles

getPathsForMap

createPath

editPath

deletePath