Map Objects

The MapKit SDK lets developers display objects on a map. All map objects are customizable, facilitating unique user scenarios tailored to the developer needs.

PlacemarksPlacemarks

Add custom image placemarks to the map with the MapObjectCollection.addPlacemark method from the Map.getMapObjects field.

The method creates placemark instance on the map, which can by customized: you can set the Point with coordinates for the placemark and the icon using ImageProvider instance, which can be created from a drawable resource.

val placemark = map.mapObjects.addPlacemark().apply {
    geometry = Point(59.935493, 30.327392)
    setIcon(ImageProvider.fromResource(this, R.drawable.ic_pin))
}

The code above creates an instance of the PlacemarkMapObject class that extends the MapObject interface.

The MapObject interface represents every visible object on the map. There are a few ways to configure map objects: changing visibility, allowing dragging, changing a z-index, setting a tap or drag event listener, and more.

For more details, see the MapObject documentation.

Setting textSetting text

You can create text labels near placemarks. Use the PlacemarkMapObject.setText method.

Use TextStyle to change how labels look, including their text size, color, and position relative to the icon.

placemark.setText(
    "Special place",
    TextStyle(/* args */)
)

Icon stylesIcon styles

You can customize how placemark icons are presented using the IconStyle class. It lets you change the icon's anchor position, size, rotation type, z-index, tappable area, visibility, and flatness to the map.

placemark.setIconStyle(
    IconStyle().apply {
        anchor = PointF(0.5f, 1.0f)
        scale = 0.6f
        zIndex = 10
    }
)

Composite iconsComposite icons

Combine multiple icons to create a composite one.

1. Create a default icon using MapObjectCollection.addPlacemark method.

2. Call PlacemarkMapObject.useCompositeIcon to create a composite icon.

3. Use CompositeIcon.setIcon to add a new icon to the composite icon.

Complete sample code for creating a composite icon:

val placemark = map.mapObjects.addPlacemark().apply {
    geometry = Point(59.935493, 30.327392)
    setText(
        "Special place",
        TextStyle().apply {
            size = 10f
            placement = Placement.RIGHT
            offset = 5f
        },
    )
}

placemark.useCompositeIcon().apply {
    setIcon(
        "pin",
        ImageProvider.fromResource(this@Activity, R.drawable.ic_dollar_pin),
        IconStyle().apply {
            anchor = PointF(0.5f, 1.0f)
            scale = 0.9f
        }
    )
    setIcon(
        "point",
        ImageProvider.fromResource(this@Activity, R.drawable.ic_circle),
        IconStyle().apply {
            anchor = PointF(0.5f, 0.5f)
            flat = true
            scale = 0.05f
        }
    )
}

The result:

Animated placemarksAnimated placemarks

You can create an animated placemark from an animated png file.

1. Create the placemark using MapObjectCollection.addPlacemark.

   val placemark = map.mapObjects.addPlacemark() {
       geometry = Point(59.935493, 30.327392)
   }
   

2. Call the PlacemarkMapObject.useAnimation method to create an animation object. Set the animation resource using the AnimatedImageProvider instance.

   val animation = placemark.useAnimation().apply {
       setIcon(AnimatedImageProvider.fromAsset(this, "animation.png"))
   }
   

3. Start the animation, managing it with the PlacemarkAnimation object.

   animation.play()
   

Placemark collectionsPlacemark collections

Placemark collections are used to group multiple placemarks into a new collection of nested map objects.

1. To create a collection of nested map objects, use the MapObjectCollection.addCollection method.

   val pinsCollection = map.mapObjects.addCollection()
   

2. From now, you can use your new pinsCollection to display placemarks and other map objects.

   val points = listOf(
       Point(59.935493, 30.327392),
       Point(59.938185, 30.32808),
       Point(59.937376, 30.33621),
       Point(59.934517, 30.335059),
   )
   
   val imageProvider = ImageProvider.fromResource(this, R.drawable.ic_pin)
   
   points.forEach { point ->
       pinsCollection.addPlacemark().apply {
           geometry = point
           setIcon(imageProvider)
       }
   }
   

   Note

   Use a single ImageProvider instance if you need to display multiple similar placemarks. That will be more efficient than creating a new instance for each placemark.

   What it looks like after placemarks were added to a collection of new map objects:

   

After creating pinCollection, you can add pins to it the same way as for Map.getMapObjects since they have the same MapObjectCollection type.

You can iterate through MapObjectCollection elements using the BaseMapObjectCollection.traverse method.

GeometriesGeometries

The MapKit SDK lets you draw primitive geometric objects like polygons, polylines, and circles on the map. They're all customizable, and they implement the MapObject interface.

PolygonsPolygons

Use a polygon when you need to display a map area to users.

1. Start by creating a Polygon instance.

   val points = listOf(
       Point(59.935493, 30.327392),
       Point(59.938185, 30.32808),
       Point(59.937376, 30.33621),
       Point(59.934517, 30.335059),
   )
   val polygon = Polygon(LinearRing(points), emptyList())
   

2. Use the MapObjectCollection.addPolygon method to create a polygon map object.

   val polygonMapObject = map.mapObjects.addPolygon(polygon)
   

   After the build is complete, you will see a default-styled polygon:

   

3. Define inner points while creating a polygon to exclude a section on the inside of the polygon.

   val points = listOf(
       Point(59.935493, 30.327392),
       Point(59.938185, 30.32808),
       Point(59.937376, 30.33621),
       Point(59.934517, 30.335059),
   )
   val innerPoints = listOf(
       Point(59.937487, 30.330034),
       Point(59.936688, 30.33127),
       Point(59.937116, 30.33328),
       Point(59.937704, 30.331842),
   )
   val polygon = Polygon(LinearRing(points), listOf(LinearRing(innerPoints)))
   

   Polygon with inner points:

   

4. Let's change the default fill color and stroke using the PolygonMapObject instance we created.

   polygonMapObject.apply {
       strokeWidth = 1.5f
       strokeColor = ContextCompat.getColor(this@Activity, R.color.olive)
       fillColor = ContextCompat.getColor(this@Activity, R.color.green)
   }
   

   

For more details on how to configure polygons, see the PolygonMapObject documentation.

PolylinesPolylines

Polylines are often used to display routes and trajectories.

1. Create a Polyline instance with the geometry you're looking for and add a polyline map object to the map using the MapObjectCollection.addPolyline method.

   val points = listOf(
       Point(59.935493, 30.327392),
       Point(59.938185, 30.32808),
       Point(59.937376, 30.33621),
       Point(59.934517, 30.335059),
   )
   val polyline = Polyline(points)
   
   val polylineObject = map.mapObjects.addPolyline(polyline)
   

2. Configure polyline styles using the PolylineMapObject variable.

   polylineObject.apply {
       strokeWidth = 5f
       setStrokeColor(ContextCompat.getColor(this@Activity, R.color.gray))
       outlineWidth = 1f
       outlineColor = ContextCompat.getColor(this@Activity, R.color.black)
   }
   

   Once you've added the polyline to the map:

   

For more details, see the PolylineMapObject documentation.

CirclesCircles

Circles are used to display circular areas.

1. Create a Circle instance with the geometry you're looking for: a center point and a radius in meters.

   val circle = Circle(
       Point(59.935493, 30.327392),
       400f
   )
   

2. Using the MapObjectCollection.addCircle method, add a circle object to the map.

   map.mapObjects.addCircle(circle).apply {
       strokeWidth = 2f
       strokeColor = ContextCompat.getColor(this, R.color.red)
       fillColor = ContextCompat.getColor(this, R.color.red_alpha)
   }
   

   After adding a circle to the map:

   

For more details on how to configure a circular map object, see the CircleMapObject documentation.

ClustersClusters

Clusterized collections are used to display multiple placemarks.

1. Start by creating a ClusterListener with a single ClusterListener.onClusterAdded method that controls the appearance of the cluster on the map.

   val clusterListener = ClusterListener { cluster ->
       cluster.appearance.setView(
           ViewProvider(
               ClusterView(this).apply {
                   setText("${cluster.placemarks.size}")
               }
           )
       )
   }
   

   The Cluster.getAppearance property returns a PlacemarkMapObject object. In our example, we're using the PlacemarkMapObject.setView method to change how the cluster looks.

   ClusterView is a custom defined class. Check out its implementation in out Github repository.

2. Create a new nested collection using the MapObjectCollection.addClusterizedPlacemarkCollection method.

   val clusterizedCollection = map.mapObjects.addClusterizedPlacemarkCollection(clusterListener)
   

3. Add multiple placemarks to the new clusterizedCollection.

   val points = listOf(
       Point(59.935493, 30.327392),
       Point(59.938185, 30.32808),
       Point(59.937376, 30.33621),
       Point(59.934517, 30.335059),
   )
   val imageProvider = ImageProvider.fromResource(this, R.drawable.ic_pin)
   
   points.forEach { point ->
       clusterizedCollection.addPlacemark().apply {
           geometry = point
           setIcon(imageProvider)
       }
   }
   

4. Call the ClusterizedPlacemarkCollection.clusterPlacemarks method. It accepts two arguments:

   • clusterRadius: the minimum distance in units between objects that remain in separate clusters.
   • minZoom: the minimum zoom level that displays clusters.

   clusterizedCollection.clusterPlacemarks(60.0, 15)
   

   Warning

   The ClusterizedPlacemarkCollection.clusterPlacemarks should be called explicitly whenever placemarks are added to or removed from clusterized collections.

   Otherwise, clusterized placemarks will be not re-rendered.

   Clusterized placemarks at different zooms:

   

Source codeSource code

For full code samples from the tutorial, see the map-objects application in our GitHub repository.