Getting Started

The section offers a comprehensive guide on seamlessly integrating the SDK into your existing iOS application. Whether starting a new project or enhancing an existing one, this section provides step-by-step instructions to ensure a smooth integration process.

1. To begin, the section covers the prerequisites, outlining the requirements you need to meet before integrating the iOS Maps SDK. This includes any necessary software versions or frameworks that need to be installed.

2. Next, the section walks you through installing Carthage, a dependency manager and the Maps SDK itself. Carthage simplifies the process of adding external frameworks to your project, making the integration process efficient and hassle-free.

3. Once the necessary dependencies are in place, the section guides you through the configuration of your application. This involves setting up the necessary API key, configuring permissions and any other relevant configurations to ensure seamless functionality.

4. With the initial setup complete, the section then focuses on displaying the first MapView in your application. By following the provided instructions, you'll be able to showcase a map interface within your app, ready for further customization and interaction.

5. Finally, the section covers the crucial aspect of plotting annotations on the MapView. Annotations serve as markers on the map, representing points of interest or specific locations. You'll learn how to add and customize these annotations, enabling you to enrich your map with relevant information and visuals.

Prerequisites

Before integrating the iOS Maps SDK into the application, there are a few prerequisites that need to be fulfilled:

1. Access Key: To utilize the iOS Maps SDK, you'll need an Access Key. If you haven't obtained one yet, feel free to contact us to obtain the necessary credentials.

2. Xcode 13.2.1: Ensure that you have Xcode 13.2.1, or a compatible version, installed on your development machine. Xcode is the integrated development environment (IDE) used for iOS app development, and having the appropriate version is crucial for a smooth integration process.

3. Minimum deployment target: The minimum deployment target for your application should be iOS 11.0 or later. This ensures compatibility with a wide range of iOS devices and allows your app to reach a broader user base.

4. Carthage v0.39 or above

By meeting these prerequisites, you'll be ready to proceed with the integration of the iOS Maps SDK by Nextbillion.ai.

Installation

Before integrating any map-related features into an iOS application, it is essential to install the Nextbillion iOS Maps SDK within the iOS development environment.

This installation process involves configuring Xcode project settings and adding the required dependencies to the projects. This guide aims to give developers an overview of the necessary steps to install the iOS Maps SDK, empowering them to seamlessly integrate advanced navigation functionalities into their iOS applications.

SDK Installation

Install Carthage

According to the official docs of Carthage:

1. Carthage is intended to be the simplest way to add frameworks to your Cocoa application.

2. Carthage builds your dependencies and provides you with binary frameworks, but you retain full control over your project structure and setup. Carthage does not automatically modify your project files or your build settings.

There are multiple options for installing Carthage:

1. (Recommended) Homebrew: You can use Homebrew and install the carthage tool on your system simply by running brew update and brew install carthage. (note: if you previously installed the binary version of Carthage, you should delete /Library/Frameworks/CarthageKit.framework).

   

2. Installer: Download and run the Carthage.pkg file for the latest release, then follow the on-screen instructions. If you are installing the pkg via CLI, you might need to run sudo chown -R $(whoami) /usr/local first.

3. MacPorts: You can use MacPorts and install the carthage tool on your system simply by running sudo port selfupdate and sudo port install carthage. (note: if you previously installed the binary version of Carthage, you should delete /Library/Frameworks/CarthageKit.framework).

4. From source: If you’d like to run the latest development version (which may be highly unstable or incompatible), simply clone the master branch of the repository, then run make install. Requires Xcode 10.0 (Swift 4.2).

Create Your Project Folder

To proceed with the instructions below, you should first create an empty iOS app project or clone one from our GitHub repository.

1. In Xcode, navigate to File > New > Project.

2. In the popup window, select iOS > App and click Next.

3. Fill in your project details in the subsequent screen, then click Next to finalize the creation of an empty project.

Alternatively, you can clone our official GitHub example code repository using the command line:

1git clone [email protected]:nextbillion-ai/ios-map-example.git
2cd ios-map-example

In the next section, we will execute specific commands within this project to complete the configuration.

Install SDK

To install the Nbmap framework using Carthage v0.39 or above.

1. (Optional) Clear your Carthage caches, If you have downloaded the sdk before, it is recommended to execute the following commands before updating the SDK :

1rm -rf ~/Library/Caches/carthage/ ~/Library/Caches/org.carthage.CarthageKit/binaries/{Nbmap}

2. Create a Cartfile with the following dependency: Create Cartfile in the project directory

1touch Cartfile

Open the Cartfile and Copy in the following dependencies in it

1binary "https://github.com/nextbillion-ai/nextbillion-map-ios/releases/download/v1/carthage/Nbmap.json" ~> 1.0.2

3. Run

1carthage update --use-xcframeworks

4. Link the following framework into your build phases:

1Nbmap

Configuration

The "Configuration" section of the iOS Maps SDK by Nextbillion provides instructions on how to configure important settings to enable the proper functioning of the SDK within your iOS application. This section covers two key configurations: Access Key and Base URI.

Access Key

In order to utilize Nextbillion's Maps and SDK, you need to specify your secret key as NBMapAccessKey in the Info.plist file. This access key serves as the authentication mechanism to ensure secure access to Nextbillion.ai's mapping services.

Base URI (Optional)

Similarly, we can configure a different base Uri if applicable by specifying the base uri as NBMapBaseUri in the info.plist file.

Add first Mapview

Incorporating a map into your iOS application is made easy with our SDK, which provides a preconfigured style for seamless integration. The provided code snippet showcases how to add a MapView to your application with minimal effort.

1class MapViewController: UIViewController {
2    var nbMapView: NGLMapView! {
3        didSet {
4            oldValue?.removeFromSuperview()
5            if let mapView = nbMapView {
6                configureMapView(nbMapView)
7                view.insertSubview(mapView, at: 0)
8            }
9        }
10    }
11    
12    func configureMapView(_ mapView: NGLMapView) {
13        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
14        
15    }
16    
17    override func viewDidLoad() {
18        super.viewDidLoad()
19        nbMapView = NGLMapView(frame:self.view.bounds)
20    }
21}

Code Summary

To begin, you'll need to create a MapViewController class that inherits from UIViewController. Inside this class, you'll find a variable named "nbMapView" of type NGLMapView. This variable is responsible for managing the MapView instance.

The didSet property observer ensures that the previous MapView instance is removed from the superview when a new instance is assigned to nbMapView. It then configures the new MapView by calling the configureMapView() function and inserts it as a subview in the view hierarchy.

The configureMapView() function allows for additional customization of the MapView. In the provided code, it sets the autoresizing mask to ensure the MapView adjusts its size based on its parent view.

Within the viewDidLoad() method of the MapViewController, a new instance of NGLMapView is created and assigned to the nbMapView variable. This initializes the MapView and sets its frame to match the bounds of the view controller's view. By following this example, you'll be able to quickly add the first MapView to your iOS application, providing a foundation for further customization and interaction with the map.

Move camera position

In the process of working with a map in your iOS application, it may be necessary to adjust the camera position to focus on a specific location or area. This can be achieved by utilizing the Move Camera Position functionality provided by our SDK.

To demonstrate this, the provided code snippet shows how to move the map camera position to a desired location.

1import Foundation
2import UIKit
3import Nbmap
4class MapViewController: UIViewController {
5    
6    var nbMapView: NGLMapView! {
7        didSet {
8            oldValue?.removeFromSuperview()
9            if let mapView = nbMapView {
10                configureMapView(nbMapView)
11                view.insertSubview(mapView, at: 0)
12                mapView.delegate = self
13            }
14        }
15    }
16    
17    
18    func configureMapView(_ mapView: NGLMapView) {
19        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
20        
21    }
22    
23    override func viewDidLoad() {
24        super.viewDidLoad()
25        nbMapView = NGLMapView(frame:self.view.bounds)
26    }
27}
28
29extension MapViewController: NGLMapViewDelegate {
30    func mapView(_ mapView: NGLMapView, didFinishLoading style: NGLStyle){
31        
32        let camera = NGLMapCamera(lookingAtCenter: CLLocationCoordinate2DMake(12.97780156, 77.59656748),
33                                  acrossDistance:10000,
34                                  pitch:0,
35                                  heading:0)
36        nbMapView.fly(to: camera)
37        
38    }
39}

In the MapViewController class, a mapView delegate is set, allowing for the execution of custom behaviors when the map finishes loading.

Inside the mapView(_:didFinishLoading:) delegate method, a new NGLMapCamera instance is created. This camera object specifies the desired position by providing the coordinates of the center location, the distance across the view, the pitch and the heading. Adjust these values as needed to achieve the desired camera position. Finally, the nbMapView.fly(to:) method is called, triggering the map to animate smoothly to the specified camera position. This provides a visually pleasing transition for the user.

By following this example, you can easily implement the Move Camera Position functionality in your iOS application, allowing you to dynamically adjust the view and focus on specific areas or locations within the map.

Annotations

Annotations play a crucial role in providing visual markers and information on a map within an iOS application. They allow developers to highlight points of interest, specific locations, or custom data on the map surface. With the help of our SDK, incorporating annotations into your iOS application becomes effortless.

Add Markers to MapView

Adding markers to a MapView is a fundamental task when working with maps in an iOS application. Markers serve as visual indicators on the map to represent specific locations or points of interest. With the help of our iOS SDK, incorporating markers into your MapView becomes a seamless process.

The provided code snippet demonstrates how to add markers to the MapView.

1import Foundation
2import UIKit
3import Nbmap
4class MarkerViewController: UIViewController {
5    
6    var nbMapView: NGLMapView! {
7        didSet {
8            oldValue?.removeFromSuperview()
9            if let mapView = nbMapView {
10                view.insertSubview(mapView, at: 0)
11                mapView.delegate = self
12            }
13        }
14    }
15    
16    var points : Array = [CLLocationCoordinate2D]()
17    
18    override func viewDidLoad() {
19        super.viewDidLoad()
20        nbMapView = NGLMapView(frame:self.view.bounds)
21        addMarker()
22    }
23    
24    func addMarker(){
25        let locations: [CLLocationCoordinate2D] =  [
26            CLLocationCoordinate2D(latitude: 12.97780156, longitude: 77.59656748),
27            CLLocationCoordinate2D(latitude: 12.98208919, longitude: 77.60329262)
28        ]
29        
30        if let currentAnnotations = nbMapView.annotations {
31            nbMapView.removeAnnotations(currentAnnotations)
32        }
33        
34        nbMapView.addAnnotations(locations.map({(coord)->
35            NGLPointAnnotation in
36            let annotation = NGLPointAnnotation()
37            annotation.coordinate = coord
38            return annotation
39        }))
40        
41    }
42}
43
44extension MarkerViewController: NGLMapViewDelegate {
45    func mapView(_ mapView: NGLMapView, didFinishLoading style: NGLStyle){
46        
47        let camera = NGLMapCamera(lookingAtCenter: CLLocationCoordinate2DMake(12.97780156, 77.59656748),
48                                  acrossDistance:10000,
49                                  pitch:0,
50                                  heading:0)
51        nbMapView.fly(to: camera)
52        
53    }
54}

In the MarkerViewController class, the nbMapView instance is set up and configured. The addMarker() method is then called, which adds multiple markers to the MapView. Inside the addMarker() method, an array of CLLocationCoordinate2D objects is created, representing the desired marker locations. The current annotations on the MapView are first removed, and then new NGLPointAnnotation objects are added for each coordinate in the array. These annotations are customized with their respective coordinates. By utilizing the addAnnotations() method of the MapView, the markers are added to the map surface, visually representing the specified locations. In the mapView(_:didFinishLoading:) delegate method, a camera position is set to focus on a specific coordinate, ensuring that the markers are visible on the MapView. The nbMapView.fly(to:) method is then called to animate the camera movement to the specified position.

By following this example and incorporating the provided code into your iOS application, you can easily add markers to the MapView, enabling you to highlight important locations or points of interest within your map-based application.

Add a Polyline to MapView

Adding a polyline to a MapView can greatly enhance the visual representation of routes or paths in your iOS application. Our SDK simplifies the process of incorporating a polyline by providing a default polyline style that you can easily integrate.

The provided code snippet demonstrates how to add a polyline to the MapView.

1import Foundation
2import UIKit
3import Nbmap
4class MapViewController: UIViewController {
5    
6    var nbMapView: NGLMapView! {
7        didSet {
8            oldValue?.removeFromSuperview()
9            if let mapView = nbMapView {
10                configureMapView(nbMapView)
11                view.insertSubview(mapView, at: 0)
12                mapView.delegate = self
13                drawPolyline()
14            }
15        }
16    }
17    
18    let locations: [CLLocationCoordinate2D] =  [
19               CLLocationCoordinate2D(latitude: 12.92948165, longitude: 77.61501446),
20               CLLocationCoordinate2D(latitude: 12.95205978, longitude: 77.60494206),
21               CLLocationCoordinate2D(latitude: 12.96612918, longitude: 77.60678866),
22               CLLocationCoordinate2D(latitude: 12.96449325, longitude: 77.59654839)
23           ]
24    func drawPolyline(){
25        if(locations.count > 1){
26            let line = NGLPolyline(coordinates:locations,count: UInt(locations.count))
27            nbMapView.addAnnotation(line)
28            
29        }
30    }
31    
32    func configureMapView(_ mapView: NGLMapView) {
33        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
34        
35    }
36    
37    override func viewDidLoad() {
38        super.viewDidLoad()
39        nbMapView = NGLMapView(frame:self.view.bounds)
40    }
41}
42
43extension MapViewController: NGLMapViewDelegate {
44    func mapView(_ mapView: NGLMapView, didFinishLoading style: NGLStyle){
45        let camera = NGLMapCamera(lookingAtCenter: CLLocationCoordinate2DMake(12.96612918, 77.60678866),
46                                  acrossDistance:20000,
47                                  pitch:0,
48                                  heading:0)
49        nbMapView.fly(to: camera)
50        
51    }
52}

In the MapViewController class, the nbMapView instance is set up and configured. The drawPolyline() method is called within the didSet property observer of nbMapView, ensuring that the polyline is drawn when the MapView is ready. Inside the drawPolyline() method, a polyline is created using the provided array of CLLocationCoordinate2D objects. This array represents the coordinates that form the points of the polyline. If the array contains more than one coordinate, the polyline is added as an annotation to the MapView using the nbMapView.addAnnotation() method. In the mapView(_:didFinishLoading:) delegate method, a camera position is set to focus on a specific coordinate, ensuring that the added polyline is visible on the MapView. The nbMapView.fly(to:) method is then called to animate the camera movement to the specified position.

By following this example and incorporating the provided code into your iOS application, you can easily add a polyline to the MapView. The specified coordinates will be connected by a line, allowing you to display routes, paths, or any other desired lines on the map. With the ability to add polylines to the MapView, you can effectively visualize routes, highlight paths, or display other line-based information within your map-based iOS application.

Add a Polygon to MapView

Incorporating polygons into your MapView can be an effective way to highlight specific areas or define boundaries in your iOS application. With our SDK, adding a polygon to the MapView is made simple by following a similar logic to that of drawing polylines. The provided code snippet demonstrates how to add a polygon to the MapView.

1import Foundation
2import UIKit
3import Nbmap
4class MapViewController: UIViewController {
5    
6    var nbMapView: NGLMapView! {
7        didSet {
8            oldValue?.removeFromSuperview()
9            if let mapView = nbMapView {
10                configureMapView(nbMapView)
11                view.insertSubview(mapView, at: 0)
12                mapView.delegate = self
13                drawPolygon()
14            }
15        }
16    }
17    
18    let locations: [CLLocationCoordinate2D] =  [
19        CLLocationCoordinate2D(latitude: 12.92948165, longitude: 77.61501446),
20        CLLocationCoordinate2D(latitude: 12.95205978, longitude: 77.60494206),
21        CLLocationCoordinate2D(latitude: 12.96612918, longitude: 77.60678866),
22        CLLocationCoordinate2D(latitude: 12.96449325, longitude: 77.59654839)
23    ]
24    
25    func drawPolygon(){
26        if let currentAnnotations = nbMapView.annotations {
27            nbMapView.removeAnnotations(currentAnnotations)
28        }
29        
30        let polygon: NGLPolygon = NGLPolygon.init(coordinates: locations, count: UInt(locations.count))
31        nbMapView.addAnnotation(polygon)
32    }
33    
34    func configureMapView(_ mapView: NGLMapView) {
35        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
36        
37    }
38    
39    override func viewDidLoad() {
40        super.viewDidLoad()
41        nbMapView = NGLMapView(frame:self.view.bounds)
42    }
43}
44
45extension MapViewController: NGLMapViewDelegate {
46    func mapView(_ mapView: NGLMapView, didFinishLoading style: NGLStyle){
47        
48        let camera = NGLMapCamera(lookingAtCenter: CLLocationCoordinate2DMake(12.96612918, 77.60678866),
49                                  acrossDistance:20000,
50                                  pitch:0,
51                                  heading:0)
52        nbMapView.fly(to: camera)
53    }
54}

Inside the MapViewController class, the nbMapView instance is set up and configured. The drawPolygon() method is called within the didSet property observer of nbMapView, ensuring that the polygon is drawn when the MapView is ready. Within the drawPolygon() method, a polygon is created using the array of CLLocationCoordinate2D objects. These coordinates define the vertices of the polygon, and the count parameter specifies the number of vertices in the array. If there are existing annotations on the MapView, they are removed before adding the polygon annotation using the nbMapView.addAnnotation() method. In the mapView(_:didFinishLoading:) delegate method, a camera position is set to focus on a specific coordinate, ensuring that the added polygon is visible on the MapView. The nbMapView.fly(to:) method is then called to animate the camera movement to the specified position.

By following this example and incorporating the provided code into your iOS application, you can easily add a polygon to the MapView. The specified coordinates will form the boundary of the polygon, allowing you to visually represent areas or boundaries on the map. With the ability to add polygons to the MapView, you can effectively showcase specific areas, boundaries, or any other enclosed regions within your map-based iOS application.

Add a Route Line to MapView

Adding a route line to your MapView can enhance your iOS application by displaying directions between two points. With our SDK, you can easily incorporate a directions route line into your MapView with just a few steps.

The provided code snippet shows how to add a route line to the MapView.

1import Foundation
2import UIKit
3import Nbmap
4class MapViewController: UIViewController {
5    
6    var nbMapView: NGLMapView! {
7        didSet {
8            oldValue?.removeFromSuperview()
9            if let mapView = nbMapView {
10                configureMapView(nbMapView)
11                view.insertSubview(mapView, at: 0)
12                mapView.delegate = self
13                drawDirections()
14            }
15        }
16    }
17    
18    let locations: [CLLocationCoordinate2D] =  [
19        CLLocationCoordinate2D(latitude: 12.96206481, longitude: 77.56687669),
20        CLLocationCoordinate2D(latitude: 12.99150562, longitude: 77.61940507)
21    ]
22    
23    func drawDirections(){        
24        nbMapView.addAnnotations(locations.map({(coord)->
25            NGLPointAnnotation in
26            let annotation = NGLPointAnnotation()
27            annotation.coordinate = coord
28            return annotation
29        }))
30        
31        let apiClient: NBAPIClient = NBAPIClient()
32        apiClient.getDirections(locations) { [weak self] resp in
33            guard let weakSelf = self else {
34                return
35            }
36            let first = resp?.routes.first;
37            if first is NBRoute {
38                let route:NBRoute? = first as? NBRoute
39                let geometry = route?.geometry
40                let routeline = GeometryDecoder.covert(toFeature: geometry, precision:5)
41                let routeSource = NGLShapeSource.init(identifier: "route-style-source", shape: routeline)
42                weakSelf.nbMapView.style?.addSource(routeSource)
43                let routeLayer = NGLLineStyleLayer.init(identifier: "route-layer", source: routeSource)
44                routeLayer.lineColor = NSExpression.init(forConstantValue: UIColor.red)
45                routeLayer.lineWidth = NSExpression.init(forConstantValue: 2)
46                
47                weakSelf.nbMapView.style?.addLayer(routeLayer)
48            }
49        }
50    }
51    
52    func configureMapView(_ mapView: NGLMapView) {
53        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
54        
55    }
56    
57    override func viewDidLoad() {
58        super.viewDidLoad()
59        nbMapView = NGLMapView(frame:self.view.bounds)
60    }
61}
62
63extension MapViewController: NGLMapViewDelegate {
64    func mapView(_ mapView: NGLMapView, didFinishLoading style: NGLStyle){        
65        let camera = NGLMapCamera(lookingAtCenter: CLLocationCoordinate2DMake(12.96206481, 77.56687669),
66                                  acrossDistance:50000,
67                                  pitch:0,
68                                  heading:0)
69        nbMapView.fly(to: camera)
70        
71    }
72}

Inside the MapViewController class, the nbMapView instance is set up and configured. The drawDirections() method is called within the didSet property observer of nbMapView, ensuring that the route line is drawn when the MapView is ready. In the drawDirections() method, the coordinates of the starting and ending points are specified in the locations array. These coordinates represent the start and end locations of the route. NGLPointAnnotation objects are created for each coordinate and added to the MapView using the nbMapView.addAnnotations() method. The NBAPIClient is used to retrieve the directions between the specified locations. The getDirections() method is called, passing in the locations array. In the completion block, the response is obtained, and the route line is drawn on the map. The route geometry is extracted from the response, and using the GeometryDecoder, it is converted into an NGLShape representing the route line. A shape source and line layer are created based on the route line data. The routeLayer is customized by setting its line color and width. Finally, the shape source and line layer are added to MapView's style. In the mapView(_:didFinishLoading:) delegate method, a camera position is set to focus on a specific coordinate, ensuring that the added route line is visible on the MapView. The nbMapView.fly(to:) method is then called to animate the camera movement to the specified position.

By following this example and incorporating the provided code into your iOS application, you can easily add a route line to the MapView, showing directions between two points. The route line will be displayed on the map, providing a visual representation of the suggested route. With the ability to add a route line to MapView, you can enrich your iOS application with interactive and informative directions, making it more engaging and user-friendly.