# The Map SDK

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](https://docs.foursquare.com/studio/docs/maps-annotations).

> 🧪
>
> ### Test it now! 
>
> [This example, rendering a lightweight development environment in your browser, adds an annotation to the map.](https://docs.foursquare.com/developer/docs/studio-map-sdk-example-annotations)

---

# 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](https://location.foursquare.com/contact-us) will be able to add several annotations.

### Example Code

JavaScript

```javascript
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,
})
```

Python

```python
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

| Argument | Type | Description |
| --- | --- | --- |
| `annotation.id` | `string` | The unique identifier of the annotation. |
| `annotation.kind` | `'POINT' | 'CIRCLE' | 'ARROW' | 'TEXT'` | The type of annotation. |
| `annotation.isVisible` | `boolean` | Whether the annotation should be visible on the map. |
| `annotation.autoSize` | `boolean` | Whether the annotation should be auto-sized horizontally to fit the text. |
| `annotation.autoSizeY` | `boolean` | Whether the annotation should be auto-sized vertically to fit the text. |
| `annotation.anchorPoint` | `AnchorPoint` | A tuple containing the longitude and latitude of the annotation's anchor point. Example: `[-73.9876, 40.7488]` |
| `annotation.label` | `string` | The textual description of the annotation. |
| `annotation.editorState` | [`EditorState`](https://docs.foursquare.com/developer/docs/studio-map-sdk-types#editorstate) | The state of the editor. |
| `annotation.mapIndex` | `number` | The index of the map this annotation is attached to. |
| `annotation.lineColor` | `string` | The color of the annotation line. |
| `annotation.lineWidth` | `number` | The width of the annotation line. |
| `annotation.textWidth` | `number` | The width of the annotation text. |
| `annotation.textHeight` | `number` | The height of the annotation text. |
| `annotation.textVerticalAlign` | `'top' | 'middle' | 'bottom' | undefined` | The vertical alignment of the annotation text. |
| `annotation.armLength` | `number` | The length of the annotation arm in pixels. |
| `annotation.angle` | `number` | The angle of the annotation in degrees. |
| `annotation.radiusInMeters` | `number` | The radius in meters (only for kind 'CIRCLE'). |

For more information, including full Python documentation, [see `addDataset()` in the full API reference.](https://docs.foursquare.com/developer/docs/studio-map-sdk-api-reference#adddataset)

---

# Update Annotation

Update an annotation on the map by providing its ID and passing a partial [`Annotation`](https://docs.foursquare.com/developer/docs/studio-map-sdk-types#annotation) object.

### Example Code

JavaScript

```javascript
map.updateAnnotation("annotation-1", {
  label: "A new label",
  lineColor: "#FF0000",
})
```

Python

```python
map.update_annotation("annotation-1", AnnotationUpdateProps(
  label="my new label",
  line_color="#FF0000",
))
```

### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `annotationId` | `string` | The identifier of the annotation to update. |
| `values.id` | `string` | The unique identifier of the annotation. |
| `values.kind` | `'POINT' | 'CIRCLE' | 'ARROW' | 'TEXT'` | The type of annotation. |
| `values.isVisible` | `boolean` | Whether the annotation should be visible on the map. |
| `values.autoSize` | `boolean` | Whether the annotation should be auto-sized horizontally to fit the text. |
| `values.autoSizeY` | `boolean` | Whether the annotation should be auto-sized vertically to fit the text. |
| `values.anchorPoint` | `AnchorPoint` | A tuple containing the longitude and latitude of the annotation's anchor point. Example: `[-73.9876, 40.7488]` |
| `values.label` | `string` | The textual description of the annotation. |
| `values.mapIndex` | `number` | The index of the map this annotation is attached to. |
| `values.lineColor` | `string` | The color of the annotation line. |
| `values.lineWidth` | `number` | The width of the annotation line. |
| `values.textWidth` | `number` | The width of the annotation text. |
| `values.textHeight` | `number` | The height of the annotation text. |
| `values.textVerticalAlign` | `'top' | 'middle' | 'bottom' | undefined` | The vertical alignment of the annotation text. |
| `values.armLength` | `number` | The length of the annotation arm in pixels. |
| `values.angle` | `number` | The angle of the annotation in degrees. |
| `values.radiusInMeters` | `number` | The radius in meters (only for kind 'CIRCLE'). |

# Get Annotations

Retrieves a list of all [Annotations](https://docs.foursquare.com/developer/docs/studio-map-sdk-types#annotation) added to the map.

### Example Code

JavaScript

```javascript
map.getAnnotations();
```

Python

```python
map.get_annotations()
```

---

# Get Annotation by ID

Gets an [Annotations](https://docs.foursquare.com/developer/docs/studio-map-sdk-types#annotation) by providing its ID.

### Example Code

JavaScript

```javascript
map.getAnnotationById("annotation-1");
```

Python

```python
map.get_annotation_by_id("annotation-1")
```

### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `annotationId` | `string` | The identifier of the annotation to retrieve. |

---

# Remove Annotation

Removes an [Annotations](https://docs.foursquare.com/developer/docs/studio-map-sdk-types#annotation) from the map.

### Example Code

JavaScript

```javascript
map.removeAnnotation("annotation-1");
```

Python

```python
map.remove_annotation("annotation-1")
```

### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `annotationId` | `string` | The identifier of the annotation to remove. |