Annotation Functions

The Map SDK allows you to programmatically apply labels, optionally featuring pointers and circles, to your map. See more examples in our Studio product documentation.

🧪

Test it now!

This example, rendering a lightweight development environment in your browser, adds an annotation to the map.


Add Annotation

Add an annotation to the map. Some of the parameters depend on or are only relevant to the specific annotation.kind.

Currently, only one annotation can be added to the map. In the future versions, enterprise users will be able to add several annotations.

map.addAnnotation({
  id: "annotation-1",
  kind: "POINT",
  isVisible: true,
  autoSize: true,
  autoSizeY: true,
  anchorPoint: [-69.30788156774667, -7.1582370789647],
  label: "Annotation 1",
  lineColor: "#C32899",
  lineWidth: 5,
  textWidth: 82.1796875,
  textHeight: 29,
  textVerticalAlign: "bottom",
  armLength: 50,
  angle: -45,
})
map.add_annotation(AnnotationCreationProps(
    id="ann_1",
    kind="POINT",
    is_visible=True,
    auto_size=True,
    auto_size_y=True,
    anchor_point=(-69.30788156774667, -7.1582370789647),
    label="Annotation 45",
    line_color="#C32899",
    line_width=5,
    text_width=82.1796875,
    text_height=29,
    text_vertical_align="bottom",
    arm_length=50,
    angle=-45,
))

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
annotation.idstringThe unique identifier of the annotation.
annotation.kind'POINT' | 'CIRCLE' | 'ARROW' | 'TEXT'The type of annotation.
annotation.isVisiblebooleanWhether the annotation should be visible on the map.
annotation.autoSizebooleanWhether the annotation should be auto-sized horizontally to fit the text.
annotation.autoSizeYbooleanWhether the annotation should be auto-sized vertically to fit the text.
annotation.anchorPointAnchorPointA tuple containing the longitude and latiude of the annotation's anchor point. Example: [-73.9876, 40.7488]
annotation.labelstringThe textual description of the annotation.
annotation.editorStateEditorStateThe state of the editor. See more information for EditorState
annotation.mapIndexnumberThe index of the map this annotation is attached to.
annotation.lineColorstringThe color of the annotation line.
annotation.lineWidthnumberThe width of the annotation line.
annotation.textWidthnumberThe width of the annotation text.
annotation.textHeightnumberThe height of the annotation text.
annotation.textVerticalAlign'top' | 'middle' | 'bottom' | undefinedThe vertical alignment of the annotation text.
annotation.armLengthnumberThe length of the annotation arm in pixels.
annotation.anglenumberThe angle of the annotation in degrees.
annotation.radiusInMetersnumberThe radius in meters (only for kind 'CIRCLE').

For more information, including full Python documentation, see addDataset() in the full API reference.


Update Annotation

Update an annotation on the map by providing its ID and passing a partial Annotation object.

map.updateAnnotation("annotation-1", {
  label: "A new label",
  lineColor: "#FF0000",
})
map.update_annotation("annotation-1", AnnotationUpdateProps(
  label="my new label",
  line_color="#FF0000",
))
ArgumentTypeDescription
annotationIdstringThe identifier of the annotation to update.
values.idstringThe unique identifier of the annotation.
values.kind'POINT' | 'CIRCLE' | 'ARROW' | 'TEXT'The type of annotation.
values.isVisiblebooleanWhether the annotation should be visible on the map.
values.autoSizebooleanWhether the annotation should be auto-sized horizontally to fit the text.
values.autoSizeYbooleanWhether the annotation should be auto-sized vertically to fit the text.
values.anchorPointAnchorPointA tuple containing the longitude and latiude of the annotation's anchor point. Example: [-73.9876, 40.7488]
values.labelstringThe textual description of the annotation.
values.mapIndexnumberThe index of the map this annotation is attached to.
values.lineColorstringThe color of the annotation line.
values.lineWidthnumberThe width of the annotation line.
values.textWidthnumberThe width of the annotation text.
values.textHeightnumberThe height of the annotation text.
values.textVerticalAlign'top' | 'middle' | 'bottom' | undefinedThe vertical alignment of the annotation text.
values.armLengthnumberThe length of the annotation arm in pixels.
values.anglenumberThe angle of the annotation in degrees.
values.radiusInMetersnumberThe radius in meters (only for kind 'CIRCLE').

Get Annotations

Retrieves a list all Annotations added to the map.

map.getAnnotations();
map.get_annotations()

Get Annotation by ID

Gets an Annotations by providing its ID.

map.getAnnotationById("annotation-1");
map.get_annotation_by_id("annotation-1")
ArgumentTypeDescription
annotationIdstringThe identifier of the annotation to retrieve.

Remove Annotation

Removes an Annotations from the map.

map.removeAnnotation("annotation-1");
map.remove_annotation("annotation-1")
ArgumentTypeDescription
annotationIdstringThe identifier of the annotation to remove.