Mapbox Maps SDK for macOS

Put interactive, scalable world maps into your native Cocoa application with the open-source Mapbox Maps SDK for macOS.

  • Mapbox-curated map styles and OpenStreetMap-based vector tiles make it easy to get started.
  • Customize every aspect of the map’s appearance in code or visually using Mapbox Studio.
  • High-performance OpenGL rendering and multitouch gestures keep your users happy.
  • A well-designed, fully documented API helps you stay productive.
  • Develop across multiple platforms, including iOS, using the same styles and similar APIs.

The Mapbox Maps SDK for macOS is compatible with macOS 10.10.0 and above for Cocoa applications developed in Objective-C, Swift, Interface Builder, or AppleScript. For hybrid applications, consider Mapbox GL JS.

Installation

There are three ways to install the Mapbox Maps SDK for macOS:

Manually

  1. Download the latest Mapbox Maps SDK for macOS release from GitHub – look for a release that begins with “macos-”.

  2. Open the project editor, select your application target, then go to the General tab. Drag Mapbox.framework into the “Embedded Binaries” section. (Don’t drag it into the “Linked Frameworks and Libraries” section; Xcode will add it there automatically.) In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.

Via Carthage

The Mapbox Maps SDK for macOS is a binary-only dependency, so you’ll need Carthage 0.19 or above. In your Cartfile, specify this dependency (plus an optional version requirement):

binary "https://mapbox.github.io/mapbox-gl-native/macos/Mapbox-macOS-SDK.json"

After running carthage update, you’ll find Mapbox.framework in the Carthage/Build/ folder. Follow these instructions to integrate it into your project.

Via CocoaPods

Create a Podfile with the following specification:

platform :osx, '10.10'

target 'TargetNameForYourApp' do
  pod 'Mapbox-iOS-SDK', '~> x.y'
end

where x.y is the current version. In Terminal, run pod install.

Usage

Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target, then go to the Info tab. Under the “Custom macOS Application Target Properties” section, set MGLMapboxAccessToken to your access token. You can obtain an access token from the Mapbox account page.

Then, in a storyboard or XIB:

  1. Add a view to your view controller or window. (Drag Custom View from the Object library to the View Controller scene on the Interface Builder canvas. In a XIB, drag it instead to the window on the canvas.)
  2. In the Identity inspector, set the view’s custom class to MGLMapView.
  3. MGLMapView needs to be layer-backed:
    • You can make the window layer-backed by selecting the window and checking Full Size Content View in the Attributes inspector. This allows the map view to underlap the title bar and toolbar.
    • Alternatively, if you don’t want the entire window to be layer-backed, you can make just the map view layer-backed by selecting it and checking its entry under the View Effects inspector’s Core Animation Layer section.
  4. Add a map feedback item to your Help menu. (Drag Menu Item from the Object library into Main Menu ‣ Help ‣ Menu.) Title it “Improve This Map” or similar, and connect it to the giveFeedback: action of First Responder.

If you need to manipulate the map view programmatically:

  1. Switch to the Assistant Editor.
  2. Import the Mapbox module.
  3. Connect the map view to a new outlet in your view controller class. (Control-drag from the map view in Interface Builder to a valid location in your view controller implementation.) The resulting outlet declaration should look something like this:
// ViewController.m
@import Mapbox;

@interface ViewController : NSViewController

@property (strong) IBOutlet MGLMapView *mapView;

@end

// ViewController.swift
import Mapbox

class ViewController: NSViewController {
    @IBOutlet var mapView: MGLMapView!
}

-- AppDelegate.applescript
script AppDelegate
    property parent : class "NSObject"
    property theMapView : missing value
end script

Full API documentation is included in this package, within the documentation folder, and online. The Mapbox Maps SDK for iOS has API documentation and online examples that apply to the Mapbox Maps SDK for macOS with few differences, mostly around unimplemented features like user location tracking.

Mapbox does not officially support the macOS SDK to the same extent as the iOS SDK; however, bug reports and pull requests are certainly welcome.

Changes in version 0.7.0

The 0.7.x series of releases will be the last to support macOS 10.10. The minimum macOS deployment version will increase to macOS 10.11.0 in a future release.

Packaging

  • Added Arabic, Danish, Hebrew, and European Portuguese localizations. (#10967, #11136, #11695)
  • Removed methods, properties, and constants that had been deprecated as of v0.6.1. (#11205)
  • Refined certain Swift interfaces by converting them from class methods to class properties. (#11674)

Style layers

  • The layout and paint properties on subclasses of MGLStyleLayer are now of type NSExpression instead of MGLStyleValue. A new “Predicates and Expressions” guide provides an overview of the supported operators, which include arithmetic and conditional operators. (#10726)
  • A style can now display a heatmap layer that visualizes a point data distribution. You can customize the appearance at runtime using the MGLHeatmapStyleLayer class. (#11046)
  • A style can now display a smooth hillshading layer and customize its appearance at runtime using the MGLHillshadeStyleLayer class. Hillshading is based on a rasterized digital elevation model supplied by the MGLRasterDEMSource class. (#10642)
  • You can now set the MGLVectorStyleLayer.predicate property to a predicate that contains arithmetic and calls to built-in NSExpression functions. You may need to cast a feature attribute key to NSString or NSNumber before comparing it to a string or number. (#11587)
  • Replaced the MGLStyle.localizesLabels property with an -[MGLStyle localizeLabelsIntoLocale:] method that allows you to specify the language to localize into. Note that this method does not automatically update the style when the system’s preferred language changes. Also added an -[NSExpression(MGLAdditions) mgl_expressionLocalizedIntoLocale:] method for localizing an individual value used with MGLSymbolStyleLayer.text. (#11651)
  • Fixed incorrect color calibration on macOS 10.13 High Sierra when using color-related methods of MGLStyleLayer subclasses, as well as when displaying an MGLAttributionInfo. It is no longer necessary to explicitly convert an NSColor to the sRGB color space before using these classes on High Sierra. (#11391)
  • The MGLSymbolStyleLayer.textFontNames property can now depend on a feature’s attributes. (#10850)
  • Changes to the MGLStyleLayer.minimumZoomLevel and MGLStyleLayer.maximumZoomLevel properties take effect immediately. (#11399)

Content sources

Map rendering

  • Improved the reliability of collision detection between symbols near the edges of tiles, as well as between symbols when the map is tilted. It is no longer necessary to enable MGLSymbolStyleLayer.symbolAvoidsEdges to prevent symbols in adjacent tiles from overlapping with each other. (#10436)
  • Symbols can fade in and out as the map pans, rotates, or tilts. (#10436)
  • Properties such as MGLSymbolStyleLayer.iconAllowsOverlap and MGLSymbolStyleLayer.iconIgnoresPlacement now account for symbols in other sources. (#10436)
  • Added the MGLTileSourceOptionTileCoordinateBounds option to create an MGLTileSource that only supplies tiles within a specific geographic bounding box. (#11141)
  • Fixed an issue preventing a dynamically-added MGLRasterStyleLayer from drawing until the map pans. (#10270)
  • Fixed an issue preventing MGLImageSources from drawing on the map when the map is zoomed in and tilted. (#10677)
  • Improved the sharpness of raster tiles on Retina displays. (#10984)
  • Fixed a crash parsing a malformed style. (#11001)
  • Fixed an issue where symbols with empty labels would always be hidden. (#11206)
  • Fixed an issue where a tilted map could flicker while displaying rotating symbols. (#11488)
  • Increased the maximum width of labels by a factor of two. (#11508)

Annotations

  • Fixed an issue where tapping a group of annotations may not have selected the nearest annotation. (#11438)
  • The MGLMapView.selectedAnnotations property (backed by -[MGLMapView setSelectedAnnotations:]) now selects annotations that are off-screen. (#9790)
  • The animated parameter to -[MGLMapView selectAnnotation:animated:] now controls whether the annotation and its callout are brought on-screen. If animated is NO then the annotation is selected if offscreen, but the map is not panned. Currently only point annotations are supported.(#3249)
  • Fixed a crash when rapidly adding and removing annotations. (#11551, #11575)

Map snapshots

  • Fixed a memory leak that occurred when creating a map snapshot. (#10585)
  • Fixed an issue that caused MGLMapSnapshotter.pointForCoordinate to return an incorrect value. (#11035)

Other changes