Working with GeoJSON Data

This SDK offers several ways to work with GeoJSON files. GeoJSON is a standard file format for representing geographic data.

Adding a GeoJSON file to the map

You can use Mapbox Studio’s Datasets editor to upload a GeoJSON file and include it in your custom map style. The GeoJSON data will be hosted on Mapbox servers. When a user loads your style, the SDK automatically loads the GeoJSON data for display.

Alternatively, if you need to host the GeoJSON file elsewhere or bundle it with your application, you can use a GeoJSON file as the basis of an MGLShapeSource object. Pass the file’s URL into the -[MGLShapeSource initWithIdentifier:URL:options:] initializer and add the shape source to the map using the -[MGLStyle addSource:] method. The URL may be a local file URL, an HTTP URL, or an HTTPS URL.

Once you’ve added the GeoJSON file to the map via an MGLShapeSource object, you can configure the appearance of its data and control what data is visible using MGLStyleLayer objects, you can access the data programmatically.

Converting GeoJSON data into shape objects

If you have GeoJSON data in the form of source code (also known as “GeoJSON text”), you can convert it into an MGLShape, MGLFeature, or MGLShapeCollectionFeature object that the MGLShapeSource class understands natively. First, create an NSData object out of the source code string or file contents, then pass that data object into the +[MGLShape shapeWithData:encoding:error:] method. Finally, you can pass the resulting shape or feature object into the -[MGLShapeSource initWithIdentifier:shape:options:] initializer and add it to the map, or you can use the object and its properties to power non-map-related functionality in your application.

To include multiple shapes in the source, create and pass an MGLShapeCollection or MGLShapeCollectionFeature object to -[MGLShapeSource initWithIdentifier:shape:options:]. Alternatively, use the -[MGLShapeSource initWithIdentifier:features:options:] or -[MGLShapeSource initWithIdentifier:shapes:options:] method to create a shape source with an array. -[MGLShapeSource initWithIdentifier:features:options:] accepts only MGLFeature instances, such as MGLPointFeature objects, whose attributes you can use when applying a predicate to MGLVectorStyleLayer or configuring a style layer’s appearance.

Extracting GeoJSON data from the map

Any MGLShape, MGLFeature, or MGLShapeCollectionFeature object has an -[MGLShape geoJSONDataUsingEncoding:] method that you can use to create a GeoJSON source code representation of the object. You can extract a feature object from the map using a method such as -[MGLMapView visibleFeaturesAtPoint:].

About GeoJSON deserialization

The process of converting GeoJSON text into MGLShape, MGLFeature, or MGLShapeCollectionFeature objects is known as “GeoJSON deserialization”. GeoJSON geometries, features, and feature collections are known in this SDK as shapes, features, and shape collection features, respectively.

Each GeoJSON object type corresponds to a type provided by either this SDK or the Core Location framework:

GeoJSON object type	SDK type
Position (longitude, latitude)	CLLocationCoordinate2D (latitude, longitude)
Point	MGLPointAnnotation
MultiPoint	MGLPointCollection
LineString	MGLPolyline
MultiLineString	MGLMultiPolyline
Polygon	MGLPolygon
Linear ring	MGLPolygon.coordinates, MGLPolygon.interiorPolygons
MultiPolygon	MGLMultiPolygon
GeometryCollection	MGLShapeCollection
Feature	MGLFeature
FeatureCollection	MGLShapeCollectionFeature

A Feature object in GeoJSON corresponds to an instance of an MGLShape subclass conforming to the MGLFeature protocol. There is a distinct MGLFeature-conforming class for each type of geometry that a GeoJSON feature can contain. This allows features to be used as raw shapes where convenient. For example, some features can be added to a map view as annotations. Note that identifiers and attributes will not be available for feature querying when a feature is used as an annotation.

In contrast to the GeoJSON standard, it is possible for MGLShape subclasses other than MGLPointAnnotation to straddle the antimeridian.

The following GeoJSON data types correspond straightforwardly to Foundation data types when they occur as feature identifiers or property values:

GeoJSON data type	Objective-C representation	Swift representation
null	NSNull	NSNull
true, false	NSNumber.boolValue	Bool
Integer	NSNumber.unsignedLongLongValue, NSNumber.longLongValue	UInt64, Int64
Floating-point number	NSNumber.doubleValue	Double
String	NSString	String