MapboxStatic

MapboxStatic is a Swift library for Mapbox's static maps API, with support for overlays, asynchronous imagery fetching, and first-class Swift data types.

Static maps are flattened PNG or JPG images, ideal for use in table views, image views, and anyplace else you'd like a quick, custom map without the overhead of an interactive view. They are created in one HTTP request, so overlays are all added server-side.

Installation

Drag the MapboxStatic.swift file into your project. If calling from Objective-C code, import <TargetName>-Swift.h first.

Usage

You will need a map ID from a custom map style on your Mapbox account. You will also need an access token in order to use the API.

Basics

The main map class is MapboxStaticMap. To create a basic map, specify the center, zoom level, and pixel size:

let map = MapboxStaticMap(
    mapID: <your map ID>,
    center: CLLocationCoordinate2D(latitude: 45.52, longitude: -122.681944),
    zoom: 13,
    size: CGSize(width: 200, height: 200),
    accessToken: <your API token>
)

Then, to retrieve an image, you can do it either synchronously (blocking the calling thread):

self.imageView.image = map.image

Or you can pass a completion handler to update the UI thread after the image is retrieved:

map.imageWithCompletionHandler { image in
    imageView.image = image
}

If you're using your own HTTP library or routines, you can also retrieve a map object's requestURL property.

let requestURLToFetch = map.requestURL

Overlays

Overlays are where things get interesting! You can add Maki markers, custom marker imagery, GeoJSON geometries, and even paths made of bare coordinates.

You pass overlays as the overlays: [Overlay] parameter during map creation. Here are some versions of our map with various overlays added.

Marker

let markerOverlay = MapboxStaticMap.Marker(
    coordinate: CLLocationCoordinate2D(latitude: 45.52, longitude: -122.681944),
    size: .Medium,
    label: "cafe",
    color: UIColor.brownColor()
)

Custom Marker

let customMarker = MapboxStaticMap.CustomMarker(
    coordinate: CLLocationCoordinate2D(latitude: 45.522, longitude: -122.69),
    URLString: "https://mapbox.com/foundations/img/pages/rocket.png"
)

GeoJSON

let GeoJSONOverlay = MapboxStaticMap.GeoJSON(
    GeoJSON: NSString(
        contentsOfFile: NSBundle.mainBundle().pathForResource("sample", ofType: "geojson")!,
        encoding: NSUTF8StringEncoding,
        error: nil
    )!
)

Path

let path = MapboxStaticMap.Path(
    pathCoordinates: [
        CLLocationCoordinate2D(
            latitude: 45.52475063103141, longitude: -122.68209457397461
        ),
        CLLocationCoordinate2D(
            latitude: 45.52451009822193, longitude: -122.67488479614258
        ),
        CLLocationCoordinate2D(
            latitude: 45.51681250530043, longitude: -122.67608642578126
        ),
        CLLocationCoordinate2D(
            latitude: 45.51693278828882, longitude: -122.68999099731445
        ),
        CLLocationCoordinate2D(
            latitude: 45.520300607576864, longitude: -122.68964767456055
        ),
        CLLocationCoordinate2D(
            latitude: 45.52475063103141, longitude: -122.68209457397461
        )
    ],
    strokeWidth: 2,
    strokeColor: UIColor.blackColor(),
    fillColor: UIColor.redColor(),
    fillOpacity: 0.25
)

Other options

Auto-fitting features

If you're adding overlays to your map, you can use the autoFitFeatures flag to automatically calculate the center and zoom that best shows them off.

let map = MapboxStaticMap(
    mapID: <your map ID>,
    size: CGSize(width: 500, height: 300),
    accessToken: <your API token>,
    overlays: [path, GeoJSONOverlay, markerOverlay, customMarker],
    autoFitFeatures: true
)

File format & quality

When creating a map, you can also specify PNG or JPEG image format as well as various bandwidth-saving image qualities.

Attribution

Be sure to attribute your map properly in your app. You can also find out more about where Mapbox's map data comes from.

More info

For more info about the Mapbox static maps API, check out the web service documentation.