MGLMapView

@interface MGLMapView : UIView

An interactive, customizable map view with an interface similar to the one provided by Apple’s MapKit.

Using MGLMapView, you can embed the map inside a view, allow users to manipulate it with standard gestures, animate the map between different viewpoints, and present information in the form of annotations and overlays.

The map view loads scalable vector tiles that conform to the Mapbox Vector Tile Specification. It styles them with a style that conforms to the Mapbox GL style specification. Such styles can be designed in Mapbox Studio and hosted on mapbox.com.

A collection of Mapbox-hosted styles is available through the MGLStyle class. These basic styles use Mapbox Streets or Mapbox Satellite data sources, but you can specify a custom style that makes use of your own data.

Mapbox-hosted vector tiles and styles require an API access token, which you can obtain from the Mapbox account page. Access tokens associate requests to Mapbox’s vector tile and style APIs with your Mapbox account. They also deter other developers from using your styles without your permission.

Note

You are responsible for getting permission to use the map data and for ensuring that your use adheres to the relevant terms of use.

Creating Instances

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

    Declaration

    Objective-C

    - (nonnull instancetype)initWithFrame:(CGRect)frame;

    Parameters

    frame

    The frame for the view, measured in points.

    Return Value

    An initialized map view.

    Show on GitHub

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

    Declaration

    Objective-C

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

    Parameters

    frame

    The frame for the view, measured in points.
    styleURL

    URL of the map style to display. The URL may be a full HTTP or HTTPS URL, a Mapbox URL indicating the style’s map ID (mapbox://styles/{user}/{style}), or a path to a local file relative to the application’s resource path. Specify nil for the default style.

    Return Value

    An initialized map view.

    Show on GitHub

Accessing the Delegate

  • The receiver’s delegate.

    A map view sends messages to its delegate to notify it of changes to its contents or the viewpoint. The delegate also provides information about annotations displayed on the map, such as the styles to apply to individual annotations.

    Declaration

    Objective-C

    @property (readwrite, nonatomic, nullable) id<MGLMapViewDelegate> delegate;
    Show on GitHub

Configuring the Map's Appearance

  • URLs of the styles bundled with the library.

    @deprecated Call the relevant class method of MGLStyle for the URL of a particular default style.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSArray<NSURL *> *_Nonnull bundledStyleURLs;
    Show on GitHub

  • URL of the style currently displayed in the receiver.

    The URL may be a full HTTP or HTTPS URL, a Mapbox URL indicating the style’s map ID (mapbox://styles/{user}/{style}), or a path to a local file relative to the application’s resource path.

    If you set this property to nil, the receiver will use the default style and this property will automatically be set to that style’s URL.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, null_resettable) NSURL *styleURL;
    Show on GitHub

  • A control indicating the map’s direction and allowing the user to manipulate the direction, positioned in the upper-right corner.

    Declaration

    Objective-C

    @property (readonly, nonatomic) UIImageView *_Nonnull compassView;
    Show on GitHub

  • The Mapbox logo, positioned in the lower-left corner.

    Note

    The Mapbox terms of service, which governs the use of Mapbox-hosted vector tiles and styles, requires most Mapbox customers to display the Mapbox logo. If this applies to you, do not hide this view or change its contents.

    Declaration

    Objective-C

    @property (readonly, nonatomic) UIImageView *_Nonnull logoView;
    Show on GitHub

  • A view showing legally required copyright notices and telemetry settings, positioned at the bottom-right of the map view.

    Note

    The Mapbox terms of service, which governs the use of Mapbox-hosted vector tiles and styles, requires these copyright notices to accompany any map that features Mapbox-designed styles, OpenStreetMap data, or other Mapbox data such as satellite or terrain data. If that applies to this map view, do not hide this view or remove any notices from it.

    Note

    You are additionally required to provide users with the option to disable anonymous usage and location sharing (telemetry). If this view is hidden, you must implement this setting elsewhere in your app or via Settings.bundle. See our website for implementation help.

    Declaration

    Objective-C

    @property (readonly, nonatomic) UIButton *_Nonnull attributionButton;
    Show on GitHub

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

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic)
    NSArray<NSString *> *_Nonnull styleClasses;
    Show on GitHub

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

    Declaration

    Objective-C

    - (BOOL)hasStyleClass:(nonnull NSString *)styleClass;

    Parameters

    styleClass

    The style class to query for.

    Return Value

    Whether the style class is currently active.

    Show on GitHub

  • Activates the style class with the given identifier.

    Declaration

    Objective-C

    - (void)addStyleClass:(nonnull NSString *)styleClass;

    Parameters

    styleClass

    The style class to activate.
    Show on GitHub

  • Deactivates the style class with the given identifier.

    Declaration

    Objective-C

    - (void)removeStyleClass:(nonnull NSString *)styleClass;

    Parameters

    styleClass

    The style class to deactivate.
    Show on GitHub

Displaying the User's Location

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

    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.

    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.

    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.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL showsUserLocation;
    Show on GitHub

  • A Boolean value indicating whether the device’s current location is visible in the map view.

    Use showsUserLocation to control the visibility of the on-screen user location annotation.

    Declaration

    Objective-C

    @property (readonly, getter=isUserLocationVisible, assign, nonatomic)
    BOOL userLocationVisible;
    Show on GitHub

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

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) MGLUserLocation *userLocation;
    Show on GitHub

  • The mode used to track the user location. The default value is MGLUserTrackingModeNone.

    Changing the value of this property updates the map view with an animated transition. If you don’t want to animate the change, use the -setUserTrackingMode:animated: method instead.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) MGLUserTrackingMode userTrackingMode;
    Show on GitHub

  • Sets the mode used to track the user location, with an optional transition.

    Declaration

    Objective-C

    - (void)setUserTrackingMode:(MGLUserTrackingMode)mode animated:(BOOL)animated;

    Parameters

    mode

    The mode used to track the user location.
    animated

    If YES, there is an animated transition from the current viewport to a viewport that results from the change to mode. If NO, the map view instantaneously changes to the new viewport. This parameter only affects the initial transition; subsequent changes to the user location or heading are always animated.
    Show on GitHub

  • The vertical alignment of the user location annotation within the receiver. The default value is MGLAnnotationVerticalAlignmentCenter.

    Changing the value of this property updates the map view with an animated transition. If you don’t want to animate the change, use the -setUserLocationVerticalAlignment:animated: method instead.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic)
    MGLAnnotationVerticalAlignment userLocationVerticalAlignment;
    Show on GitHub

  • Sets the vertical alignment of the user location annotation within the receiver, with an optional transition.

    Declaration

    Objective-C

    - (void)setUserLocationVerticalAlignment:
            (MGLAnnotationVerticalAlignment)alignment
                                animated:(BOOL)animated;

    Parameters

    alignment

    The vertical alignment of the user location annotation.
    animated

    If YES, the user location annotation animates to its new position within the map view. If NO, the user location annotation instantaneously moves to its new position.
    Show on GitHub

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

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL displayHeadingCalibration;
    Show on GitHub

  • The geographic coordinate that is the subject of observation as the user location is being tracked.

    By default, this property is set to an invalid coordinate, indicating that there is no target. In course tracking mode, the target forms one of two foci in the viewport, the other being the user location annotation. Typically, this property is set to a destination or waypoint in a real-time navigation scene. As the user annotation moves toward the target, the map automatically zooms in to fit both foci optimally within the viewport.

    This property has no effect if the userTrackingMode property is set to a value other than MGLUserTrackingModeFollowWithCourse.

    Changing the value of this property updates the map view with an animated transition. If you don’t want to animate the change, use the -setTargetCoordinate:animated: method instead.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CLLocationCoordinate2D targetCoordinate;
    Show on GitHub

  • Sets the geographic coordinate that is the subject of observation as the user location is being tracked, with an optional transition animation.

    By default, the target coordinate is set to an invalid coordinate, indicating that there is no target. In course tracking mode, the target forms one of two foci in the viewport, the other being the user location annotation. Typically, the target is set to a destination or waypoint in a real-time navigation scene. As the user annotation moves toward the target, the map automatically zooms in to fit both foci optimally within the viewport.

    This method has no effect if the userTrackingMode property is set to a value other than MGLUserTrackingModeFollowWithCourse.

    Declaration

    Objective-C

    - (void)setTargetCoordinate:(CLLocationCoordinate2D)targetCoordinate
                   animated:(BOOL)animated;

    Parameters

    targetCoordinate

    The target coordinate to fit within the viewport.
    animated

    If YES, the map animates to fit the target within the map view. If NO, the map fits the target instantaneously.
    Show on GitHub

Configuring How the User Interacts with the Map

  • A Boolean value that determines whether the user may zoom the map in and out, changing the zoom level.

    When this property is set to YES, the default, the user may zoom the map in and out by pinching two fingers or by double tapping, holding, and moving the finger up and down.

    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.

    Declaration

    Objective-C

    @property (getter=isZoomEnabled, assign, readwrite, nonatomic) BOOL zoomEnabled;
    Show on GitHub

  • A Boolean value that determines whether the user may scroll around the map, changing the center coordinate.

    When this property is set to YES, the default, the user may scroll the map by dragging or swiping with one finger.

    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.

    Declaration

    Objective-C

    @property (getter=isScrollEnabled, assign, readwrite, nonatomic)
    BOOL scrollEnabled;
    Show on GitHub

  • A Boolean value that determines whether the user may rotate the map, changing the direction.

    When this property is set to YES, the default, the user may rotate the map by moving two fingers in a circular motion.

    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.

    Declaration

    Objective-C

    @property (getter=isRotateEnabled, assign, readwrite, nonatomic)
    BOOL rotateEnabled;
    Show on GitHub

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

    When this property is set to YES, the default, the user may tilt the map by vertically dragging two fingers.

    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.

    Declaration

    Objective-C

    @property (getter=isPitchEnabled, assign, readwrite, nonatomic)
    BOOL pitchEnabled;
    Show on GitHub

Manipulating the Viewpoint

  • The geographic coordinate at the center of the map view.

    Changing the value of 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.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CLLocationCoordinate2D centerCoordinate;
    Show on GitHub

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

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

    Declaration

    Objective-C

    - (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.
    Show on GitHub

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

    Declaration

    Objective-C

    - (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.
    Show on GitHub

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

    Declaration

    Objective-C

    - (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.
    Show on GitHub

  • Changes the center coordinate, zoom level, and direction of the map, calling a completion handler at the end of an optional animation.

    Declaration

    Objective-C

    - (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
                  zoomLevel:(double)zoomLevel
                  direction:(CLLocationDirection)direction
                   animated:(BOOL)animated
          completionHandler:(nullable void (^)(void))completion;

    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.
    completion

    The block executed after the animation finishes.
    Show on GitHub

  • The zoom level of the receiver.

    In addition to affecting the visual size and detail of features on the map, the zoom level affects the size of the vector tiles that are loaded. At zoom level 0, each tile covers the entire world map; at zoom level 1, it covers ¼ of the world; at zoom level 2, 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.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) double zoomLevel;
    Show on GitHub

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

    Changing the zoom level scales the map without changing the current center coordinate.

    Declaration

    Objective-C

    - (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.
    Show on GitHub

  • The minimum zoom level at which the map can be shown.

    Depending on the map view’s aspect ratio, the map view may be prevented from reaching the minimum zoom level, in order to keep the map from repeating within the current viewport.

    If the value of this property is greater than that of the maximumZoomLevel property, the behavior is undefined.

    The default minimumZoomLevel is 0.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) double minimumZoomLevel;
    Show on GitHub

  • The maximum zoom level the map can be shown at.

    If the value of this property is smaller than that of the minimumZoomLevel property, the behavior is undefined.

    The default maximumZoomLevel is 20.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) double maximumZoomLevel;
    Show on GitHub

  • The heading of the map, measured in degrees clockwise from 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.

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

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CLLocationDirection direction;
    Show on GitHub

  • Changes the heading of the map and optionally animates the change.

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

    Declaration

    Objective-C

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

    Parameters

    direction

    The heading of the map, measured in degrees clockwise from 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.
    Show on GitHub

  • Resets the map rotation to a northern heading — a direction of 0 degrees.

    Declaration

    Objective-C

    - (void)resetNorth;
    Show on GitHub

  • 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.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic)
    MGLCoordinateBounds visibleCoordinateBounds;
    Show on GitHub

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

    Declaration

    Objective-C

    - (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.
    Show on GitHub

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

    Declaration

    Objective-C

    - (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.
    Show on GitHub

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

    Declaration

    Objective-C

    - (void)setVisibleCoordinates:(nonnull 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.
    Show on GitHub

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

    Declaration

    Objective-C

    - (void)setVisibleCoordinates:(nonnull CLLocationCoordinate2D *)coordinates
                        count:(NSUInteger)count
                  edgePadding:(UIEdgeInsets)insets
                    direction:(CLLocationDirection)direction
                     duration:(NSTimeInterval)duration
      animationTimingFunction:(nullable CAMediaTimingFunction *)function
            completionHandler:(nullable void (^)(void))completion;

    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.
    direction

    The direction to rotate the map to, measured in degrees relative to true north.
    duration

    The duration to animate the change in seconds.
    function

    The timing function to animate the change.
    completion

    The block executed after the animation finishes.
    Show on GitHub

  • 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. A small amount of padding is reserved around the edges of the map view. To specify a different amount of padding, use the -showAnnotations:edgePadding:animated: method.

    Declaration

    Objective-C

    - (void)showAnnotations:(nonnull 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.
    Show on GitHub

  • Sets the visible region so that the map displays the specified annotations with the specified amount of padding on each side.

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

    Declaration

    Objective-C

    - (void)showAnnotations:(nonnull NSArray<id<MGLAnnotation>> *)annotations
            edgePadding:(UIEdgeInsets)insets
               animated:(BOOL)animated;

    Parameters

    annotations

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

    The minimum padding (in screen points) around the edges of the map view to keep clear of annotations.
    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.
    Show on GitHub

  • A camera representing the current viewpoint of the map.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic) MGLMapCamera *_Nonnull camera;
    Show on GitHub

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

    Declaration

    Objective-C

    - (void)setCamera:(nonnull 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.
    Show on GitHub

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

    Declaration

    Objective-C

    - (void)setCamera:(nonnull 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.
    Show on GitHub

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

    Declaration

    Objective-C

    - (void)setCamera:(nonnull MGLMapCamera *)camera
               withDuration:(NSTimeInterval)duration
    animationTimingFunction:(nullable CAMediaTimingFunction *)function
          completionHandler:(nullable void (^)(void))completion;

    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.
    completion

    The block to execute after the animation finishes.
    Show on GitHub

  • Moves the viewpoint to a different location using a transition animation that evokes powered flight and a default duration based on the length of the flight path.

    The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.

    Declaration

    Objective-C

    - (void)flyToCamera:(nonnull MGLMapCamera *)camera
    completionHandler:(nullable void (^)(void))completion;

    Parameters

    camera

    The new viewpoint.
    completion

    The block to execute after the animation finishes.
    Show on GitHub

  • Moves the viewpoint to a different location using a transition animation that evokes powered flight and an optional transition duration.

    The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.

    Declaration

    Objective-C

    - (void)flyToCamera:(nonnull MGLMapCamera *)camera
         withDuration:(NSTimeInterval)duration
    completionHandler:(nullable void (^)(void))completion;

    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. Specify a negative value to use the default duration, which is based on the length of the flight path.
    completion

    The block to execute after the animation finishes.
    Show on GitHub

  • Moves the viewpoint to a different location using a transition animation that evokes powered flight and an optional transition duration and peak altitude.

    The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.

    Declaration

    Objective-C

    - (void)flyToCamera:(nonnull MGLMapCamera *)camera
         withDuration:(NSTimeInterval)duration
         peakAltitude:(CLLocationDistance)peakAltitude
    completionHandler:(nullable void (^)(void))completion;

    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. Specify a negative value to use the default duration, which is based on the length of the flight path.
    peakAltitude

    The altitude, measured in meters, at the midpoint of the animation. The value of this parameter is ignored if it is negative or if the animation transition resulting from a similar call to -setCamera:animated: would have a midpoint at a higher altitude.
    completion

    The block to execute after the animation finishes.
    Show on GitHub

  • The distance from the edges of the map view’s frame to the edges of the map view’s logical viewport.

    When the value of this property is equal to UIEdgeInsetsZero, viewport properties such as centerCoordinate assume a viewport that matches the map view’s frame. Otherwise, those properties are inset, excluding part of the frame from the viewport. For instance, if the only the top edge is inset, the map center is effectively shifted downward.

    When the map view’s superview is an instance of UIViewController whose automaticallyAdjustsScrollViewInsets property is YES, the value of this property may be overridden at any time.

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

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) UIEdgeInsets contentInset;
    Show on GitHub

  • Sets the distance from the edges of the map view’s frame to the edges of the map view’s logical viewport with an optional transition animation.

    When the value of this property is equal to UIEdgeInsetsZero, viewport properties such as centerCoordinate assume a viewport that matches the map view’s frame. Otherwise, those properties are inset, excluding part of the frame from the viewport. For instance, if the only the top edge is inset, the map center is effectively shifted downward.

    When the map view’s superview is an instance of UIViewController whose automaticallyAdjustsScrollViewInsets property is YES, the value of this property may be overridden at any time.

    Declaration

    Objective-C

    - (void)setContentInset:(UIEdgeInsets)contentInset animated:(BOOL)animated;

    Parameters

    contentInset

    The new values to inset the content by.
    animated

    Specify YES if you want the map view to animate the change to the content inset or NO if you want the map to inset the content immediately.
    Show on GitHub

Converting Geographic Coordinates

  • Converts a point in the given view’s coordinate system to a geographic coordinate.

    Declaration

    Objective-C

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

    Parameters

    point

    The point to convert.
    view

    The view in whose coordinate system the point is expressed.

    Return Value

    The geographic coordinate at the given point.

    Show on GitHub

  • Converts a geographic coordinate to a point in the given view’s coordinate system.

    Declaration

    Objective-C

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

    Parameters

    coordinate

    The geographic coordinate to convert.
    view

    The view in whose coordinate system the returned point should be expressed. If this parameter is nil, the returned point is expressed 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 given geographic coordinate.

    Show on GitHub

  • Converts a rectangle in the given view’s coordinate system to a geographic bounding box.

    Declaration

    Objective-C

    - (MGLCoordinateBounds)convertRect:(CGRect)rect
        toCoordinateBoundsFromView:(nullable UIView *)view;

    Parameters

    rect

    The rectangle to convert.
    view

    The view in whose coordinate system the rectangle is expressed.

    Return Value

    The geographic bounding box coextensive with the given rectangle.

    Show on GitHub

  • Converts a geographic bounding box to a rectangle in the given view’s coordinate system.

    Declaration

    Objective-C

    - (CGRect)convertCoordinateBounds:(MGLCoordinateBounds)bounds
                     toRectToView:(nullable UIView *)view;

    Parameters

    bounds

    The geographic bounding box to convert.
    view

    The view in whose coordinate system the returned rectangle should be expressed. If this parameter is nil, the returned rectangle is expressed in the window’s coordinate system. If view is not nil, it must belong to the same window as the map view.
    Show on GitHub

  • Returns the distance spanned by one point in the map view’s coordinate system at the given latitude and current zoom level.

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

    Declaration

    Objective-C

    - (CLLocationDistance)metersPerPointAtLatitude:(CLLocationDegrees)latitude;

    Parameters

    latitude

    The latitude of the geographic coordinate represented by the point.

    Return Value

    The distance in meters spanned by a single point.

    Show on GitHub

Annotating the Map

  • 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.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable)
    NSArray<id<MGLAnnotation>> *annotations;
    Show on GitHub

  • Adds an annotation to the map view.

    Declaration

    Objective-C

    - (void)addAnnotation:(nonnull 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 annotation object.

    Show on GitHub

  • Adds an array of annotations to the map view.

    Declaration

    Objective-C

    - (void)addAnnotations:(nonnull 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 each individual annotation object.
    Show on GitHub

  • Removes an annotation from the map view, deselecting it if it is selected.

    Removing an annotation object dissociates 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.

    Declaration

    Objective-C

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

    Parameters

    annotation

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

  • Removes an array of annotations from the map view, deselecting any selected annotations in the array.

    Removing annotation objects dissociates 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 given annotations.

    Declaration

    Objective-C

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

    Parameters

    annotations

    The array of annotation objects to remove. Objects in the array must conform to the MGLAnnotation protocol.
    Show on GitHub

  • Returns a reusable annotation image object associated with its identifier.

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

    Declaration

    Objective-C

    - (nullable MGLAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:
        (nonnull 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 given identifier, or nil if no such object exists in the reuse queue.

    Show on GitHub

Managing Annotation Selections

  • The currently selected annotations.

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

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
    NSArray<id<MGLAnnotation>> *_Nonnull selectedAnnotations;
    Show on GitHub

  • Selects an annotation and displays a callout view for it.

    If the given annotation is not visible within the current viewport, this method has no effect.

    Declaration

    Objective-C

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

    Parameters

    annotation

    The annotation object to select.
    animated

    If YES, the callout view is animated into position.
    Show on GitHub

  • Deselects an annotation and hides its callout view.

    Declaration

    Objective-C

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

    Parameters

    annotation

    The annotation object to deselect.
    animated

    If YES, the callout view is animated offscreen.
    Show on GitHub

Overlaying the Map

  • Adds a single overlay object to the map.

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

    Declaration

    Objective-C

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

    Parameters

    overlay

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

    Show on GitHub

  • Adds an array of overlay objects to the map.

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

    Declaration

    Objective-C

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

    Parameters

    overlays

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

  • Removes a single overlay object from the map.

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

    Declaration

    Objective-C

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

    Parameters

    overlay

    The overlay object to remove.
    Show on GitHub

  • Removes one or more overlay objects from the map.

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

    Declaration

    Objective-C

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

    Parameters

    overlays

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

Debugging the Map

  • The options that determine which debugging aids are shown on the map.

    These options are all disabled by default and should remain disabled in released software for performance and aesthetic reasons.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) MGLMapDebugMaskOptions debugMask;
    Show on GitHub

  • Empties the in-memory tile cache.

    Declaration

    Objective-C

    - (void)emptyMemoryCache;
    Show on GitHub

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

    Declaration

    Objective-C

    - (void)resetPosition;
    Show on GitHub