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.

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.

Adding your own gesture recognizer to MGLMapView will block the corresponding
gesture recognizer built into MGLMapView. To avoid conflicts, define which
gesture takes precedence. For example, you can create your own
UITapGestureRecognizer that will be invoked only if the default MGLMapView
tap gesture fails:

Declaration

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

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.

The default styles provided by Mapbox contain sources and layers with
identifiers that will change over time. Applications that use APIs that
manipulate a style’s sources and layers must first set the style URL to an
explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL”
inspectable in Interface Builder, or a manually constructed NSURL.

Declaration

You do not normally need to call this method. The map view automatically
responds to changes in network connectivity by reloading the style. You may
need to call this method if you change the access token after a style has
loaded but before loading a style associated with a different Mapbox account.

This method does not bust the cache. Even if the style has recently changed on
the server, calling this method does not necessarily ensure that the map view
reflects those changes.

Declaration

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

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

If you choose to reimplement this view, assign the -showAttribution: method
as the action for your view to present the default notices and settings.

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

This action is performed when the user taps on the attribution button provided
by default via the attributionButton property. If you implement a custom
attribution button, you should add this action to the button.

Declaration

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.

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

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.

Setting this property to YES causes the default user location annotation to
appear and always show an arrow-shaped heading indicator, if heading is
available. This property does not rotate the map; for that, see
MGLUserTrackingModeFollowWithHeading.

This property has no effect when userTrackingMode is
MGLUserTrackingModeFollowWithHeading or
MGLUserTrackingModeFollowWithCourse.

Declaration

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

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.

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

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.

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.

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.

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.

Declaration

Parameters

bounds

The coordinate bounds to fit to the receiver’s viewport.

Return Value

A camera object centered on the same location as the coordinate
bounds with zoom level as high (close to the ground) as possible while still
including the entire coordinate bounds. The camera object uses the current
direction and pitch.

Parameters

The minimum padding (in screen points) that would be visible
around the returned camera object if it were set as the receiver’s camera.

Return Value

A camera object centered on the same location as the coordinate bounds
with zoom level as high (close to the ground) as possible while still
including the entire coordinate bounds. The camera object uses the current
direction and pitch.

Parameters

Return Value

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

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

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.

Declaration

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.

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.

Parameters

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.

Parameters

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.

Return Value

Returns a reusable annotation view object associated with its identifier.

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

Return Value

The complete list of annotations associated with the receiver that are
currently visible.

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

Parameters

Returns an array of rendered map features that intersect with a given point.

This method may return features from any of the map’s style layers. To restrict
the search to a particular layer or layers, use the
-visibleFeaturesAtPoint:inStyleLayersWithIdentifiers: method. For more
information about searching for map features, see that method’s documentation.

Returns an array of rendered map features that intersect with a given point,
restricted to the given style layers and filtered by the given predicate.

Each object in the returned array represents a feature rendered by the
current style and provides access to attributes specified by the relevant map
content sources. The returned array includes features loaded by
MGLShapeSource and MGLVectorSource objects but does not include anything
from MGLRasterSource objects, or from image, video, or canvas sources, which
are unsupported by this SDK.

The returned features are drawn by a style layer in the current style. For
example, suppose the current style uses the
Mapbox Streets source,
but none of the specified style layers includes features that have the maki
property set to bus. If you pass a point corresponding to the location of a
bus stop into this method, the bus stop feature does not appear in the
resulting array. On the other hand, if the style does include bus stops, an
MGLFeature object representing that bus stop is returned and its
featureAttributes dictionary has the maki key set to bus (along with
other attributes). The dictionary contains only the attributes provided by the
tile source; it does not include computed attribute values or rules about how
the feature is rendered by the current style.

The returned array is sorted by z-order, starting with the topmost rendered
feature and ending with the bottommost rendered feature. A feature that is
rendered multiple times due to wrapping across the antimeridian at low zoom
levels is included only once, subject to the caveat that follows.

Features come from tiled vector data or GeoJSON data that is converted to tiles
internally, so feature geometries are clipped at tile boundaries and features
may appear duplicated across tiles. For example, suppose the specified point
lies along a road that spans the screen. The resulting array includes those
parts of the road that lie within the map tile that contain the specified
point, even if the road extends into other tiles.

To find out the layer names in a particular style, view the style in
Mapbox Studio.

Layer identifiers are not guaranteed to exist across styles or different
versions of the same style. Applications that use this API must first set
the style URL to an explicitly versioned style using a convenience method
like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL”
inspectable in Interface Builder, or a manually constructed NSURL. This
approach also avoids layer identifer name changes that will occur in the
default style’s layers over time.

Return Value

Returns an array of rendered map features that intersect with the given
rectangle.

This method may return features from any of the map’s style layers. To restrict
the search to a particular layer or layers, use the
-visibleFeaturesAtPoint:inStyleLayersWithIdentifiers: method. For more
information about searching for map features, see that method’s documentation.

Returns an array of rendered map features that intersect with the given
rectangle, restricted to the given style layers and filtered by the given
predicate.

Each object in the returned array represents a feature rendered by the
current style and provides access to attributes specified by the relevant map
content sources. The returned array includes features loaded by
MGLShapeSource and MGLVectorSource objects but does not include anything
from MGLRasterSource objects, or from image, video, or canvas sources, which
are unsupported by this SDK.

The returned features are drawn by a style layer in the current style. For
example, suppose the current style uses the
Mapbox Streets source,
but none of the specified style layers includes features that have the maki
property set to bus. If you pass a rectangle containing the location of a bus
stop into this method, the bus stop feature does not appear in the resulting
array. On the other hand, if the style does include bus stops, an MGLFeature
object representing that bus stop is returned and its featureAttributes
dictionary has the maki key set to bus (along with other attributes). The
dictionary contains only the attributes provided by the tile source; it does
not include computed attribute values or rules about how the feature is
rendered by the current style.

The returned array is sorted by z-order, starting with the topmost rendered
feature and ending with the bottommost rendered feature. A feature that is
rendered multiple times due to wrapping across the antimeridian at low zoom
levels is included only once, subject to the caveat that follows.

Features come from tiled vector data or GeoJSON data that is converted to tiles
internally, so feature geometries are clipped at tile boundaries and features
may appear duplicated across tiles. For example, suppose the specified
rectangle intersects with a road that spans the screen. The resulting array
includes those parts of the road that lie within the map tiles covering the
specified rectangle, even if the road extends into other tiles. The portion of
the road within each map tile is included individually.

To find out the layer names in a particular style, view the style in
Mapbox Studio.

Layer identifiers are not guaranteed to exist across styles or different
versions of the same style. Applications that use this API must first set the
style URL to an explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL”
inspectable in Interface Builder, or a manually constructed NSURL. This
approach also avoids layer identifer name changes that will occur in the default
style’s layers over time.

Note

Layer identifiers are not guaranteed to exist across styles or different
versions of the same style. Applications that use this API must first set
the style URL to an explicitly versioned style using a convenience method
like +[MGLStyle outdoorsStyleURLWithVersion:], MGLMapView’s “Style URL”
inspectable in Interface Builder, or a manually constructed NSURL. This
approach also avoids layer identifer name changes that will occur in the
default style’s layers over time.