Description

A basemap for a map or a scene.

Instances of this class represent a basemap for a map or a scene.

A basemap helps orient the user and provides a geographical context for the content you want to display in the scene. It is used for locational reference and provides a framework on which you can overlay operational layers. Thus, the basemap serves as a foundation and provides a framework for working with information geographically. It's content is typically static and does not change frequently. For eg, streets, parcel boundaries, or geographic features such as rivers. Some basemaps also contain reference layers, such as labels, which are drawn on top of operational layers.

ArcGIS Online provides a number of ready-to-use basemaps such as streetsBasemap (AGSBasemap(AGSDeprecated)), topographicBasemap (AGSBasemap(AGSDeprecated)), etc, but you can also create your own basemap by mashing up layers. A basemap is composed of a collection of baseLayers, and referenceLayers. Base layers are displayed at the bottom, and reference layers are displayed at the top, with other operational layers sandwiched between them. The content of a basemap is typically static and does not change frequently.

In order to take advantage of geographically load balanced services and monitor usage with API keys or named users, use initWithStyle: (AGSBasemap).

Since: 100

Inheritance diagram for AGSBasemap:

Instance Methods
(void)	- cancelLoad

(void)	- doCancelLoading

(void)	- doStartLoading:

(instancetype)	- init

(instancetype)	- initWithBaseLayer:

(instancetype)	- initWithBaseLayers:referenceLayers:

(instancetype)	- initWithItem:

(instancetype)	- initWithStyle:

(nullable instancetype)	- initWithURL:

(void)	- loadDidFinishWithError:

(void)	- loadWithCompletion:

(void)	- onLoadStatusChanged

(void)	- retryLoadWithCompletion:

(nullable id)	- toJSON:

Class Methods
(instancetype)	+ basemap

(instancetype)	+ basemapWithBaseLayer:

(instancetype)	+ basemapWithBaseLayers:referenceLayers:

(instancetype)	+ basemapWithItem:

(instancetype)	+ basemapWithStyle:

(nullable instancetype)	+ basemapWithURL:

(instancetype)	+ darkGrayCanvasVectorBasemap

(nullable id< AGSJSONSerializable >)	+ fromJSON:error:

(instancetype)	+ imageryBasemap

(instancetype)	+ imageryWithLabelsBasemap

(instancetype)	+ imageryWithLabelsVectorBasemap

(instancetype)	+ lightGrayCanvasBasemap

(instancetype)	+ lightGrayCanvasVectorBasemap

(instancetype)	+ nationalGeographicBasemap

(instancetype)	+ navigationVectorBasemap

(instancetype)	+ oceansBasemap

(instancetype)	+ openStreetMapBasemap

(instancetype)	+ streetsBasemap

(instancetype)	+ streetsNightVectorBasemap

(instancetype)	+ streetsVectorBasemap

(instancetype)	+ streetsWithReliefVectorBasemap

(instancetype)	+ terrainWithLabelsBasemap

(instancetype)	+ terrainWithLabelsVectorBasemap

(instancetype)	+ topographicBasemap

(instancetype)	+ topographicVectorBasemap

Properties
NSString *	APIKey

NSMutableArray< AGSLayer * > *	baseLayers

AGSCredential *	credential

AGSItem *	item

NSError *	loadError

AGSLoadStatus	loadStatus

NSString *	name

NSMutableArray< AGSLayer * > *	referenceLayers

AGSRequestConfiguration *	requestConfiguration

NSDictionary< NSString , id >	unknownJSON

NSDictionary< NSString , id >	unsupportedJSON

NSURL *	URL

Method Documentation

◆ basemap

+ (instancetype) basemap

Instantiates a new basemap.

Since: 100

◆ basemapWithBaseLayer:

+ (instancetype) basemapWithBaseLayer: (AGSLayer *) layer

Instantiates a new basemap.

Parameters

layer The layer to be used as the basemap's base layer

Since: 100

◆ basemapWithBaseLayers:referenceLayers:

+ (instancetype) basemapWithBaseLayers:	(NSArray< AGSLayer * > *)	baseLayers
referenceLayers:	(nullable NSArray< AGSLayer * > *)	referenceLayers

Instantiates a new basemap.

Parameters

baseLayers	The layers to be used as the basemap's base layers
referenceLayers	The layers to be used as the basemap's reference layers

Since: 100

◆ basemapWithItem:

+ (instancetype) basemapWithItem: (AGSItem *) item

Instantiates a new basemap.

Parameters

item	The web map item on ArcGIS Online or an on-premise portal that represents a basemap

Note: The item must be of type AGSPortalItemTypeWebMap.

Since: 100

◆ basemapWithStyle:

+ (instancetype) basemapWithStyle: (AGSBasemapStyle) style

Creates a basemap with a style.

Parameters

style The basemap style.

See also: AGSBasemapStyle

Since: 100.10

◆ basemapWithURL:

+ (nullable instancetype) basemapWithURL: (NSURL *) URL

Instantiate a basemap with a URL to a portal item which is a web basemap.

Parameters

URL	of the web basemap on ArcGIS Online or an on-premises portal

Returns: The basemap created from the URL, or nil if an invalid URL is passed.

Since: 100.4

◆ cancelLoad

- (void) cancelLoad

requiredinherited

Cancels loading if it is in progress, otherwise it does nothing. This should be called carefully because other objects could be waiting for loadWithCompletion: or retryLoadWithCompletion: to complete and this will call them all back with the error of NSUserCancelledError

Since: 100

◆ darkGrayCanvasVectorBasemap

+ (instancetype) darkGrayCanvasVectorBasemap

Instantiates a new basemap based on ArcGIS Online Dark Gray Canvas basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISDarkGray.

Provided by category AGSBasemap(AGSDeprecated).

◆ doCancelLoading

- (void) doCancelLoading

Never call this method directly. The framework calls this method on a background thread when cancelLoad (AGSLoadable-p) is called. It is meant to be overriden by subclasses. Subclasses should override this method to cancel loading their data and call loadDidFinishWithError: (AGSLoadableBase(ForSubclassEyesOnly)) at the end passing in an error representing NSUserCancelledError.

Since: 100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ doStartLoading:

- (void) doStartLoading: (BOOL) retrying

Never call this method directly. The framework calls this method on a background thread when loadWithCompletion: (AGSLoadable-p) or retryLoadWithCompletion: (AGSLoadable-p) is called. It is meant to be overriden by subclasses. Subclasses should override this method to load their data and call loadDidFinishWithError: (AGSLoadableBase(ForSubclassEyesOnly)) upon completion, passing in the error if any.

Parameters

retrying flag that is true if this method was called from retryLoadWithCompletion: (AGSLoadable-p).

Since: 100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ fromJSON:error:

+ (nullable id<AGSJSONSerializable>) fromJSON:	(id)	JSONObject
error:	(NSError **)	error

staticrequiredinherited

Initializes and returns an object from its JSON representation.

Parameters

JSONObject	`NSDictionary` or `NSArray` containing the JSON.
error	encountered during the operation, if any.

Since: 100

◆ imageryBasemap

+ (instancetype) imageryBasemap

Instantiates a new basemap based on ArcGIS Online World Imagery basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISImageryStandard.

Provided by category AGSBasemap(AGSDeprecated).

◆ imageryWithLabelsBasemap

+ (instancetype) imageryWithLabelsBasemap

Instantiates a new basemap based on ArcGIS Online Imagery with Labels basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISImagery.

Provided by category AGSBasemap(AGSDeprecated).

◆ imageryWithLabelsVectorBasemap

+ (instancetype) imageryWithLabelsVectorBasemap

Instantiates a new basemap based on ArcGIS Online Imagery Hybrid basemap.

Since: 100\

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISImagery.

Provided by category AGSBasemap(AGSDeprecated).

◆ init

- (instancetype) init

◆ initWithBaseLayer:

- (instancetype) initWithBaseLayer: (AGSLayer *) layer

Instantiates a new basemap.

Parameters

layer The layer to be used as the basemap's base layer

Since: 100

◆ initWithBaseLayers:referenceLayers:

- (instancetype) initWithBaseLayers:	(NSArray< AGSLayer * > *)	baseLayers
referenceLayers:	(nullable NSArray< AGSLayer * > *)	referenceLayers

Instantiates a new basemap.

Parameters

baseLayers	The layers to be used as the basemap's base layers
referenceLayers	The layers to be used as the basemap's reference layers

Since: 100

◆ initWithItem:

- (instancetype) initWithItem: (AGSItem *) item

Instantiates a new basemap.

Parameters

item	The item on ArcGIS Online or an on-premise portal that represents a basemap

Since: 100

◆ initWithStyle:

- (instancetype) initWithStyle: (AGSBasemapStyle) style

Creates a basemap with a style.

Parameters

style The basemap style.

See also: AGSBasemapStyle

Since: 100.10

◆ initWithURL:

- (nullable instancetype) initWithURL: (NSURL *) URL

Instantiate a basemap with a URL to a portal item which is a web basemap.

Parameters

URL	of the web basemap on ArcGIS Online or an on-premises portal

Returns: The basemap created from the URL, or nil if an invalid URL is passed.

Since: 100.4

◆ lightGrayCanvasBasemap

+ (instancetype) lightGrayCanvasBasemap

Instantiates a new basemap based on ArcGIS Online Light Gray Canvas basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISLightGray.

Provided by category AGSBasemap(AGSDeprecated).

◆ lightGrayCanvasVectorBasemap

+ (instancetype) lightGrayCanvasVectorBasemap

Instantiates a new basemap based on ArcGIS Online Light Gray Canvas basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISLightGray.

Provided by category AGSBasemap(AGSDeprecated).

◆ loadDidFinishWithError:

- (void) loadDidFinishWithError: (nullable NSError *) error

Only subclasses should call this method in doStartLoading: (AGSLoadableBase(ForSubclassEyesOnly)) and doCancelLoading (AGSLoadableBase(ForSubclassEyesOnly)) when done loading or failed to load.

Since: 100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ loadWithCompletion:

- (void) loadWithCompletion: (nullable void(^)(NSError *__nullable error)) completion

requiredinherited

Loads data for the object asynchronously. The completion block is invoked upon completion.

You can call this method any number of times, however only one attempt is made to load the data. If it is already loading, it will just continue to load (i.e. not force a reload). If it has already loaded successfully, the completion block will be invoked right away. If it has already failed to load, the completion block will be invoked right away with error previously encountered. This method supports multiple callers and will call them all back on completion. However, each caller's completion block will be invoked once and only once.

Parameters

completion block that is invoked when object loads successfully or fails to load. An error is passed to the block if the object fails to load.

Note: The completion block is always invoked on the main thread.

Since: 100

See also: - cancelLoad to cancel loading; - retryLoadWithCompletion: to force reload

◆ nationalGeographicBasemap

+ (instancetype) nationalGeographicBasemap

Instantiates a new basemap based on ArcGIS Online National Geographic World basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use the National Geographic Style Map. https://www.arcgis.com/home/item.html?id=f33a34de3a294590ab48f246e99958c9

Provided by category AGSBasemap(AGSDeprecated).

◆ navigationVectorBasemap

+ (instancetype) navigationVectorBasemap

Instantiates a new basemap based on ArcGIS Online World Navigation Map basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISNavigation.

Provided by category AGSBasemap(AGSDeprecated).

◆ oceansBasemap

+ (instancetype) oceansBasemap

Instantiates a new basemap based on ArcGIS Online Oceans basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISOceans.

Provided by category AGSBasemap(AGSDeprecated).

◆ onLoadStatusChanged

- (void) onLoadStatusChanged

Never call this method directly. The framework calls this method on a background thread when AGSLoadable::loadStatus changes is called. Subclasses can optionally implement this to know when their loading status has changed.

Since: 100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ openStreetMapBasemap

+ (instancetype) openStreetMapBasemap

Instantiates a new basemap based on OpenStreetMap basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleOSMStandard.

Provided by category AGSBasemap(AGSDeprecated).

◆ retryLoadWithCompletion:

- (void) retryLoadWithCompletion: (nullable void(^)(NSError *__nullable error)) completion

requiredinherited

Tries to reload when an object has failed to load. This method should be called judiciously. It should be called when:

you didn't have network connectivity earlier when it failed and you want to retry now that you have connectivity
the server was down earlier when it failed and you want to retry
the request is taking too long and you want to cancel it and retry, in which case you will first call cancelLoad and then this method

If the data hasn't started loading, it will start loading. If it is already loading, it will just continue to load. If it has already loaded successfully, calls back right away. If it has already failed to load, tries again. This method supports multiple callers and will call them all back on completion. However, each caller's completion block will be invoked once and only once.

Parameters

completion block that is invoked when object loads successfully or fails to load. An error is passed to the block if the object fails to load.

Note: The completion block is always invoked on the main thread.

Since: 100

◆ streetsBasemap

+ (instancetype) streetsBasemap

Instantiates a new basemap based on ArcGIS Online World Street basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISStreets.

Provided by category AGSBasemap(AGSDeprecated).

◆ streetsNightVectorBasemap

+ (instancetype) streetsNightVectorBasemap

Instantiates a new basemap based on ArcGIS Online World Street Map (Night) basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISStreetsNight.

Provided by category AGSBasemap(AGSDeprecated).

◆ streetsVectorBasemap

+ (instancetype) streetsVectorBasemap

Instantiates a new basemap based on ArcGIS Online World Street Map basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISStreets.

Provided by category AGSBasemap(AGSDeprecated).

◆ streetsWithReliefVectorBasemap

+ (instancetype) streetsWithReliefVectorBasemap

Instantiates a new basemap based on ArcGIS Online Streets (with Relief) basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISStreetsRelief.

Provided by category AGSBasemap(AGSDeprecated).

◆ terrainWithLabelsBasemap

+ (instancetype) terrainWithLabelsBasemap

Instantiates a new basemap based on ArcGIS Online Terrain with Labels basmap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISTerrain.

Provided by category AGSBasemap(AGSDeprecated).

◆ terrainWithLabelsVectorBasemap

+ (instancetype) terrainWithLabelsVectorBasemap

Instantiates a new basemap based on ArcGIS Online Terrain with Labels basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISTerrain.

Provided by category AGSBasemap(AGSDeprecated).

◆ toJSON:

- (nullable id) toJSON: (NSError **) error

requiredinherited

Returns JSON representation for this object.

Parameters

error encountered during the operation, if any.

Returns: NSDictionary or NSArray containing the JSON.

Since: 100

Reimplemented in AGSPortalItem.

◆ topographicBasemap

+ (instancetype) topographicBasemap

Instantiates a new basemap based on ArcGIS Online World Topographic basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISTopographic.

Provided by category AGSBasemap(AGSDeprecated).

◆ topographicVectorBasemap

+ (instancetype) topographicVectorBasemap

Instantiates a new basemap based on ArcGIS Online Topographic basemap.

Since: 100

Deprecated:: 100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISTopographic.

Provided by category AGSBasemap(AGSDeprecated).

Property Documentation

◆ APIKey

- (NSString*) APIKey

readwriterequirednonatomiccopyinherited

The API key to access API key enabled services and resources in ArcGIS Online.

An API key is a unique key used to authorize access to specific services and resources in ArcGIS Online. It is also used to monitor access to those services. An API key is created and managed in the ArcGIS developer dashboard and is tied to a specific ArcGIS account.

In addition to setting an API key at a global level for your application using the AGSArcGISRuntimeEnvironment::APIKey property, you can set an AGSAPIKeyResource::APIKey property on any ArcGIS Runtime class that implements AGSAPIKeyResource. When you set an individual AGSAPIKeyResource::APIKey property on an AGSAPIKeyResource it will override the default key at the global level (on the AGSArcGISRuntimeEnvironment::APIKey property, in other words), enabling more granular usage telemetry and management for ArcGIS Online resources used by your app. Classes that expose an API key property by implementing AGSAPIKeyResource include:

◆ baseLayers

- (NSMutableArray<AGSLayer*>*) baseLayers

readnonatomicstrong

The base layers of this basemap. Base layers are displayed at the bottom in a mapview, and reference layers are displayed at the top, with the map's operational layers sandwiched between them. The layers are drawn in a bottom-up fashion with the 0th layer in the list drawn first, next layer drawn on top of the previous one, and so on.

Note: This array does not allow duplicate objects.

Since: 100

◆ credential

- (AGSCredential*) credential

readwritenonatomicstronginherited

Security credentials to access the remote resource. Only applicable if the resource is secured.

Since: 100

◆ item

- (AGSItem*) item

readnonatomicstrong

The portal item that was used to create the basemap

Since: 100

◆ loadError

- (NSError*) loadError

readnonatomicstronginherited

The error that was encountered during the most recent load operation. Will be nil if the operation succeeded.

Since: 100

◆ loadStatus

- (AGSLoadStatus) loadStatus

readrequirednonatomicassigninherited

Status of the load operation.

Since: 100

◆ name

- (NSString*) name

readwritenonatomiccopy

The name of the basemap

Since: 100

◆ referenceLayers

- (NSMutableArray<AGSLayer*>*) referenceLayers

readnonatomicstrong

The reference layers of this basemap. Base layers are displayed at the bottom in a mapview, and reference layers are displayed at the top, with the map's operational layers sandwiched between them. The layers are drawn in a bottom-up fashion with the 0th layer in the list drawn first, next layer drawn on top of the previous one, and so on.

Note: This array does not allow duplicate objects.

Since: 100

◆ requestConfiguration

- (AGSRequestConfiguration*) requestConfiguration

readwritenonatomicstronginherited

The AGSRequestConfiguration object which defines the behavior and policies to use when accessing the remote resource. The default will be nil. If it is nil the [AGSRequestConfiguration globalConfiguration] will be used.

Since: 100

◆ unknownJSON

- (NSDictionary<NSString*,id>*) unknownJSON

readrequirednonatomiccopyinherited

A dictionary of values that was in the source JSON but was unparsed by API.

Returns: NSDictionary containing the unknown JSON.

Since: 100

◆ unsupportedJSON

- (NSDictionary<NSString*,id>*) unsupportedJSON

readnonatomiccopyinherited

A dictionary of values that are supported by the REST API, but not exposed through the SDK API.

Returns: NSDictionary containing the unsupported JSON.

Since: 100

◆ URL

- (NSURL*) URL

readrequirednonatomicstronginherited

The URL of the remote resource.

Since: 100

Description

Instance Methods

Class Methods

Properties

Method Documentation

◆ basemap

◆ basemapWithBaseLayer:

◆ basemapWithBaseLayers:referenceLayers:

◆ basemapWithItem:

◆ basemapWithStyle:

◆ basemapWithURL:

◆ cancelLoad

◆ darkGrayCanvasVectorBasemap

◆ doCancelLoading

◆ doStartLoading:

◆ fromJSON:error:

◆ imageryBasemap

◆ imageryWithLabelsBasemap

◆ imageryWithLabelsVectorBasemap

◆ init

◆ initWithBaseLayer:

◆ initWithBaseLayers:referenceLayers:

◆ initWithItem:

◆ initWithStyle:

◆ initWithURL:

◆ lightGrayCanvasBasemap

◆ lightGrayCanvasVectorBasemap

◆ loadDidFinishWithError:

◆ loadWithCompletion:

◆ nationalGeographicBasemap

◆ navigationVectorBasemap

◆ oceansBasemap

◆ onLoadStatusChanged

◆ openStreetMapBasemap

◆ retryLoadWithCompletion:

◆ streetsBasemap

◆ streetsNightVectorBasemap

◆ streetsVectorBasemap

◆ streetsWithReliefVectorBasemap

◆ terrainWithLabelsBasemap

◆ terrainWithLabelsVectorBasemap

◆ toJSON:

◆ topographicBasemap

◆ topographicVectorBasemap

Property Documentation

◆ APIKey

◆ baseLayers

◆ credential

◆ item

◆ loadError

◆ loadStatus

◆ name

◆ referenceLayers

◆ requestConfiguration

◆ unknownJSON

◆ unsupportedJSON

◆ URL