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

Packaging

  • Renamed this SDK from Mapbox macOS SDK to Mapbox Maps SDK for macOS. (#10610, #10793)
  • Added a Bulgarian localization. (#10309)

Networking and storage

  • Added a new MGLMapSnapshotter class for capturing rendered map images from an MGLMapView’s camera. (#9891)
  • Reduced the time it takes to create new MGLMapView instances in some cases. (#9864)
  • Added support for forced cache revalidation that will eliminate flickering that was sometimes visible for certain types of tiles (e.g., traffic tiles). (#9670, #9103)
  • Improved the performance of the SDK when parsing vector tile data used to render the map. (#9312)

Styles

  • Added a new type of source, represented by the MGLImageSource class at runtime, that displays a georeferenced image. (#9110)
  • Setting a style using MGLMapView‘s styleURL property now smoothly transitions from the previous style to the new style and maintains equivalent layers and sources along with their identifiers. (#9256)
  • Added MGLCircleStyleLayer.circlePitchAlignment and MGLSymbolStyleLayer.iconPitchAlignment properties to control whether circles and symbols lie flat against a tilted map. (#9426, #9479)
  • Added an MGLSymbolStyleLayer.iconAnchor property to control where an icon is anchored. (#9849)
  • The maximumTextWidth and textLetterSpacing properties of MGLSymbolStyleLayer are now compatible with MGLSourceStyleFunctions and MGLCompositeStyleFunctions, allowing data-driven styling of these properties. (#9870)
  • Improved the legibility of labels that follow lines when the map is tilted. (#9009)
  • Fixed an issue that could cause flickering when a translucent raster style layer was present. (#9468)
  • Fixed an issue that could cause antialiasing between polygons on the same layer to fail if the fill layers used data-driven styling for the fill color. (#9699)
  • The previously deprecated support for style classes has been removed. For interface compatibility, the API methods remain, but they are now non-functional.

Annotations and user interaction

Other changes

  • Fixed distortion in the logo view on macOS 10.13 High Sierra. (#10606)
  • Fixed an issue that could cause line label rendering glitches when the line geometry is projected to a point behind the plane of the camera. (#9865)
  • Fixed an issue that could cause a crash when using -[MGLMapView flyToCamera:completionHandler:] and related methods with zoom levels at or near the maximum value. (#9381)
  • Fixed an issue where removing a MGLOpenGLStyleLayer from a map might result in a crash. (#10765)
  • Added documentation for usage of coordinate bounds that cross the anti-meridian. (#10783)
  • Removed duplicated variables in MGLMapSnapshotter. (#10702)