Inherits from UIView
Declared in MGLMapView.h

Overview

An MGLMapView object provides an embeddable map interface, similar to the one provided by Apple’s MapKit. You use this class to display map information and to manipulate the map contents from your application. You can center the map on a given coordinate, specify the size of the area you want to display, and style the features of the map to fit your application’s use case.

Use of MGLMapView requires a Mapbox API access token. Obtain an access token on the Mapbox account page. If you instantiate an MGLMapView from Interface Builder, rendering of the map won’t begin until the accessToken property has been set.

Warning: Please note that you are responsible for getting permission to use the map data, and for ensuring your use adheres to the relevant terms of use.

Tasks

Initializing a Map View

Accessing Map Properties

Manipulating the Visible Portion of the Map

Converting Map Coordinates

Styling the Map

Annotating the Map

Managing Annotation Selections

Adding Overlays

Removing Overlays

Displaying the User's Location

Debugging

Properties

annotations

The complete list of annotations associated with the receiver. (read-only)

@property (nonatomic, readonly, nullable) NSArray<id<MGLAnnotation> > *annotations

Discussion

The complete list of annotations associated with the receiver. (read-only)

The objects in this array must adopt the MGLAnnotation protocol. If no annotations are associated with the map view, the value of this property is nil.

Declared In

MGLMapView.h

attributionButton

The button shown in the lower-right of the map which when pressed displays the map attribution information.

@property (nonatomic, readonly) UIButton *attributionButton

Discussion

The button shown in the lower-right of the map which when pressed displays the map attribution information.

Declared In

MGLMapView.h

bundledStyleURLs

URLs of the styles bundled with the library. (Deprecated: Call the relevant class method of MGLStyle for the URL of a particular default style. )

@property (nonatomic, readonly) NSArray<NSURL*> *bundledStyleURLs

Discussion

URLs of the styles bundled with the library.

Declared In

MGLMapView.h

camera

A camera representing the current viewpoint of the map.

@property (nonatomic, copy) MGLMapCamera *camera

Discussion

A camera representing the current viewpoint of the map.

Declared In

MGLMapView.h

centerCoordinate

The map coordinate at the center of the map view.

@property (nonatomic) CLLocationCoordinate2D centerCoordinate

Discussion

The map coordinate at the center of the map view.

Changing the value in this property centers the map on the new coordinate without changing the current zoom level.

Changing the value of this property updates the map view immediately. If you want to animate the change, use the setCenterCoordinate:animated: method instead.

Declared In

MGLMapView.h

compassView

The compass image view shown in the upper-right when the map is rotated.

@property (nonatomic, readonly) UIImageView *compassView

Discussion

The compass image view shown in the upper-right when the map is rotated.

Declared In

MGLMapView.h

debugActive

A Boolean value that determines whether map debugging information is shown.

@property (nonatomic, getter=isDebugActive) BOOL debugActive

Discussion

A Boolean value that determines whether map debugging information is shown.

The default value of this property is NO.

Declared In

MGLMapView.h

direction

The heading of the map (measured in degrees) relative to true north.

@property (nonatomic) CLLocationDirection direction

Discussion

The heading of the map (measured in degrees) relative to true north.

The value 0 means that the top edge of the map view corresponds to true north. The value 90 means the top of the map is pointing due east. The value 180 means the top of the map points due south, and so on.

Declared In

MGLMapView.h

displayHeadingCalibration

Whether the map view should display a heading calibration alert when necessary. The default value is YES.

@property (nonatomic, assign) BOOL displayHeadingCalibration

Discussion

Whether the map view should display a heading calibration alert when necessary. The default value is YES.

Declared In

MGLMapView.h

logoView

The Mapbox logo image view shown in the lower-left of the map.

@property (nonatomic, readonly) UIImageView *logoView

Discussion

The Mapbox logo image view shown in the lower-left of the map.

Declared In

MGLMapView.h

pitchEnabled

A Boolean value that determines whether the user may change the pitch (tilt) of the map.

@property (nonatomic, getter=isPitchEnabled) BOOL pitchEnabled

Discussion

A Boolean value that determines whether the user may change the pitch (tilt) of the map.

This property controls only user interactions with the map. If you set the value of this property to NO, you may still change the pitch of the map programmatically.

The default value of this property is YES.

Declared In

MGLMapView.h

rotateEnabled

A Boolean value that determines whether the user may rotate the map.

@property (nonatomic, getter=isRotateEnabled) BOOL rotateEnabled

Discussion

A Boolean value that determines whether the user may rotate the map.

This property controls only user interactions with the map. If you set the value of this property to NO, you may still rotate the map programmatically.

The default value of this property is YES.

Declared In

MGLMapView.h

scrollEnabled

A Boolean value that determines whether the user may scroll around the map.

@property (nonatomic, getter=isScrollEnabled) BOOL scrollEnabled

Discussion

A Boolean value that determines whether the user may scroll around the map.

This property controls only user interactions with the map. If you set the value of this property to NO, you may still change the map location programmatically.

The default value of this property is YES.

Declared In

MGLMapView.h

selectedAnnotations

The annotations that are currently selected.

@property (nonatomic, copy) NSArray<id<MGLAnnotation> > *selectedAnnotations

Discussion

The annotations that are currently selected.

Assigning a new array to this property selects only the first annotation in the array.

Declared In

MGLMapView.h

showsUserLocation

A Boolean value indicating whether the map may display the user location.

@property (nonatomic, assign) BOOL showsUserLocation

Discussion

A Boolean value indicating whether the map may display the user location.

This property does not indicate whether the user’s position is actually visible on the map, only whether the map view is allowed to display it. To determine whether the user’s position is visible, use the userLocationVisible property. The default value of this property is NO.

Setting this property to YES causes the map view to use the Core Location framework to find the current location. As long as this property is YES, the map view continues to track the user’s location and update it periodically.

On iOS 8 and above, your app must specify a value for NSLocationWhenInUseUsageDescription or NSLocationAlwaysUsageDescription in its Info.plist to satisfy the requirements of the underlying Core Location framework when enabling this property.

Declared In

MGLMapView.h

styleClasses

Currently active style classes, represented as an array of string identifiers.

@property (nonatomic) NSArray<NSString*> *styleClasses

Discussion

Currently active style classes, represented as an array of string identifiers.

Declared In

MGLMapView.h

styleURL

URL of the style currently displayed in the receiver.

@property (nonatomic, null_resettable) NSURL *styleURL

Discussion

URL of the style currently displayed in the receiver.

The URL may be a full HTTP or HTTPS URL or a Mapbox URL indicating the style’s map ID (mapbox://styles/<user>/<style>).

To display the default style, set this property to nil.

Declared In

MGLMapView.h

userLocation

Returns the annotation object indicating the user’s current location.

@property (nonatomic, readonly, nullable) MGLUserLocation *userLocation

Discussion

Returns the annotation object indicating the user’s current location.

Declared In

MGLMapView.h

userLocationVisible

A Boolean value indicating whether the device’s current location is visible in the map view. (read-only)

@property (nonatomic, assign, readonly, getter=isUserLocationVisible) BOOL userLocationVisible

Discussion

A Boolean value indicating whether the device’s current location is visible in the map view. (read-only)

Declared In

MGLMapView.h

userTrackingMode

The mode used to track the user location.

@property (nonatomic, assign) MGLUserTrackingMode userTrackingMode

Discussion

The mode used to track the user location.

Declared In

MGLMapView.h

visibleCoordinateBounds

The coordinate bounds visible in the receiver’s viewport.

@property (nonatomic) MGLCoordinateBounds visibleCoordinateBounds

Discussion

The coordinate bounds visible in the receiver’s viewport.

Changing the value of this property updates the receiver immediately. If you want to animate the change, call setVisibleCoordinateBounds:animated: instead.

Declared In

MGLMapView.h

zoomEnabled

A Boolean value that determines whether the user may zoom the map.

@property (nonatomic, getter=isZoomEnabled) BOOL zoomEnabled

Discussion

A Boolean value that determines whether the user may zoom the map.

This property controls only user interactions with the map. If you set the value of this property to NO, you may still change the map zoom programmatically.

The default value of this property is YES.

Declared In

MGLMapView.h

zoomLevel

The zoom level of the map view.

@property (nonatomic) double zoomLevel

Discussion

The zoom level of the map view.

Changing the value in this property zooms the map in or out without changing the center coordinate. At zoom level 0, tiles cover the entire world map; at zoom level 1, tiles cover ¼ of the world; at zoom level 2, tiles cover 1/16 of the world, and so on.

Changing the value of this property updates the map view immediately. If you want to animate the change, use the setZoomLevel:animated: method instead.

Declared In

MGLMapView.h

Instance Methods

addAnnotation:

Adds the specified annotation to the map view.

- (void)addAnnotation:(id<MGLAnnotation>)annotation

Parameters

annotation

The annotation object to add to the receiver. This object must conform to the MGLAnnotation protocol. The map view retains the specified object.

Discussion

Adds the specified annotation to the map view.

Declared In

MGLMapView.h

addAnnotations:

Adds an array of annotation objects to the map view.

- (void)addAnnotations:(NSArray<id<MGLAnnotation> > *)annotations

Parameters

annotations

An array of annotation objects. Each object in the array must conform to the MGLAnnotation protocol. The map view retains the individual annotation objects.

Discussion

Adds an array of annotation objects to the map view.

Declared In

MGLMapView.h

addOverlay:

Adds a single overlay object to the map.

- (void)addOverlay:(id<MGLOverlay>)overlay

Parameters

overlay

The overlay object to add. This object must conform to the MGLOverlay protocol.

Discussion

Adds a single overlay object to the map.

To remove an overlay from a map, use the removeOverlay: method.

Declared In

MGLMapView.h

addOverlays:

Adds an array of overlay objects to the map.

- (void)addOverlays:(NSArray<id<MGLOverlay> > *)overlays

Parameters

overlays

An array of objects, each of which must conform to the MGLOverlay protocol.

Discussion

Adds an array of overlay objects to the map.

To remove multiple overlays from a map, use the removeOverlays: method.

Declared In

MGLMapView.h

addStyleClass:

Activates the style class with the given identifier.

- (void)addStyleClass:(NSString *)styleClass

Parameters

styleClass

The style class to activate.

Discussion

Activates the style class with the given identifier.

Declared In

MGLMapView.h

convertCoordinate:toPointToView:

Converts a map coordinate to a point in the specified view.

- (CGPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(nullable UIView *)view

Parameters

coordinate

The map coordinate for which you want to find the corresponding point.

view

The view in whose coordinate system you want to locate the specified map coordinate. If this parameter is nil, the returned point is specified in the window’s coordinate system. If view is not nil, it must belong to the same window as the map view.

Return Value

The point (in the appropriate view or window coordinate system) corresponding to the specified latitude and longitude value.

Discussion

Converts a map coordinate to a point in the specified view.

Declared In

MGLMapView.h

convertPoint:toCoordinateFromView:

Converts a point in the specified view’s coordinate system to a map coordinate.

- (CLLocationCoordinate2D)convertPoint:(CGPoint)point toCoordinateFromView:(nullable UIView *)view

Parameters

point

The point you want to convert.

view

The view that serves as the reference coordinate system for the point parameter.

Return Value

The map coordinate at the specified point.

Discussion

Converts a point in the specified view’s coordinate system to a map coordinate.

Declared In

MGLMapView.h

dequeueReusableAnnotationImageWithIdentifier:

Returns a reusable annotation image object located by its identifier.

- (nullable MGLAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:(NSString *)identifier

Parameters

identifier

A string identifying the annotation image to be reused. This string is the same one you specify when initially returning the annotation image object using the mapView:imageForAnnotation: method.

Return Value

An annotation image object with the specified identifier, or nil if no such object exists in the reuse queue.

Discussion

Returns a reusable annotation image object located by its identifier.

For performance reasons, you should generally reuse MGLAnnotationImage objects for annotations in your map views. Dequeueing saves time and memory during performance-critical operations such as scrolling.

Declared In

MGLMapView.h

deselectAnnotation:animated:

Deselects the specified annotation and hides its callout view.

- (void)deselectAnnotation:(id<MGLAnnotation>)annotation animated:(BOOL)animated

Parameters

annotation

The annotation object to deselect.

animated

If YES, the callout view is animated offscreen.

Discussion

Deselects the specified annotation and hides its callout view.

Declared In

MGLMapView.h

emptyMemoryCache

Empties the in-memory tile cache.

- (void)emptyMemoryCache

Discussion

Empties the in-memory tile cache.

Declared In

MGLMapView.h

hasStyleClass:

Returns a Boolean value indicating whether the style class with the given identifier is currently active.

- (BOOL)hasStyleClass:(NSString *)styleClass

Parameters

styleClass

The style class to query for.

Return Value

Whether the style class is currently active.

Discussion

Returns a Boolean value indicating whether the style class with the given identifier is currently active.

Declared In

MGLMapView.h

initWithFrame:

Initializes and returns a newly allocated map view with the specified frame and the default style.

- (instancetype)initWithFrame:(CGRect)frame

Parameters

frame

The frame for the view, measured in points.

Return Value

An initialized map view.

Discussion

Initializes and returns a newly allocated map view with the specified frame and the default style.

Declared In

MGLMapView.h

initWithFrame:styleURL:

Initializes and returns a newly allocated map view with the specified frame and style URL.

- (instancetype)initWithFrame:(CGRect)frame styleURL:(nullable NSURL *)styleURL

Parameters

frame

The frame for the view, measured in points.

styleURL

The map style URL to use. Can be either an HTTP/HTTPS URL or a Mapbox map ID style URL (mapbox://styles/<user>/<style>). Specify nil for the default style.

Return Value

An initialized map view.

Discussion

Initializes and returns a newly allocated map view with the specified frame and style URL.

Declared In

MGLMapView.h

metersPerPixelAtLatitude:

Returns the distance spanned by one pixel at the specified latitude and current zoom level.

- (CLLocationDistance)metersPerPixelAtLatitude:(CLLocationDegrees)latitude

Parameters

latitude

The latitude for which to return the value.

Return Value

The distance (in meters) spanned by a single pixel.

Discussion

Returns the distance spanned by one pixel at the specified latitude and current zoom level.

The distance between pixels decreases as the latitude approaches the poles. This relationship parallels the relationship between longitudinal coordinates at different latitudes.

Declared In

MGLMapView.h

removeAnnotation:

Removes the specified annotation object from the map view.

- (void)removeAnnotation:(id<MGLAnnotation>)annotation

Parameters

annotation

The annotation object to remove. This object must conform to the MGLAnnotation protocol.

Discussion

Removes the specified annotation object from the map view.

Removing an annotation object disassociates it from the map view entirely, preventing it from being displayed on the map. Thus, you would typically call this method only when you want to hide or delete a given annotation.

Declared In

MGLMapView.h

removeAnnotations:

Removes an array of annotation objects from the map view.

- (void)removeAnnotations:(NSArray<id<MGLAnnotation> > *)annotations

Parameters

annotations

The array of annotations to remove. Objects in the array must conform to the MGLAnnotation protocol.

Discussion

Removes an array of annotation objects from the map view.

Removing annotation objects disassociates them from the map view entirely, preventing them from being displayed on the map. Thus, you would typically call this method only when you want to hide or delete the specified annotations.

Declared In

MGLMapView.h

removeOverlay:

Removes a single overlay object from the map.

- (void)removeOverlay:(id<MGLOverlay>)overlay

Parameters

overlay

The overlay object to remove.

Discussion

Removes a single overlay object from the map.

If the specified overlay is not currently associated with the map view, this method does nothing.

Declared In

MGLMapView.h

removeOverlays:

Removes one or more overlay objects from the map.

- (void)removeOverlays:(NSArray<id<MGLOverlay> > *)overlays

Parameters

overlays

An array of objects, each of which conforms to the MGLOverlay protocol.

Discussion

Removes one or more overlay objects from the map.

If a given overlay object is not associated with the map view, it is ignored.

Declared In

MGLMapView.h

removeStyleClass:

Deactivates the style class with the given identifier.

- (void)removeStyleClass:(NSString *)styleClass

Parameters

styleClass

The style class to deactivate.

Discussion

Deactivates the style class with the given identifier.

Declared In

MGLMapView.h

resetNorth

Resets the map rotation to a northern heading.

- (IBAction)resetNorth

Discussion

Resets the map rotation to a northern heading.

Declared In

MGLMapView.h

resetPosition

Resets the map to the minimum zoom level, a center coordinate of (0, 0), and a northern heading.

- (void)resetPosition

Discussion

Resets the map to the minimum zoom level, a center coordinate of (0, 0), and a northern heading.

Declared In

MGLMapView.h

selectAnnotation:animated:

Selects the specified annotation and displays a callout view for it.

- (void)selectAnnotation:(id<MGLAnnotation>)annotation animated:(BOOL)animated

Parameters

annotation

The annotation object to select.

animated

If YES, the callout view is animated into position.

Discussion

Selects the specified annotation and displays a callout view for it.

If the specified annotation is not onscreen, this method has no effect.

Declared In

MGLMapView.h

setCamera:animated:

Moves the viewpoint to a different location with respect to the map with an optional transition animation.

- (void)setCamera:(MGLMapCamera *)camera animated:(BOOL)animated

Parameters

camera

The new viewpoint.

animated

Specify YES if you want the map view to animate the change to the new viewpoint or NO if you want the map to display the new viewpoint immediately.

Discussion

Moves the viewpoint to a different location with respect to the map with an optional transition animation.

Declared In

MGLMapView.h

setCamera:withDuration:animationTimingFunction:

Moves the viewpoint to a different location with respect to the map with an optional transition duration and timing function.

- (void)setCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function

Parameters

camera

The new viewpoint.

duration

The amount of time, measured in seconds, that the transition animation should take. Specify 0 to jump to the new viewpoint instantaneously.

function

A timing function used for the animation. Set this parameter to nil for a transition that matches most system animations. If the duration is 0, this parameter is ignored.

Discussion

Moves the viewpoint to a different location with respect to the map with an optional transition duration and timing function.

Declared In

MGLMapView.h

setCenterCoordinate:animated:

Changes the center coordinate of the map and optionally animates the change.

- (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate animated:(BOOL)animated

Parameters

coordinate

The new center coordinate for the map.

animated

Specify YES if you want the map view to scroll to the new location or NO if you want the map to display the new location immediately.

Changing the center coordinate centers the map on the new coordinate without changing the current zoom level.

Discussion

Changes the center coordinate of the map and optionally animates the change.

Declared In

MGLMapView.h

setCenterCoordinate:zoomLevel:animated:

Changes the center coordinate and zoom level of the map and optionally animates the change.

- (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel animated:(BOOL)animated

Parameters

centerCoordinate

The new center coordinate for the map.

zoomLevel

The new zoom level for the map.

animated

Specify YES if you want the map view to animate scrolling and zooming to the new location or NO if you want the map to display the new location immediately.

Discussion

Changes the center coordinate and zoom level of the map and optionally animates the change.

Declared In

MGLMapView.h

setCenterCoordinate:zoomLevel:direction:animated:

Changes the center coordinate, zoom level, and direction of the map and optionally animates the change.

- (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel direction:(CLLocationDirection)direction animated:(BOOL)animated

Parameters

centerCoordinate

The new center coordinate for the map.

zoomLevel

The new zoom level for the map.

direction

The new direction for the map, measured in degrees relative to true north.

animated

Specify YES if you want the map view to animate scrolling, zooming, and rotating to the new location or NO if you want the map to display the new location immediately.

Discussion

Changes the center coordinate, zoom level, and direction of the map and optionally animates the change.

Declared In

MGLMapView.h

setDirection:animated:

Changes the heading of the map and optionally animates the changes.

- (void)setDirection:(CLLocationDirection)direction animated:(BOOL)animated

Parameters

direction

The heading of the map (measured in degrees) relative to true north.

animated

Specify YES if you want the map view to animate the change to the new heading or NO if you want the map to display the new heading immediately.

Changing the heading rotates the map without changing the current center coordinate or zoom level.

Discussion

Changes the heading of the map and optionally animates the changes.

Declared In

MGLMapView.h

setVisibleCoordinateBounds:animated:

Changes the receiver’s viewport to fit the given coordinate bounds, optionally animating the change.

- (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds animated:(BOOL)animated

Parameters

bounds

The bounds that the viewport will show in its entirety.

animated

Specify YES to animate the change by smoothly scrolling and zooming or NO to immediately display the given bounds.

Discussion

Changes the receiver’s viewport to fit the given coordinate bounds, optionally animating the change.

Declared In

MGLMapView.h

setVisibleCoordinateBounds:edgePadding:animated:

Changes the receiver’s viewport to fit the given coordinate bounds and optionally some additional padding on each side.

- (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds edgePadding:(UIEdgeInsets)insets animated:(BOOL)animated

Parameters

bounds

The bounds that the viewport will show in its entirety.

insets

The minimum padding (in screen points) that will be visible around the given coordinate bounds.

animated

Specify YES to animate the change by smoothly scrolling and zooming or NO to immediately display the given bounds.

Discussion

Changes the receiver’s viewport to fit the given coordinate bounds and optionally some additional padding on each side.

Declared In

MGLMapView.h

setVisibleCoordinates:count:edgePadding:animated:

Changes the receiver’s viewport to fit all of the given coordinates and optionally some additional padding on each side.

- (void)setVisibleCoordinates:(CLLocationCoordinate2D *)coordinates count:(NSUInteger)count edgePadding:(UIEdgeInsets)insets animated:(BOOL)animated

Parameters

coordinates

The coordinates that the viewport will show.

count

The number of coordinates. This number must not be greater than the number of elements in coordinates.

insets

The minimum padding (in screen points) that will be visible around the given coordinate bounds.

animated

Specify YES to animate the change by smoothly scrolling and zooming or NO to immediately display the given bounds.

Discussion

Changes the receiver’s viewport to fit all of the given coordinates and optionally some additional padding on each side.

Declared In

MGLMapView.h

setZoomLevel:animated:

Changes the zoom level of the map and optionally animates the change.

- (void)setZoomLevel:(double)zoomLevel animated:(BOOL)animated

Parameters

zoomLevel

The new zoom level for the map.

animated

Specify YES if you want the map view to animate the change to the new zoom level or NO if you want the map to display the new zoom level immediately.

Changing the zoom level scales the map without changing the current center coordinate. At zoom level 0, tiles cover the entire world map; at zoom level 1, tiles cover ¼ of the world; at zoom level 2, tiles cover 1/16 of the world, and so on.

Discussion

Changes the zoom level of the map and optionally animates the change.

Declared In

MGLMapView.h

showAnnotations:animated:

Sets the visible region so that the map displays the specified annotations.

- (void)showAnnotations:(NSArray<id<MGLAnnotation> > *)annotations animated:(BOOL)animated

Parameters

annotations

The annotations that you want to be visible in the map.

animated

YES if you want the map region change to be animated, or NO if you want the map to display the new region immediately without animations.

Discussion

Sets the visible region so that the map displays the specified annotations.

Calling this method updates the value in the visibleCoordinateBounds property and potentially other properties to reflect the new map region.

Declared In

MGLMapView.h

toggleDebug

Toggle the current value of debugActive.

- (void)toggleDebug

Discussion

Toggle the current value of debugActive.

Declared In

MGLMapView.h