メインコンテンツまでスキップ

Add your data to the map

When using the Mapbox Maps SDK for iOS, there are several ways to add your own data. The right approach depends on the type, quantity, and style of data you want to display.

The most important distinction is whether you want to display data above the map or within the map itself, as each approach has fundamental differences in how the data is loaded, styled and interacted with.

Above the Map: Annotations
Visual elements drawn above the map, easy to add and interact with.
Above the Map: View Annotations
Custom SwiftUI or UIKit views drawn above the map, easy to add and interact with.
In the Map: Style Layers
Data rendered as part of the map itself with high performance.

Understanding how the Map is rendered​

Mapbox maps are rendered entirely on the client device using Apple's Metal graphics technology, which enables high-performance, smooth rendering of complex geographic data.

The map you see is not a single image, but rather a composite of many virtual layers. The SDK fetches data for roads, buildings, and other map features from Mapbox servers, assembles these layers in memory, and presents them based on the current map position, zoom level, and style. In the Mapbox Maps SDK for iOS, this rendering is handled by the MapView class when using UIKit and the Map struct when using SwiftUI.

This client-side rendering enables smooth interactions with the map - you can rotate, tilt, and zoom while maintaining crisp visuals at any scale. The SDK dynamically loads additional data as needed based on the current view.

Understanding this architecture is key to choosing how to add your data: you can either add visual elements above the map using elements rendered in the native UI layer (annotations) or integrate your data into the map itself as additional layers that can be mixed into the existing layer stack (style layers).

Above the Map: Annotations & View Annotations
Annotations are rendered above the map by the native UI layer, and are fixed to a geographic location so they will move when the map moves.
In the Map: Style Layers
Style layers are rendered as part of the map itself, allowing for high-performance visualization of large datasets, and positioning relative to other map features.

Choosing the right approach​

When deciding how to add your data to the map, consider the following factors:

  • The complexity of your data
  • The level of interactivity you need
  • Performance requirements
  • Development time and effort

Annotations generally have a lower learning curve and are easier to implement, while style layers offer more flexibility and performance for complex datasets.

Annotations​

Annotations are individually styled images, circles, line, or polygons that are displayed above the map. They are managed by the SDK's Annotation API and are ideal for quickly adding images, lines, polygons, or full UIViews pinned to specific geographic coordinates.

Advantages:

  • Easier to use — no need to work directly with map style layers or sources.
  • Ideal for interactive features (tapping, dragging, etc.).
  • Automatically managed by the SDK (rendering, hit-testing).
  • Works with standard geographic data formats (GeoJSON, etc.).
  • Several options available

Limitations:

  • Limited styling flexibility compared to layers.
  • Less efficient for large datasets (performance may degrade with hundreds of annotations).

View Annotations​

View Annotations are native iOS UIViews positioned at geographic coordinates on the map. They are ideal for overlaying completely custom UI elements (buttons, labels, images, data-driven views) that behave like part of the map.

Advantages:

  • Full power of UIKit — animations, gesture handling, custom layouts.
  • Can display dynamic or complex components not possible with pure map styling.
  • Data can be sourced from any format — you only need geographic coordinates to position the views.

Limitations:

  • Less efficient for large datasets (performance may degrade with hundreds of annotations).

Style Layers​

Style layers are additional layers rendered as part of the map, integrated along with the roads, buildings, and other map features — sources provide the geographic data (GeoJSON, vector tiles, raster tiles), and layers define how that data is styled (circle, fill, line, symbol, heatmap, etc.).

They are ideal for large or complex datasets, advanced styling, or when you need precise control over map rendering.

Advantages:

  • Maximum flexibility and performance — can handle tens of thousands of features.
  • Compatible with vector tiles for large datasets with wide geographic coverage.
  • Can make style changes dynamically without reloading the data.
  • Can use data-driven styling (styles change based on feature properties).

Limitations:

  • More verbose to set up, requires familiarity with the Mapbox Style Specification.
  • Requires data in specific formats, such as GeoJSON or vector tiles.
  • Complex integration for user interaction — you'll need to add gesture recognizers and query rendered features manually.
このpageは役に立ちましたか？