Mapbox macOS SDK

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

  • 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 macOS SDK 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 macOS SDK:

Manually

  1. Download the latest Mapbox macOS SDK 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 macOS SDK 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 iOS SDK’s API documentation and online examples apply to the Mapbox macOS SDK 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.4.0

This version of the Mapbox macOS SDK corresponds to version 3.5.1 of the Mapbox iOS SDK.

Internationalization

  • Added support for right-to-left text and Arabic ligatures in labels. (#6984, #7123)
  • Improved the line wrapping behavior of point-placed labels, especially labels written in Chinese and Japanese. (#6828, #7446)
  • CJK characters now remain upright in vertically oriented labels that have line placement, such as road labels. (#7114)
  • Added Catalan, Chinese (Simplified and Traditional), Dutch, Finnish, French, German, Japanese, Lithuanian, Polish, Portuguese (Brazilian), Spanish, Swedish, Ukrainian, and Vietnamese localizations. (#7316, #7503, #7899, #7999, #8113, #8256)

Styles

  • Added support for data-driven styling in the form of source and composite style functions. MGLStyleFunction is now an abstract class, with MGLCameraStyleFunction providing the behavior of MGLStyleFunction in previous releases. New MGLStyleFunction subclasses allow you to vary a style attribute by the values of attributes of features in the source. (#7596)
  • Added methods to MGLShapeSource and MGLVectorSource for querying features loaded by the source, whether or not they’re visible on the map. (#8263)
  • Added circleStrokeColor, circleStrokeWidth, and circleStrokeOpacity properties to MGLCircleStyleLayer and support for corresponding properties in style JSON files. (#7356)
  • Point-placed labels in symbol style layers are now placed at more optimal locations within polygons. (#7465)
  • Fixed flickering that occurred when manipulating a style layer. (#7616)
  • Symbol style layers can now render point collections (known as multipoints in GeoJSON). (#7445)
  • Added a transition property to MGLStyle to customize the timing of changes to style layers. (#7711)
  • Added properties to MGLStyleLayer subclasses to customize the timing of transitions between values of individual attributes. (#8225)
  • Fixed an issue causing lines and text labels toward the top of the map view to appear blurry when the map is tilted. (#7444)
  • Fixed incorrect interpolation of style functions in Boolean-typed style attributes. (#7526)
  • Removed support for the ref property in layers in style JSON files. (#7586)
  • Fixed an issue that collapsed consecutive newlines within text labels. (#7446)
  • Fixed artifacts when drawing particularly acute line joins. (#7786)
  • Fixed an issue in which a vector style layer predicate involving the $id key path would exclude all features from the layer. (#7989, #7971)
  • Fixed an issue causing vector style layer predicates to be evaluated as if each feature had a $type attribute of 1, 2, or 3. The $type key path can now be compared to Point, LineString, or Polygon, as described in the documentation. (#7971)
  • When setting an MGLShapeSource’s shape to an MGLFeature instance, any NSColor attribute value is now converted to the equivalent CSS string representation for use with MGLInterpolationModeIdentity in style functions. (#8025)
  • An exception is no longer thrown if layers or sources are removed from a style before they are added. (#7962)
  • Renamed MGLStyleConstantValue to MGLConstantStyleValue. For compatibility with previous releases, MGLStyleConstantValue is now an alias of MGLConstantStyleValue. (#8090)
  • Fixed a crash that could occur when switching styles after adding an MGLSource to the style. (#8298)

Annotations and user interaction

  • Added a method to MGLMapViewDelegate, -mapView:shouldChangeFromCamera:toCamera:, that you can implement to restrict which parts the user can navigate to using gestures. (#5584)
  • When a map view is the first responder, pressing +, -, or = now zooms the map. (#8033)
  • Changing the coordinates of a point annotation no longer deselects the annotation. (#8269)
  • Fixed an issue that could cause a crash when point annotations were added and removed while simultaneously querying source features. (#8374)
  • Fixed an issue preventing MGLMapView from adding a polyline annotation with the same coordinates as a polygon annotation. (#8355)
  • Zooming by double-tap, two-finger tap, zoom buttons, shortcut keys, or demo app menu items or shortcut keys now zooms to the nearest integer zoom level. (#8027)
  • Fixed an issue where translucent point annotations along tile boundaries would be drawn darker than expected. (#6832)

Networking and offline maps

  • Offline pack notifications are now posted by MGLOfflinePack instances instead of the shared MGLOfflineStorage object. For backwards compatibility, the userInfo dictionary still indicates the pack’s state and progress. (#7952)
  • Fixed a memory leak in MGLMapView. (#7956)
  • Fixed an issue that could prevent a cached style from appearing while the computer is offline. (#7770)
  • Fixed an issue that could prevent a style from loading when reestablishing a network connection. (#7902)
  • MGLOfflineStorage instances now support a delegate conforming to MGLOfflineStorageDelegate, which allows altering URLs before they are requested from the Internet. (#8084)

Other changes

  • Added support for the Carthage dependency manager. See this SDK’s homepage for setup instructions. (#8257)
  • Fixed an issue that, among other things, caused various islands to disappear at certain zoom levels. (#7621)
  • Added a method to MGLMapView that allows you to specify a predicate when querying for visible features. (#8256)
  • Fixed flickering that occurred when panning past the antimeridian. (#7574)
  • Added a MGLDistanceFormatter class for formatting geographic distances. (#7888)