Markers API: Create, Edit, View, and Delete Map Pins

Markers are the primary way users annotate locations on a BuzzTrip map. Every marker is linked to a places record — a de-duplicated store of geographic point-of-interest data. When a marker is created, the backend checks whether a place already exists at the given coordinates before inserting a new one. Markers can also be assigned to one or more collections, which are managed via collection_links join records. This makes it easy to group related pins (e.g. “Restaurants”, “Hotels”) without duplicating the marker itself. All operations require authentication via the authedQuery / authedMutation wrappers.

getMarkersView

Retrieves all markers on a map enriched with their associated place data, forming a CombinedMarker array. An optional markerId filter returns only that single marker. Position (lat / lng) on the returned object is sourced from the linked place record when available, falling back to the value stored directly on the marker. API path: api.maps.markers.getMarkersView
Type: authedQuery — authentication required

mapId

Id<'maps'>

required

The map whose markers should be fetched.

markerId

Id<'markers'>

Optional. When provided, only the matching marker is returned.

Returns: CombinedMarker[] | null

Show CombinedMarker fields

_id

Id<'markers'>

Unique marker document ID.

_creationTime

number

Unix timestamp (ms) of marker creation.

title

string

Display title for the marker.

note

string | undefined

Optional user note attached to the marker.

lat

number

Latitude — sourced from the linked place if available, otherwise from the marker record.

lng

number

Longitude — sourced from the linked place if available, otherwise from the marker record.

icon

IconType | string

Icon identifier for the marker pin.

color

string

Hex or named color string for the marker pin.

map_id

Id<'maps'>

The map this marker belongs to.

place_id

Id<'places'>

The linked place document ID.

updatedAt

string | undefined

ISO 8601 datetime of the last update.

place

Place

The full place document merged into the marker.

Show place fields

title

string

Name of the place (e.g. "Eiffel Tower").

lat

number

Latitude of the place.

lng

number

Longitude of the place.

address

string | undefined

Street address.

bounds

{ east, north, south, west } | { lat, lng } | null

Geographic bounds or a single lat/lng fallback.

description

string | undefined

Optional place description.

gm_place_id

string | undefined

Google Maps place ID.

mb_place_id

string | undefined

Mapbox place ID.

fq_place_id

string | undefined

Foursquare place ID.

rating

number

Aggregate rating for the place.

types

string[] | null | undefined

Place type tags (e.g. ["restaurant", "food"]).

website

string | undefined

Place website URL.

phone

string | undefined

Contact phone number.

photos

string[] | null | undefined

Array of photo URLs.

icon

IconType | string

Icon derived from the place’s POI category.

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

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

// All markers on the map
const markers = useQuery(api.maps.markers.getMarkersView, { mapId });

// Single marker
const single = useQuery(api.maps.markers.getMarkersView, {
  mapId,
  markerId: "marker_xyz" as Id<"markers">,
});

markers?.forEach((m) => {
  console.log(m.title, m.lat, m.lng, m.place.address);
});

createMarker

Inserts a new marker onto a map. Before inserting, the backend checks whether a places record already exists at the provided lat/lng coordinates using the by_place_lat_lng index. If no existing place is found, a new one is created via createPlace. This de-duplicates geographic POI data across all maps. After the marker is inserted, collection_links join records are created for each ID in collectionIds. API path: api.maps.markers.createMarker
Type: authedMutation — authentication required

mapId

Id<'maps'>

required

The map to add the marker to.

marker

CombinedMarker

required

The marker data, including embedded place information.

Show marker fields

marker.title

string

required

Display title for the marker.

marker.note

string

Optional user note.

marker.lat

number

required

Latitude of the marker. Also used for place deduplication lookup.

marker.lng

number

required

Longitude of the marker. Also used for place deduplication lookup.

marker.icon

IconType | string

required

Icon identifier for the marker pin.

marker.color

string

required

Color string for the marker pin.

marker.place_id

Id<'places'>

Optional. If you already know the place ID, you can supply it directly.

marker.place

object

required

Place data used to create a new places record if one does not yet exist at these coordinates.

Show place fields

marker.place.title

string

required

Name of the place.

marker.place.lat

number

required

Latitude.

marker.place.lng

number

required

Longitude.

marker.place.address

string

Street address.

marker.place.bounds

Bounds | null

Geographic bounds. Falls back to { lat, lng } if not provided.

marker.place.icon

IconType | string

required

Icon for the place’s POI category.

marker.place.rating

number

Place rating.

marker.place.gm_place_id

string

Google Maps place ID.

marker.place.website

string

Place website URL.

marker.place.types

string[]

POI type tags.

marker.updatedAt

string

Optional ISO 8601 datetime string.

collectionIds

string[]

Optional list of collection IDs to link the new marker to. A collection_links record is inserted for each entry.

Returns: Id<'markers'> — the document ID of the newly created marker.

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

const createMarker = useMutation(api.maps.markers.createMarker);

const markerId = await createMarker({
  mapId: "abc123" as Id<"maps">,
  marker: {
    title: "Senso-ji Temple",
    note: "Amazing at sunrise, very crowded by 9am",
    lat: 35.7148,
    lng: 139.7967,
    icon: "Landmark",
    color: "#e85d04",
    place: {
      title: "Senso-ji Temple",
      lat: 35.7148,
      lng: 139.7967,
      address: "2-3-1 Asakusa, Taito City, Tokyo",
      icon: "Landmark",
      rating: 4.7,
      gm_place_id: "ChIJ8T1GpMGOGGARDYGSgpooDWw",
      types: ["place_of_worship", "tourist_attraction"],
      bounds: null,
    },
  },
  collectionIds: ["collection_temples" as Id<"collections">],
});

console.log("Created marker:", markerId);

editMarker

Updates an existing marker’s fields and/or adjusts its collection assignments. Collection links can be added and removed in the same call. API path: api.maps.markers.editMarker
Type: authedMutation — authentication required

marker_id

Id<'markers'>

required

The marker to update.

mapId

Id<'maps'>

required

The map the marker belongs to. Required when creating new collection_links.

marker

Partial<markersEditSchema>

required

Any subset of marker fields to update. All fields are optional.

Show Updatable fields

marker.title

string

New display title.

marker.note

string

New note text.

marker.lat

number

Updated latitude.

marker.lng

number

Updated longitude.

marker.icon

IconType | string

New icon identifier.

marker.color

string

New color string.

collectionIds_to_add

Id<'collections'>[]

Optional list of collection IDs to link to this marker. A new collection_links record is inserted for each.

collectionIds_to_remove

Id<'collections'>[]

Optional list of collection IDs to unlink from this marker. The corresponding collection_links record is deleted.

Returns: { collectionLinksDeleted: string[]; collectionLinksCreated: string[] | null }

Show Response fields

collectionLinksDeleted

string[]

Array of collection IDs for which links were successfully removed.

collectionLinksCreated

string[] | null

Array of collection IDs for which links were successfully created, or null if none were added.

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

const editMarker = useMutation(api.maps.markers.editMarker);

const result = await editMarker({
  marker_id: "marker_xyz" as Id<"markers">,
  mapId: "abc123" as Id<"maps">,
  marker: {
    note: "Best visited on weekday mornings to avoid crowds",
    color: "#3a86ff",
  },
  collectionIds_to_add: ["collection_must_see" as Id<"collections">],
  collectionIds_to_remove: ["collection_maybe" as Id<"collections">],
});

console.log("Removed links:", result.collectionLinksDeleted);
console.log("Added links:", result.collectionLinksCreated);

deleteMarker

Permanently deletes a marker document. Collection links referencing this marker are not automatically removed — handle that separately if required. API path: api.maps.markers.deleteMarker
Type: authedMutation — authentication required

markerId

Id<'markers'>

required

The document ID of the marker to delete.

Returns: void

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

const deleteMarker = useMutation(api.maps.markers.deleteMarker);

await deleteMarker({ markerId: "marker_xyz" as Id<"markers"> });

Overview

Maps API

Users & Places

Configuration

Markers API: Create, Edit, View, and Delete Map Pins

getMarkersView

createMarker

editMarker

deleteMarker

Build docs developers (and LLMs) love

Overview

Maps API

Users & Places

Configuration

Documentation Index

​getMarkersView

​createMarker

​editMarker

​deleteMarker

Build docs developers (and LLMs) love

getMarkersView

createMarker

editMarker

deleteMarker