Work with maps

Install Amplify-MapLibre adapter

First, ensure you've provisioned an Amazon Location Service Map resource and configured your app using the instructions in either Configure maps or Use existing resources guide.

Amplify-MapLibre is an open source adapter that enables the popular MapLibre SDK to work seamlessly with Amplify Geo.

1. To install the Amplify-MapLibre adapter to your application, open your project in Xcode and select File > Add Packages...

2. Enter the amplify-ios-maplibre GitHub repo URL (https://github.com/aws-amplify/amplify-ios-maplibre) into the search bar and hit Enter. Wait for the result to load. You'll see the repository rules for which version of amplify-ios-mapLibre you want Swift Package Manager to install.

3. Choose the dependency rule Up to Next Major Version, as it will use the latest compatible version of the dependency, then click Add Package.

4. Lastly, choose which of the libraries you want added to your project. If you want to use the SwiftUI user interface components provided by the adapter, select both AmplifyMapLibreAdapter and AmplifyMapLibreUI. If you only want to enable Amplify Geo to work directly with MapLibre and do not wish use use the provided SwiftUI views, you can just select AmplifyMapLibreAdapter. After you select the libraries, click Add Package.

Display a map

First, ensure you've provisioned an Amazon Location Service Map resource and configured your app using the instructions in either Configure maps or Use existing resources guide.

Select your user interface

There are two ways to display a map. The easiest way to get started is to use the AmplifyMaplibreUI library to create an instance of AMLMapView. This is the recommended approach for new projects or anyone who wants to use SwiftUI.

Alternatively, if you are using UIKit or have existing code using the MapLibre/MapBox SDK, you can simply call AmplifyMapLibre.createMap(completionHandler:) to create an instance of MGLMapView that is pre-wired for use with Amazon Location Service and Amplify. For more information on using MGLMapView directly, please see the MapLibre Documentation

import SwiftUI
import AmplifyMapLibreUI

struct ContentView: View {    
    var body: some View {
        AMLMapView()
            .edgesIgnoringSafeArea(.all)
    }
}

import AmplifyMapLibreAdapter
import Mapbox
import Amplify

var mapView: MGLMapView?

AmplifyMapLibre.createMap { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let map):
        mapView = map
    }
}

import AmplifyMapLibreAdapter
import Mapbox
import Amplify

var mapView: MGLMapView?
do {
    mapView = try await AmplifyMapLibre.createMap()
} catch {
    print(error)
}

Customize the map and access state

The AMLMapView can be customized through a number of view modifiers. The map state information can be set and observed through an instance of AMLMapViewState, which can optionally be passed into AMLMapView to set initial values. The following example sets an initial zoom level and center location for the map and configures the map to show the user's location.

@StateObject private var mapState = AMLMapViewState(
    zoomLevel: 8,
    center: CLLocationCoordinate2D(latitude: 39.7392, longitude: -104.9903)
)

var body: some View {
    AMLMapView(mapState: mapState)
        .showUserLocation(true)
        .edgesIgnoringSafeArea(.all)
}

Inject custom behavior

The AMLMapView also allows for custom behavior triggered by user interaction to be injected. The following example sets a custom feature image and defines the maps behavior when that feature is tapped - zooming in two levels above the current level.

var body: some View {
    AMLMapView()
        .featureImage { MyCustomImage() }
        .featureTapped { mapView, pointFeature in
            mapView.setCenter(
                pointFeature.coordinate,
                zoomLevel: mapView.zoomLevel + 2,
                direction: mapView.camera.heading,
                animated: true
            )
        }
        .edgesIgnoringSafeArea(.all)
}

AMLMapCompositeView

The AMLMapCompositeView combines AMLMapView, AMLSearchBar, AMLMapControlView, and AMLPlaceCellView to create a full user experience. This includes accessible map control buttons, a search bar that automatically searches for points of interest based on user input, and a list representation of points. In its simplest form, which still leverages all of the above mentioned functionality, the AMLMapCompositeView can be instantiated without any arguments. All of the view modifiers and state tracking capabilities of AMLMapView are also available on AMLMapCompositeView.

var body: some View {
    AMLMapCompositeView()
}

Display different map styles

The availableMaps API fetches information for all maps that are available to be displayed.

This is useful if you would like to give your users a variety of maps styles to choose from.

var maps = [Geo.MapStyle]()
do {
    maps = try await Amplify.Geo.availableMaps()
} catch let error as Geo.Error {
    print("Failed to get available maps: \(error)")
} catch {
    print("Unexpected error: \(error)")
}

You can load a different style map by passing it to the createMap function.

guard let mapStyle = maps.first else {
    print("No maps available")
    return
}

let mapView = AmplifyMapLibre.createMap(mapStyle)