# Modules.Map

Add-on Map module

Availability

3.1.0

3.2.0

9.2.0

Extends

Titanium.Module

# Overview

# Requirements

Google Maps API key (required for both development and production)
Google Play services SDK installed using the Android SDK manager
This module only works on Android devices. This module is not supported on the Android emulator

# Getting Started

Edit the modules section of your tiapp.xml file to include this module:

<ti:app>
    <modules>
        <!-- Add this line to your modules section -->
        <module platform="android">ti.map</module>
    </modules>
</ti:app>

Obtain a Google Maps API key. For instructions, refer to the "Obtain and Add a Google API Key" section in the Google Maps v2 for Android guide (opens new window).

Add the following meta-tag element to the Android manifest section of the tiapp.xml file. You may need to add the manifest and application elements.

<ti:app>
    <android xmlns:android="http://schemas.android.com/apk/res/android">
        <manifest>
            <application>
                <!-- Replace "YOUR_API_KEY" with the Google API key you obtained -->
                <meta-data 
                    android:name="com.google.android.geo.API_KEY"
                    android:value="YOUR_API_KEY" />
            </application>
        </manifest>
    </android>
</ti:app>

Instantiate the module with the require('ti.map') method, then make subsequent API calls with the new map object.
```
var Map = require('ti.map');
var mapview = Map.createView({ 
  mapType: Map.NORMAL_TYPE 
});
```

# iOS

This module is a replacement for the built-in Titanium.Map module on iOS.

For more instructions and examples of using the module, refer to the iOS Map Kit guide (opens new window).

# Requirements

Applications using this module must be built using Xcode 5 or later.

# Getting Started

Edit the modules section of your tiapp.xml file to include this module:

<ti:app>
    <modules>
        <!-- Add this line to your modules section -->
        <module platform="iphone">ti.map</module>
    </modules>
</ti:app>

To use the userLocation property in iOS 8 and later, add either the NSLocationWhenInUseUsageDescription (opens new window) or NSLocationAlwaysUsageDescription (opens new window) key to the iOS plist section of the project's tiapp.xml file.

<ti:app>
    <ios>
        <plist>
            <dict>
                <key>NSLocationAlwaysUsageDescription</key>
                <string>
                    Specify the reason for accessing the user's location information.
                    This appears in the alert dialog when asking the user for permission to
                    access their location.
                </string>
            </dict>
        </plist>
    </ios>
</ti:app>

Instantiate the module with the require('ti.map') method, then make subsequent API calls with the new map object.
```
var Map = require('ti.map');
var mapview = Map.createView({
  mapType: Map.NORMAL_TYPE
});
```

# Breaking Changes

The addRoute method no longer accepts a dictionary as a parameter. Pass a Modules.Map.Route object instead.

# Examples

# Basic Map Example

This is a basic map example that places a custom annotation on the map, and listens for click events on the annotation.

In this example, a custom property (myid) is added to the annotation object. While adding custom members to a Titanium object is not generally recommended, in this case it provides a mechanism for uniquely identifying an annotation. This can be useful, for example, if the annotations are dynamically generated and it is not practical to identify them by title.

var Map = require('ti.map');
var win = Titanium.UI.createWindow();

var mountainView = Map.createAnnotation({
    latitude: 37.390749,
    longitude: -122.081651,
    title: 'Appcelerator Headquarters',
    subtitle: 'Mountain View, CA',
    pincolor: Map.ANNOTATION_RED,
    myid: 1 // Custom property to uniquely identify this annotation.
});

var mapview = Map.createView({
    mapType: Map.NORMAL_TYPE,
    region: { 
        latitude: 33.74511,
        longitude: -84.38993,
        latitudeDelta: 0.01,
        longitudeDelta: 0.01
    },
    animate: true,
    regionFit: true,
    userLocation: true,
    annotations: [ mountainView ]
});

var circle = Map.createCircle({
    center: {
        latitude: 33.74511,
        longitude: -84.38993
    },
    radius: 1000, // = 1.0 km
    fillColor: '#20FF0000'
});
mapview.addCircle(circle);

win.add(mapview);

mapview.addEventListener('click', function(event) {
    Ti.API.info('Clicked ' + event.clicksource + ' on ' + event.latitude + ', ' + event.longitude);
});
win.open();

# Alloy XML Markup

Previous example as an Alloy view.

In XML markup, use the View element with the module attribute set to ti.map to create an instance of a map view, then use the Annotation element to define an annotation.

In the initializer file, load the map module and assign it to the Alloy.Globals.Map namespace. This variable can be used to reference map module constants in the project, as seen in the TSS file to assign the pincolor attribute.

alloy.js:

// Loads the map module to the global Alloy scope, which can be referenced by Alloy.Globals.Map
Alloy.Globals.Map = require('ti.map');

app/views/index.xml:

<Alloy>
    <Window>
        <Module id="mapview" module="ti.map" onClick="report" method="createView">
            <Annotation id="appcHQ" myId="1337" />
        </Module>
    </Window>
</Alloy>

app/styles/index.tss:

"#mapview": {
    region: {
        latitude: 33.74511,
        longitude: -84.38993,
        latitudeDelta: 0.01,
        longitudeDelta: 0.01
    }
},
"#appcHQ": {
    latitude: 37.368122,
    longitude: -121.913653,
    title: "Appcelerator Headquarters",
    subtitle: "San Jose, CA",
    pincolor: Alloy.Globals.Map.ANNOTATION_RED
}

app/controllers/index.js:

function report(event) {
    Ti.API.info('Annotation ' + event.title + ' clicked, ID: ' + event.annotation.myID);
}

$.index.open();

# Map Clustering (iOS 11+)

This is a map-example which creates marker annotation and clustering of annotations.

The clusterIdentifier property and the clusterstart event are required in order to enable clustering. You can control the clustering by defining the collisionMode property and setting special cluster annotations using the setClusterAnnotation method on your map view instance.

var Map = require('ti.map');
var win = Titanium.UI.createWindow();
var annotations = [];

for (var i = 0; i < 10; i++) {
    annotations.push(Map.createAnnotation({
        title: 'Appcelerator Inc.',
        subtitle: 'TiRocks!',
        clusterIdentifier: 'abc', // Required for clusters
        collisionMode: Map.ANNOTATION_VIEW_COLLISION_MODE_RECTANGLE,
        showAsMarker: true,
        markerGlyphText: i.toString(),
        markerColor: 'blue',
        markerGlyphColor: 'green',
        markerTitleVisibility: Map.FEATURE_VISIBILITY_VISIBLE,
        markerSubtitleVisibility: Map.FEATURE_VISIBILITY_HIDDEN,
        markerGlyphImage: 'path/to/flag.png',
        markerSelectedGlyphImage: 'path/to/flag-selected.png',
        annotationDisplayPriority: Map.FEATURE_DISPLAY_PRIORITY_DEFAULT_LOW,
        latitude: (Math.random() * 10) + 40,
        longitude: Math.random() * 10,
    }));
}

var mapview = Map.createView({
    annotations: annotations,
    rotateEnabled: true,
    mapType: Map.MUTED_STANDARD_TYPE,
    showsPointsOfInterest: false,
    userLocation: true
});

mapview.addEventListener('clusterstart', function(e) {
    Ti.API.info('clustering started!');

    var clusterAnnotation = Map.createAnnotation({
        showAsMarker: true,
        markerText: e.memberAnnotations.length.toString(),
        title: 'Cluster Title',
        subtitle: 'Cluster Subtitle',
    });

    mapview.setClusterAnnotation({
        annotation: clusterAnnotation,
        memberAnnotations: e.memberAnnotations
    });
});
win.add(mapview);
win.open();

# Methods

# createAnnotation

Availability

3.1.0

3.2.0

9.2.0

createAnnotation([parameters]) → Modules.Map.Annotation

Creates and returns an instance of Modules.Map.Annotation.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.Annotation>	Properties to set on a new object, including any defined by Modules.Map.Annotation except those marked not-creation or read-only.

Returns

Type: Modules.Map.Annotation

# createCamera

Availability

9.1.0

3.2.0

9.2.0

createCamera([parameters]) → Modules.Map.Camera

Creates and returns an instance of Modules.Map.Camera.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.Camera>	Properties to set on a new object, including any defined by Modules.Map.Camera except those marked not-creation or read-only.

Returns

Type: Modules.Map.Camera

# createCircle

Availability

4.1.0

9.2.0

createCircle([parameters]) → Modules.Map.Circle

Creates and returns an instance of Modules.Map.Circle.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.Circle>	Properties to set on a new object, including any defined by Modules.Map.Circle except those marked not-creation or read-only.

Returns

Type: Modules.Map.Circle

# createImageOverlay

Availability

7.4.0

7.2.0

9.2.0

createImageOverlay([parameters]) → Modules.Map.ImageOverlay

Creates and returns an instance of Modules.Map.ImageOverlay.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.ImageOverlay>	Properties to set on a new object, including any defined by Modules.Map.ImageOverlay except those marked not-creation or read-only.

Returns

Type: Modules.Map.ImageOverlay

# createPolygon

Availability

4.1.0

9.2.0

createPolygon([parameters]) → Modules.Map.Polygon

Creates and returns an instance of Modules.Map.Polygon.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.Polygon>	Properties to set on a new object, including any defined by Modules.Map.Polygon except those marked not-creation or read-only.

Returns

Type: Modules.Map.Polygon

# createPolyline

Availability

4.1.0

9.2.0

createPolyline([parameters]) → Modules.Map.Polyline

Creates and returns an instance of Modules.Map.Polyline.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.Polyline>	Properties to set on a new object, including any defined by Modules.Map.Polyline except those marked not-creation or read-only.

Returns

Type: Modules.Map.Polyline

# createRoute

Availability

3.1.0

3.2.0

9.2.0

createRoute([parameters]) → Modules.Map.Route

Creates and returns an instance of Modules.Map.Route.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.Route>	Properties to set on a new object, including any defined by Modules.Map.Route except those marked not-creation or read-only.

Returns

Type: Modules.Map.Route

# createSnapshotter

Availability

6.0.0

9.2.0

createSnapshotter([parameters]) → Modules.Map.Snapshotter

Creates and returns an instance of Modules.Map.Snapshotter.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.Snapshotter>	Properties to set on a new object, including any defined by Modules.Map.Snapshotter except those marked not-creation or read-only.

Returns

Type: Modules.Map.Snapshotter

# createStreetViewPanorama

Availability

5.2.0

createStreetViewPanorama([parameters]) → Modules.Map.StreetViewPanorama

Creates and returns an instance of Modules.Map.StreetViewPanorama.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.StreetViewPanorama>	Properties to set on a new object, including any defined by Modules.Map.StreetViewPanorama except those marked not-creation or read-only.

Returns

Type: Modules.Map.StreetViewPanorama

# createView

Availability

3.1.0

3.2.0

9.2.0

createView([parameters]) → Modules.Map.View

Creates and returns an instance of Modules.Map.View.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Map.View>	Properties to set on a new object, including any defined by Modules.Map.View except those marked not-creation or read-only.

Returns

Type: Modules.Map.View

# isGooglePlayServicesAvailable

Availability

3.1.1

isGooglePlayServicesAvailable() → Number

Returns a code to indicate whether Google Play Services is available on the device.

Returns

One of the following status codes: SUCCESS, SERVICE_MISSING, SERVICE_VERSION_UPDATE_REQUIRED, SERVICE_DISABLED or SERVICE_INVALID.

Type: Number

# Constants

# ANNOTATION_AZURE

Availability

3.1.0

6.1.0

9.2.0

ANNOTATION_AZURE :Number

Color constant used to set a map annotation to azure via the pincolor property.

# ANNOTATION_BLUE

Availability

3.1.0

6.1.0

9.2.0

ANNOTATION_BLUE :Number

Color constant used to set a map annotation to blue via the pincolor property.

# ANNOTATION_CYAN

Availability

3.1.0

6.1.0

9.2.0

ANNOTATION_CYAN :Number

Color constant used to set a map annotation to cyan via the pincolor property.

# ANNOTATION_DRAG_STATE_END

Availability

3.1.0

3.2.0

9.2.0

ANNOTATION_DRAG_STATE_END :Number

Used in the pinchangedragstate event to indicate that the user finished moving the annotation.

# ANNOTATION_DRAG_STATE_START

Availability

3.1.0

3.2.0

9.2.0

ANNOTATION_DRAG_STATE_START :Number

Used in the pinchangedragstate event to indicate that the user started dragging the annotation.

# ANNOTATION_GREEN

Availability

3.1.0

3.2.0

9.2.0

ANNOTATION_GREEN :Number

Color constant used to set a map annotation to green via the pincolor property.

# ANNOTATION_MAGENTA

Availability

3.1.0

6.1.0

9.2.0

ANNOTATION_MAGENTA :Number

Color constant used to set a map annotation to magenta via the pincolor property.

# ANNOTATION_ORANGE

Availability

3.1.0

6.1.0

9.2.0

ANNOTATION_ORANGE :Number

Color constant used to set a map annotation to orange via the pincolor property.

# ANNOTATION_PURPLE

Availability

6.1.0

3.2.0

9.2.0

ANNOTATION_PURPLE :Number

Color constant used to set a map annotation to purple via the pincolor property.

# ANNOTATION_RED

Availability

3.1.0

3.2.0

9.2.0

ANNOTATION_RED :Number

Color constant used to set a map annotation to red via the pincolor property.

# ANNOTATION_ROSE

Availability

3.1.0

6.1.0

9.2.0

ANNOTATION_ROSE :Number

Color constant used to set a map annotation to rose via the pincolor property.

# ANNOTATION_VIEW_COLLISION_MODE_CIRCLE

Availability

6.3.0

9.2.0

ANNOTATION_VIEW_COLLISION_MODE_CIRCLE :Number

Constant indicating that a circle inscribed in the collision frame rectangle should be used to determine collisions.

# ANNOTATION_VIEW_COLLISION_MODE_RECTANGLE

Availability

6.3.0

ANNOTATION_VIEW_COLLISION_MODE_RECTANGLE :Number

Constant indicating that the full collision frame rectangle should be used for detecting collisions.

# ANNOTATION_VIOLET

Availability

3.1.0

6.1.0

9.2.0

ANNOTATION_VIOLET :Number

Color constant used to set a map annotation to violet via the pincolor property.

# ANNOTATION_YELLOW

Availability

3.1.0

6.1.0

9.2.0

ANNOTATION_YELLOW :Number

Color constant used to set a map annotation to yellow via the pincolor property.

# FEATURE_DISPLAY_PRIORITY_DEFAULT_HIGH

Availability

6.3.0

9.2.0

FEATURE_DISPLAY_PRIORITY_DEFAULT_HIGH :Number

Constant indicating that the item's display priority is high.

An annotation view with this priority is removed from the map when its bounds collide with the bounds of another view with a higher priority. If the priorities of the two views are equal, the view furthest from the center of the map's visible region is hidden first.

# FEATURE_DISPLAY_PRIORITY_DEFAULT_LOW

Availability

6.3.0

9.2.0

FEATURE_DISPLAY_PRIORITY_DEFAULT_LOW :Number

Constant indicating that the item's display priority is low.

# FEATURE_DISPLAY_PRIORITY_REQUIRED

Availability

6.3.0

9.2.0

FEATURE_DISPLAY_PRIORITY_REQUIRED :Number

Constant indicating that the item is required.

An annotation view with this priority does not participate in clustering.

# FEATURE_VISIBILITY_ADAPTIVE

Availability

6.3.0

9.2.0

FEATURE_VISIBILITY_ADAPTIVE :Number

Constant indicating that title text adapts to the current map state.

For markers in the normal state, title text is displayed and subtitle text is hidden. When a marker is selected, the title and subtitle text are hidden when the marker requires a callout.

# FEATURE_VISIBILITY_HIDDEN

Availability

6.3.0

9.2.0

FEATURE_VISIBILITY_HIDDEN :Number

Constant indicating that title text is always hidden.

# FEATURE_VISIBILITY_VISIBLE

Availability

6.3.0

9.2.0

FEATURE_VISIBILITY_VISIBLE :Number

Constant indicating that title text is always visible.

# HYBRID_FLYOVER_TYPE

Availability

3.2.0

9.2.0

HYBRID_FLYOVER_TYPE :Number

Used with mapType to display a satellite flyover image of the area with road and road name information layered on top. Available in iOS 9.0 and later.

# HYBRID_TYPE

Availability

3.1.0

3.2.0

9.2.0

HYBRID_TYPE :Number

Used with mapType to display a satellite image of the area with road and road name information layered on top.

# MUTED_STANDARD_TYPE

Availability

3.1.0

3.2.0

9.2.0

MUTED_STANDARD_TYPE :Number

Used with mapType to display a street map where your data is emphasized over the underlying map details. Available in iOS 11.0 and later. On Android it is mapped to NORMAL_TYPE.

# NORMAL_TYPE

Availability

3.1.0

3.2.0

9.2.0

NORMAL_TYPE :Number

Used with mapType to display a street map that shows the position of all roads and some road names.

# OVERLAY_LEVEL_ABOVE_LABELS

Availability

3.2.0

9.2.0

OVERLAY_LEVEL_ABOVE_LABELS :Number

Place the overlay above roadways but below map labels, shields, or point-of-interest icons. Available in iOS 7.0 and later.

# OVERLAY_LEVEL_ABOVE_ROADS

Availability

3.2.0

9.2.0

OVERLAY_LEVEL_ABOVE_ROADS :Number

Place the overlay above map labels, shields, or point-of-interest icons but below annotations and 3D projections of buildings. Available in iOS 7.0 and later.

# POLYLINE_JOINT_BEVEL

Availability

5.1.0

POLYLINE_JOINT_BEVEL :Number

Flat bevel on the outside of the joint.

# POLYLINE_JOINT_DEFAULT

Availability

5.1.0

POLYLINE_JOINT_DEFAULT :Number

Default: Mitered joint, with fixed pointed extrusion equal to half the stroke width on the outside of the joint.

# POLYLINE_JOINT_ROUND

Availability

5.1.0

POLYLINE_JOINT_ROUND :Number

Rounded on the outside of the joint by an arc of radius equal to half the stroke width, centered at the vertex.

# POLYLINE_PATTERN_DASHED

Availability

6.2.0

9.2.0

POLYLINE_PATTERN_DASHED :Number

Polyline type constant used to display a dashed polyline via pattern property.

# POLYLINE_PATTERN_DOTTED

Availability

6.2.0

9.2.0

POLYLINE_PATTERN_DOTTED :Number

Polyline type constant used to display a dotted polyline via pattern property.

# REASON_API_ANIMATION

Availability

3.1.0

REASON_API_ANIMATION :Number

Used in the regionwillchange event. The animation was initiated in response to the user actions.

# REASON_DEVELOPER_ANIMATION

Availability

3.1.0

REASON_DEVELOPER_ANIMATION :Number

Used in the regionwillchange event. The camera moved in response to a request from the application.

# REASON_GESTURE

Availability

3.1.0

REASON_GESTURE :Number

Used in the regionwillchange event. The camera moved in response to the user gestures on the map.

# SATELLITE_FLYOVER_TYPE

Availability

3.2.0

9.2.0

SATELLITE_FLYOVER_TYPE :Number

Used with mapType to display satellite flyover imagery of the area. Available in iOS 9.0 and later.

# SATELLITE_TYPE

Availability

3.1.0

3.2.0

9.2.0

SATELLITE_TYPE :Number

Used with mapType to display satellite imagery of the area.

# SERVICE_DISABLED

Availability

3.1.0

SERVICE_DISABLED :Number

Code returned from isGooglePlayServicesAvailable. Google Play services has been disabled on this device.

# SERVICE_INVALID

Availability

3.1.0

SERVICE_INVALID :Number

Code returned from isGooglePlayServicesAvailable. The version of Google Play services installed on this device is not authentic.

# SERVICE_MISSING

Availability

3.1.0

SERVICE_MISSING :Number

Code returned from isGooglePlayServicesAvailable. Google Play services is not installed on the device.

# SERVICE_VERSION_UPDATE_REQUIRED

Availability

3.1.0

SERVICE_VERSION_UPDATE_REQUIRED :Number

Code returned from isGooglePlayServicesAvailable. Google Play services is out of date.

# SUCCESS

Availability

3.1.0

SUCCESS :Number

Code returned from isGooglePlayServicesAvailable. Google Play services is available, and the connection is successful.

# TERRAIN_TYPE

Availability

3.1.0

TERRAIN_TYPE :Number

Used with mapType to display the terrain that shows the position of all roads and some road names.