ti.map

Native Apple Maps and Google Maps for iOS and Android.

5.6.0AndroidSep 23, 2023v5.6.0-androidNot the current release →

Install

A module is a zip you unpack in your project. There is no installer command yet - a ti module install is planned but does not exist today, so the steps below are the ones that work.

1. Download the release archive
- ti.map-android-5.6.0.zipAndroid · 278 KB
2. Unpack it at your project root
```
cd /path/to/your-project
unzip ~/Downloads/ti.map-android-5.6.0.zip
```
The archive already contains the full path, so it lands in place:
- modules/android/ti.map/5.6.0/
3. Add it to tiapp.xml
```
<modules>
  <module platform="android" version="5.6.0">ti.map</module>
</modules>
```
The platform attribute is the packager’s name for the platform, which is iphone for iOS - the same word the archive uses in its own path.
4. Require it from your app
```
const mod = require('ti.map');
```

Manifest

Android 5.6.0

Minimum SDK: 9.0.0
Module API version: 4
Architectures: arm64-v8a, armeabi-v7a, x86, x86_64
Resource package: com.google.android.gms
GUID: f0d8fd44-86d2-4730-b67d-bd454577aeee
Author: Appcelerator
License: Apache Public License v2
Copyright: Copyright (c) 2013-present by Axway, Inc.

API reference

Compiled from tidev/ti.map@5.6.0 (26cae56).

Modules.Map

moduleAndroidiPhoneiPadmacOSsince Android 3.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

Extends Titanium.Module

Add-on Map module

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](api: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.

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 import Map from 'ti.map' API, then make subsequent API calls with the new map object.
```
import Map from 'ti.map';

const 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.

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](api: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 or NSLocationAlwaysUsageDescription key to the iOS plist section of the project's tiapp.xml file.

<ti:app>
    <ios>
        <plist>
            <dict>
                <key>NSLocationAlwaysUsageDescription</key>
                [string](api:Global.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 import Map from 'ti.map' API, then make subsequent API calls with the new map object.
```
import Map from 'ti.map';

const 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.

import Map from 'ti.map';

const window = Ti.UI.createWindow();

const 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.
});

const 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 ]
});

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

mapView.addCircle(circle);
window.add(mapView);

mapView.addEventListener('click', event => {
    Ti.API.info('Clicked ' + event.clicksource + ' on ' + event.latitude + ', ' + event.longitude);
});

windown.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.

import Map from 'ti.map';

const window = Ti.UI.createWindow();
const annotations = [];

for (let 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,
    }));
}

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

mapView.addEventListener('clusterstart', event => {
    Ti.API.info('clustering started!');

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

    mapView.setClusterAnnotation({
        annotation: clusterAnnotation,
        memberAnnotations: event.memberAnnotations
    });
});
window.add(mapView);
window.open();

Search Request (iOS only)

The following example shows the MapKit based search request. The options in search (2nd parameter) are optional, but improve the accuracy of the results.

import Map from 'ti.map';

Map.addEventListener('didUpdateResults', event => {
    console.warn('Found place:');
    console.warn(event)
});

Map.search('Colosseum', {
  region: {
    latitude: 41.890560,
    longitude: 12.494270,
    latitudeDelta: 1,
    longitudeDelta: 1,
  },
  resultTypes: [Map.SEARCH_RESULT_TYPE_POINT_OF_INTEREST, Map.SEARCH_RESULT_TYPE_ADDRESS]
});

Properties 49

ANNOTATION_AZURE

Numbersince iPhone 6.1.0, iPad 6.1.0, Android 3.1.0, macOS 9.2.0read-onlyiOS 9.0+

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

ANNOTATION_BLUE

Numbersince iPhone 6.1.0, iPad 6.1.0, Android 3.1.0read-onlyiOS 9.0+

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

ANNOTATION_CYAN

Numbersince iPhone 6.1.0, iPad 6.1.0, Android 3.1.0, macOS 9.2.0read-onlyiOS 9.0+

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

ANNOTATION_DRAG_STATE_END

Numbersince 3.1.0read-only

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

ANNOTATION_DRAG_STATE_START

Numbersince 3.1.0read-only

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

ANNOTATION_GREEN

Numberread-only

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

ANNOTATION_MAGENTA

Numbersince iPhone 6.1.0, iPad 6.1.0, Android 3.1.0, macOS 9.2.0read-onlyiOS 9.0+

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

ANNOTATION_ORANGE

Numbersince iPhone 6.1.0, iPad 6.1.0, Android 3.1.0, macOS 9.2.0read-onlyiOS 9.0+

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

ANNOTATION_PURPLE

Numbersince iPhone 3.2.0, iPad 3.2.0, Android 6.1.0, macOS 9.2.0read-only

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

ANNOTATION_RED

Numberread-only

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

ANNOTATION_ROSE

Numbersince iPhone 6.1.0, iPad 6.1.0, Android 3.1.0, macOS 9.2.0read-onlyiOS 9.0+

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

ANNOTATION_VIEW_COLLISION_MODE_CIRCLE

NumberiPhoneiPadmacOSsince 6.3.0read-onlyiOS 11.0+

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

ANNOTATION_VIEW_COLLISION_MODE_RECTANGLE

NumberiPhoneiPadsince 6.3.0read-onlyiOS 11.0+

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

ANNOTATION_VIOLET

Numbersince iPhone 6.1.0, iPad 6.1.0, Android 3.1.0, macOS 9.2.0read-onlyiOS 9.0+

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

ANNOTATION_YELLOW

Numbersince iPhone 6.1.0, iPad 6.1.0, Android 3.1.0, macOS 9.2.0read-onlyiOS 9.0+

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

FEATURE_DISPLAY_PRIORITY_DEFAULT_HIGH

NumberiPhoneiPadmacOSsince 6.3.0read-onlyiOS 11.0+

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

NumberiPhoneiPadmacOSsince 6.3.0read-onlyiOS 11.0+

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

FEATURE_DISPLAY_PRIORITY_REQUIRED

NumberiPhoneiPadmacOSsince 6.3.0read-onlyiOS 11.0+

Constant indicating that the item is required.

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

FEATURE_PHYSICAL_FEATURES

NumberAndroidsince 12.0.0read-onlyiOS 16.0+

The option that represents physical map features such as mountain ranges, rivers, and ocean basins.

FEATURE_TERRITORIES

NumberAndroidsince 12.0.0read-onlyiOS 16.0+

The option that represents territorial boundaries such as a national border, a state boundary, or a neighborhood.

FEATURE_TYPE_POINT_OF_INTEREST

NumberAndroidsince 12.0.0read-onlyiOS 16.0+

The option that represents points of interest such as museums, cafes, parks, or schools.

FEATURE_VISIBILITY_ADAPTIVE

NumberiPhoneiPadmacOSsince 6.3.0read-onlyiOS 11.0+

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

NumberiPhoneiPadmacOSsince 6.3.0read-onlyiOS 11.0+

Constant indicating that title text is always hidden.

FEATURE_VISIBILITY_VISIBLE

NumberiPhoneiPadmacOSsince 6.3.0read-onlyiOS 11.0+

Constant indicating that title text is always visible.

HYBRID_FLYOVER_TYPE

NumberiPhoneiPadmacOSread-only

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

Numberread-only

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

MUTED_STANDARD_TYPE

Numberread-onlyiOS 11.0+

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

Numberread-only

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

OVERLAY_LEVEL_ABOVE_LABELS

NumberiPhoneiPadmacOSsince 3.2.0read-only

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

NumberiPhoneiPadmacOSsince 3.2.0read-only

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

NumberAndroidsince 5.1.0read-only

Flat bevel on the outside of the joint.

POLYLINE_JOINT_DEFAULT

NumberAndroidsince 5.1.0read-only

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

POLYLINE_JOINT_ROUND

NumberAndroidsince 5.1.0read-only

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

Numbersince 6.2.0read-only

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

POLYLINE_PATTERN_DOTTED

Numbersince 6.2.0read-only

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

REASON_API_ANIMATION

NumberAndroidread-only

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

REASON_DEVELOPER_ANIMATION

NumberAndroidread-only

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

REASON_GESTURE

NumberAndroidread-only

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

SATELLITE_FLYOVER_TYPE

NumberiPhoneiPadmacOSread-only

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

SATELLITE_TYPE

Numberread-only

Used with mapType to display satellite imagery of the area.

SEARCH_RESULT_TYPE_ADDRESS

Numbersince 12.3.0read-onlyiOS 13.0+

A value that indicates that search results include addresses.

SEARCH_RESULT_TYPE_POINT_OF_INTEREST

Numbersince 12.3.0read-onlyiOS 13.0+

A value that indicates that search results include points of interest.

SEARCH_RESULT_TYPE_QUERY

Numbersince 12.3.0read-onlyiOS 13.0+

A value that indicates that the search completer includes query completions in results.

SERVICE_DISABLED

NumberAndroidread-only

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

SERVICE_INVALID

NumberAndroidread-only

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

SERVICE_MISSING

NumberAndroidread-only

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

SERVICE_VERSION_UPDATE_REQUIRED

NumberAndroidread-only

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

SUCCESS

NumberAndroidread-only

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

TERRAIN_TYPE

NumberAndroidread-only

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

Methods 15

createAnnotation

since Android 3.0.2, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.Annotation

createCamera

since Android 9.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.Camera

createCircle

since Android 4.1.0, iPhone 4.1.0, iPad 4.1.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.Circle

createImageOverlay

since iPhone 7.2.0, iPad 7.2.0, Android 7.4.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.ImageOverlay

createPolygon

since Android 4.1.0, iPhone 4.1.0, iPad 4.1.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.Polygon

createPolyline

since Android 4.1.0, iPhone 4.1.0, iPad 4.1.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.Polyline

createRoute

since Android 3.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.Route

createSnapshotter

iPhoneiPadmacOSsince iPhone 6.0.0, iPad 6.0.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.Snapshotter

createStreetViewPanorama

Androidsince 5.2.0

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

Parameters
Parameters	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 Modules.Map.StreetViewPanorama

createView

since Android 3.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

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

Parameters
Parameters	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 Modules.Map.View

geocodeAddress

iPhoneiPadmacOSsince 12.3.0

Resolve address details using the CLGeocoder to get information (e.g. latitude, longitude, postal code and city) about a given input address.

The result is provided via the callback (second function argument).

Parameters
Parameters	Type	Description
address	String	The address to resolve.
callback	Callback<Object>	Function to be called upon completion (either success with a place or an error).

getLookAroundImage

iPhoneiPadmacOSsince 12.0.0iOS 16.0+

A utility function that you use to create a static image from a LookAround scene.

Parameters
Parameters	Type	Description
callback	Callback<Object>	Function to be called upon completion (either success with an image or an error).
latitude	Number	Latitude of the preferred region.
longitude	Number	Longitude of the preferred region.

isGooglePlayServicesAvailable

Androidsince 3.1.1

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

Returns Number

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

openLookAroundDialog

iPhoneiPadmacOSsince 12.0.0iOS 16.0+

Opens a LookAround window modally.

Parameters
Parameters	Type	Description
latitude	Number	Latitude of the preferred region.
longitude	Number	Longitude of the preferred region.

search

iPhoneiPadmacOSsince 12.3.0

Uses the native MKLocalSearchCompleter class to search places for a given input value.

Please use the didUpdateResults event to get updates for a search completion request via the results field. If the search failed, the results field is empty and an error is provided.

Parameters
Parameters	Type	Description
value	String	The value to search with.
options	SearchCompletionOptions	Additional options to fine-tune the search request. 2 fields region MapRegionTypev2 The region to look for results. Note that only `latitude`, `longitude`, `latitudeDelta` and `longitudeDelta` are currently handled to define the region. resultTypes Array<Number> These options configure the types of search results you want to receive, including points of interest and addresses.

Modules.Map.Annotation

proxyAndroidiPhoneiPadmacOSsince Android 3.0.2, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

Extends Titanium.Proxy

Represents a labeled point of interest on the map that the user can click on.

The Annotation object gives you low-level control over annotations that can be added to map view. An annotation must have its latitude and longitude properties set to appear on a map.

Use the Modules.Map.createAnnotation method to create an annotation. Starting with Alloy 1.4.0, use the <Annotation> Alloy element to define one in XML markup.

An annotation can also have a title, a subtitle, and two inset buttons or views on the left and right side of the title. All of these items are optional.

The controls on the left and right side of the annotation can be specified in one of two ways:

To display an image, set the leftButton or rightButton property to an image URL. (On iOS, you can also use a SystemButton constant to use one of the native system button icons.)
To add another type of view to the annotation, set the leftView or rightView property to a View object.

An annotation has two states: selected and deselected. A deselected annotation is marked by a pin image. When the user selects the pin, the full annotation is displayed.

You can specify a custom image for the map pin by setting the image property.

When the user clicks on an annotation, a click event is generated.

On iOS, You can add a click event listener to a specific annotation, or add a click event listener to the map view to receive click events from all annotations on the map.

On Android, you must add the click event listener to the map view; the annotation itself does not generate these events.

Properties 31

annotationDisplayPriority

NumberiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The display priority of this annotation view.

An annotation view whose priority is set to MKFeatureDisplayPriorityRequired is always visible on the map, whereas other priorities may result in the annotation view being hidden. Use Modules.Map.FEATURE_DISPLAY_PRIORITY_REQUIRED, Modules.Map.FEATURE_DISPLAY_PRIORITY_DEFAULT_HIGH or Modules.Map.FEATURE_DISPLAY_PRIORITY_DEFAULT_LOW.

Accepts

FEATURE_DISPLAY_PRIORITY_DEFAULT_HIGH
FEATURE_DISPLAY_PRIORITY_DEFAULT_LOW
FEATURE_DISPLAY_PRIORITY_REQUIRED

Default: Modules.Map.FEATURE_DISPLAY_PRIORITY_REQUIRE

canShowCallout

BooleaniPhoneiPadmacOS

Defines whether the annotation view is able to display extra information in a callout bubble.

When this is set to true, the annotation view shows the callout bubble on selection. Set this to false to disabled the showing of the callout bubble on selection. This must be set before the annotation is added to the map.

If this value is undefined, the value is treated as explicit true.

centerOffset

Point

Defines a center offset point for the annotation.

By default, the center point of an annotation view is placed at the coordinate point of the associated annotation. Use this property to reposition the annotation view as needed. Positive offset values move the annotation view down and right, while negative values move it up and left.

clusterIdentifier

Stringsince Android 7.4.0, iPhone 6.3.0, iPad 6.3.0, macOS 9.2.0iOS 11.0+

An identifier that determines whether the annotation view participates in clustering.

The default value of this property is null, which prevents the annotation view from being clustered with other annotation views. Setting the property to a non null value it to participate in clustering. Clustering occurs when there is a collision between multiple annotation views with the same identifier on the map surface. The annotation views involved in the collision are removed from the map view and replaced by a clustering annotation view, which displays the title from one of the annotations and provides access to the other annotations.

Default: null

collisionMode

NumberiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The collision mode to use when interpreting the collision frame rectangle.

Use Modules.Map.ANNOTATION_VIEW_COLLISION_MODE_RECTANGLE or Modules.Map.ANNOTATION_VIEW_COLLISION_MODE_CIRCLE.

Accepts

ANNOTATION_VIEW_COLLISION_MODE_CIRCLE
ANNOTATION_VIEW_COLLISION_MODE_RECTANGLE

customView

Titanium.UI.Viewsince 3.1.0

Defines a custom view to be used by the annotation.

Must be set during creation. User interaction is disabled on the view. No view interaction events (click, touchstart etc) will be fired.

draggable

Boolean

Determines whether the pin can be dragged by the user.

When an annotation is draggable, it can be moved by the user by long pressing on the pin.

Default: false

hidden

Booleansince 6.1.0

Determines whether the annotation is hidden or not.

Default: false

image

String | Titanium.Blob

Image to use for the the pin.

Must be set during creation. This is ignored if the customView property is set.

Default: If not specified, a standard map pin image is used.

latitude

Number

Latitude of the annotation, in decimal degrees.

leftButton

Stringsince 3.1.0

Left button image on the annotation, specified as an image URL.

leftView

Titanium.UI.Viewsince 3.1.0

Left view that is displayed on the annotation.

This is ignored if the leftButton property is set.

longitude

Number

Longitude of the annotation, in decimal degrees.

markerAnimatesWhenAdded

BooleaniPhoneiPadmacOSsince 6.3.0iOS 11.0+

Boolean indicating whether the marker animates into position onscreen.

Default: false

markerColor

StringiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The background color of the marker balloon.

The default value of this property is undefined, which applies the standard color that is appropriate for the current map style.

markerGlyphColor

StringiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The color to apply to the glyph text or image.

The default value of this property is undefined, which applies the standard tint color for the current map style.

markerGlyphImage

String | Titanium.BlobiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The image displayed in the marker balloon.

Use this property or the Modules.Map.Annotation.markerGlyphText property to specify the marker balloon content. If you specify both an image and text, the text is displayed. The glyph image is displayed when the marker is in the normal state. Create glyph images as template images so that the glyph tint color can be applied to it. Normally, you set the size of this image to 20 by 20 points on iOS. However, if you do not provide a separate selected image in the Modules.Map.Annotation.markerSelectedGlyphImage property, make the size of this image 40 by 40 points on iOS. MapKit scales images that are larger or smaller than those sizes.

markerGlyphText

StringiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The text to display in the marker balloon.

Use this property or the Modules.Map.Annotation.markerGlyphImage property to specify the marker balloon content. If you specify both an image and text, the text is displayed. The amount of space available for displaying your glyph text is limited. Specify no more than two or three characters for any strings you assign to this property.

markerSelectedGlyphImage

String | Titanium.BlobiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The image to display when the marker is selected.

The glyph image is displayed when the marker is in the selected state. This image is displayed only when the marker is selected. If you specify an image for this property, you should also specify an image in the Modules.Map.Annotation.markerGlyphImage property. Create glyph images as template images so that the glyph tint color can be applied to it. Set the size of this image to 40 by 40 points on iOS. MapKit scales images that are larger or smaller than those sizes.

markerSubtitleVisibility

NumberiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The visibility of the subtitle text rendered below the marker balloon.

The subtitle text is hidden when the marker is not selected. The text is shown when the marker is selected. Use Modules.Map.FEATURE_VISIBILITY_ADAPTIVE, Modules.Map.FEATURE_VISIBILITY_VISIBLE or Modules.Map.FEATURE_VISIBILITY_HIDDEN.

Accepts

FEATURE_VISIBILITY_ADAPTIVE
FEATURE_VISIBILITY_HIDDEN
FEATURE_VISIBILITY_VISIBLE

markerTitleVisibility

NumberiPhoneiPadmacOSsince 6.3.0iOS 11.0+

The visibility of the title text rendered below the marker balloon.

Title text is normally displayed below the marker balloon. Use Modules.Map.FEATURE_VISIBILITY_ADAPTIVE, Modules.Map.FEATURE_VISIBILITY_VISIBLE or Modules.Map.FEATURE_VISIBILITY_HIDDEN.

Accepts

FEATURE_VISIBILITY_ADAPTIVE
FEATURE_VISIBILITY_HIDDEN
FEATURE_VISIBILITY_VISIBLE

pincolor

Number | String

The color of the pin-annotation. Use the ANNOTATION_* constants for pre- defined colors, e.g ANNOTATION_GREEN.

Note for iOS: Apps running iOS 9 and later can also specify a non-constant value, e.g. "blue", "rgb(0, 0, 255 ,1)" or "#0000ff".

Pin color is ignored if a custom pin image is specified using Modules.Map.Annotation.image.

previewContext

Titanium.UI.iOS.PreviewContextiPhoneiPadmacOSsince 6.2.0iOS 9.0+

The preview context used in the 3D-Touch feature "Peek and Pop".

Preview context to present the "Peek and Pop" of a view. Use an configured instance of Titanium.UI.iOS.PreviewContext here.

Note: This property can only be used on devices running iOS9 or later and supporting 3D-Touch. It is ignored on older devices and can manually be checked using Titanium.UI.iOS.forceTouchSupported.

rightButton

Stringsince 3.1.0

Right button image on the annotation, specified as an image URL.

rightView

Titanium.UI.Viewsince 3.1.0

Right view that is displayed on the annotation.

This is ignored if the rightButton property is set.

showAsMarker

BooleaniPhoneiPadmacOSsince 6.3.0iOS 11.0+

Boolean to show an annotation view that displays a balloon-shaped marker at the designated location.

Must be set during creation. This is ignored if the customView property is set. See the example "Map Example With Marker Annotation and Clustering".

Default: false

showInfoWindow

Booleansince 3.2.0

Show or hide the view that is displayed on the annotation when clicked.

When this is false, clicking on the annotation will not center it on the map, but the annotation will still be selected, thus triggering the click event. If the annotation is selected, and the info window is hidden, then the next click will deselect the annotation, thus will NOT show the info window, regardless of the current state of this property.

Default: true

subtitle

String

Secondary title of the annotation view.

subtitleid

Stringsince 3.1.0

Key in the locale file to use for the subtitle property.

title

String

Primary title of the annotation view.

titleid

Stringsince 3.1.0

Key in the locale file to use for the title property.

Methods 2

animate

iPhoneiPadmacOSsince 9.2.0

Animate annotation to new location.

Parameters
Parameters	Type	Description
newLocation	Array<Number>	latitude and longitude where annotation will animate.

rotate

iPhoneiPadmacOSsince 9.2.0

Rotate annotation on its location.

Parameters
Parameters	Type	Description
angle	Number	angle on which annotation will rotate.

Modules.Map.Camera

proxyAndroidiPhoneiPadmacOSsince Android 9.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

Extends Titanium.Proxy

A camera object defines a point above the map's surface from which to view the map. Available in iOS 7.0 and later.

Applying a camera to a map has the effect of giving the map a 3D-like appearance. You can use a camera to rotate the map so that it is oriented to match the user's heading or to apply a pitch angle to tilt the plane of the map.

If the app is run on pre iOS 7, camera functionality will not be available. After creating a Camera object, it can be applied to the map by setting the camera property of the map view.

Use the Modules.Map.createCamera method to create a camera.

If altitude, eyeCoordinate, and centerCoordinate are passed in on creation, a camera will be returned using the specified viewing angle information.

Example:

var camera = Map.createCamera({
    altitude: 15.5,
    centerCoordinates: {
        longitude: 151.276417,
        latitude: -33.891614
    },
    heading: 45,
    pitch: 75
});
mapview.camera = camera;

Properties 5

altitude

Number

The altitude above the ground, measured in meters. On Android these zoom values are: 1: World 5: Landmass/continent 10: City 15: Streets 20: Buildings

centerCoordinate

MapPointType

The coordinate point on which the map should be centered.

eyeCoordinate

MapPointType

The coordinate point at which to place the camera. Only used on creation when altitude and centerCoordinate are also provided. Setting this property at anytime other time will have no effect.

If the value for this parameter is equal to the value in the centerCoordinate parameter, the map is displayed as if the camera is looking straight down. If this point is offset from the centerCoordinate value, the map is displayed with an appropriate heading and pitch angle. Not used on Android.

heading

Number

The heading of the camera (measured in degrees) relative to true north.

The value 0 means that the top edge of the map view corresponds to true north. The value 90 means the top of the map is pointing due east. The value 180 means the top of the map points due south, and so on.

pitch

Number

The viewing angle of the camera, measured in degrees.

A value of 0 results in a camera pointed straight down at the map. Angles greater than 0 result in a camera that is pitched toward the horizon by the specified number of degrees. The value in this property may be clamped to a maximum value to maintain map readability. There is no fixed maximum value, though, because the actual maximum value is dependent on the current altitude of the camera.

Modules.Map.Circle

proxyAndroidiPhoneiPadmacOSsince Android 4.1.0, iPhone 4.1.0, iPad 4.1.0, macOS 9.2.0

Extends Titanium.Proxy

Represents a bounded area on the map.

The Circle object gives you low-level control over circles that can be added to a map view. A circle must have a center property and a radius set to appear on a map.

Use the Modules.Map.createCircle method to create a circle.

Properties 9

blendMode

NumberiPhoneiPadmacOSsince 12.0.0iOS 16.0+

The blend mode to apply to the overlay.

Use one of the Ti.UI.BLEND_MODE_* constants!

center

MapPointType

An object with longitude and latitude values. Can also be an array with longitude (index 0), latitude (index 1) touples.

fillColor

String

Color to use when shading the circle, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: black

opacity

Number

Opacity of this map circle, from 0.0 (transparent) to 1.0 (opaque).

Default: 1.0 (opaque)

radius

Number

The radius of the circle, specified in meters. It should be zero or greater.

strokeColor

String

Color to use for the border of the circle, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: black

strokeWidth

Number

Line width in pixels to use when drawing the circle.

Default: 10

touchEnabled

Booleansince 6.2.0

Determines whether view should receive touch events.

Default: true

zIndex

NumberAndroid

The order (depth) in which to display the circles.

For iOS, the circles are drawn in the order in which they are added.

Modules.Map.ImageOverlay

proxyAndroidiPhoneiPadmacOSsince iPhone 7.2.0, iPad 7.2.0, Android 7.4.0, macOS 9.2.0

Extends Titanium.Proxy

Represents a bounded area on the map that has an image overlay.

The ImageOverlay object gives you low-level control over image overlays that can be added to a map view. An image overlay must have a boundsCoordinate property and a image set to appear on a map.

Use the Modules.Map.createImageOverlay method to create an image overlay.

Properties 2

boundsCoordinate

MapBoundsCoordinateType

An object representing diagonal coordinates (topLeft and bottomRight) on the map.

image

String | Titanium.Blob

The image that is shown as an overlay on the map.

Modules.Map.Polygon

proxyAndroidiPhoneiPadmacOSsince Android 4.1.0, iPhone 4.1.0, iPad 4.1.0, macOS 9.2.0

Extends Titanium.Proxy

Represents a bounded area on the map.

The Polygon object gives you low-level control over polygons that can be added to a map view. A polygon must have its points property set to appear on a map.

Use the Modules.Map.createPolygon method to create a polygon.

Properties 8

bounds

MapRegionTypev2Androidsince 12.3.0

Returns the bounding box of the polygon. Useful to center the region.

fillColor

String

Color to use when shading the polygon, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: black

holes

Array<Array<MapPointType>>

Array of points arrays that define holes in the polygon.

points

Array<MapPointType>

Array of map points making up the polygon. Can also be an array of longitude (index 0), latitude (index 1) touples.

strokeColor

String

Color to use for the border of the polygon, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: black

strokeWidth

Number

Line width in pixels to use when drawing the polygon.

Default: 10

touchEnabled

Booleansince 6.2.0

Determines whether view should receive touch events.

Default: true

zIndex

NumberAndroid

The order (depth) in which to display the polygons.

For iOS, the polygons are drawn in the order in which they are added.

Modules.Map.Polyline

proxyAndroidiPhoneiPadmacOSsince Android 4.1.0, iPhone 4.1.0, iPad 4.1.0, macOS 9.2.0

Extends Titanium.Proxy

Represents a bounded area on the map.

The Polyline object gives you low-level control over polylines that can be added to a map view. A polyline must have its points property set to appear on a map.

Use the Modules.Map.createPolyline method to create a polyline.

Example

var polyline = Map.createPolyline({
    points: [{
            latitude: -33.891614,
            longitude: 151.276417
        },
        [-33.87365, 151.20689]
    ],
    strokeWidth: 3,
    strokeColor: '#f00',
    zIndex: 1
});
mapView.addPolyline(polyline);

Properties 7

jointType

NumberAndroidsince 5.1.0

Defines the shape of corner points.

Defines the shape of corner points. Can be one of the following shapes: Modules.Map.POLYLINE_JOINT_DEFAULT, Modules.Map.POLYLINE_JOINT_ROUND or Modules.Map.POLYLINE_JOINT_BEVEL

Default: Modules.Map.POLYLINE_JOINT_DEFAULT

pattern

Objectsince 6.2.0

Pattern used to draw the polylines.

As per default polylines are drawn with a solid line. You can specify to draw them with a dashed line using Modules.Map.POLYLINE_PATTERN_DASHED or with a dotted line using Modules.Map.POLYLINE_PATTERN_DOTTED.

You can also specify the dimensions to use when you create a dashed or dotted polyline.

For a dashed polyline, you can do something like this:

polyline.setPattern({
    type: TiMap.POLYLINE_PATTERN_DASHED,
    gapLength: 25,
    dashLength: 50
});

or for a dotted polyline, you can do:

polyline.setPattern({
    type: TiMap.POLYLINE_PATTERN_DOTTED,
    gapLength: 25
});

points

Array<MapPointType> | String

Array of map points making up the polyline. Can also be an array of longitude (index 0), latitude (index 1) touples. On Android platform you can use an encoded polyline as string.

strokeColor

String

Color to use for the the polyline, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: black

strokeWidth

Number

Line width in pixels to use when drawing the polyline.

Default: 10

touchEnabled

Booleansince 6.2.0

Determines whether view should receive touch events.

Default: true

zIndex

NumberAndroid

The order (depth) in which to display the polylines.

For iOS, the polylines are drawn in the order in which they are added.

Modules.Map.Route

proxyAndroidiPhoneiPadmacOSsince Android 3.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

Extends Titanium.Proxy

Represents a path between two or more points of interest.

The Route object gives you low-level control over routes that can be added to a map view. A route must have its points property set to appear on a map.

Use the Modules.Map.createRoute method to create a route.

iOS Platform Notes

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

Android Platform Notes

The parameter points accepts additional the route in format encoded polyline.
https://developers.google.com/maps/documentation/utilities/polylinealgorithm

Properties 4

color

String

Color to use when drawing the route, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

iOS Note: Changing the color of an existing route will only work on iOS 7 and later

Default: black

level

NumberiPhoneiPadmacOSsince 3.2.0

The map level at which to place the route. Available in iOS 7.0 and later.

Specify one of the following levels: Modules.Map.OVERLAY_LEVEL_ABOVE_LABELS, Modules.Map.OVERLAY_LEVEL_ABOVE_ROADS.

Default: <Modules.Map.OVERLAY_LEVEL_ABOVE_LABELS>

points

String | Array<MapPointType>

Array of map points making up the route.

width

Number

Line width in pixels to use when drawing the route.

iOS Note: Changing the width of an existing route will only work on iOS 7 and later

Default: 10

Modules.Map.Snapshotter

proxyiPhoneiPadmacOSsince iPhone 6.0.0, iPad 6.0.0, macOS 9.2.0

Extends Titanium.Proxy

Snapshotter is used to allow screen shots to be taken of a specified region or a mapview.

Examples

Taking a simple snapshot

This is a map-example which creates a simple snapshot of the specified map-area.

var MapModule = require('ti.map');

var win = Ti.UI.createWindow({
    backgroundColor: 'white'
});

var Snapshotter = MapModule.createSnapshotter({
    mapType: MapModule.HYBRID_TYPE,
    region: {
        latitude: 37.3382,
        longitude: -121.8863,
        latitudeDelta: 0.4,
        longitudeDelta: 0.4
    },
    size: {
        width: 300, 
        height: 200
    }
});

Snapshotter.takeSnapshot({
    success: function(e) {
        var imageView = Ti.UI.createImageView({
            image: e.image
        });
        win.add(imageView);
    },
    error: function(e) {
        Ti.API.error("The snapshot could not be taken: " + e.error);
    }
});

win.open();

Properties 5

mapType

Number

Map type constant, either Modules.Map.NORMAL_TYPE, Modules.Map.SATELLITE_TYPE, Modules.Map.HYBRID_TYPE, Modules.Map.HYBRID_FLYOVER_TYPE or Modules.Map.SATELLITE_FLYOVER_TYPE.

Default: NORMAL_TYPE

region

MapRegionTypev2

A dictionary specifying the location and zoom level of the map.

showsBuildings

Boolean

Determines whether building will be shown on the map. The mapType property must be set to <Modules.Map.STANDARD_TYPE> for extruded buildings to be displayed.

Default: true

showsPointsOfInterest

Boolean

When this property is set to YES, the map displays icons and labels for restaurants, schools, and other relevant points of interest.

Default: true

size

SnapshotSize

A dictionary specifying the width and height of the snapshot.

Methods 1

takeSnapshot

Takes a snap shot of of the map corresponding to the region property or a snap of the mapView if passed in as a second parameter.

Parameters
Parameters	Type	Description
success	Callback<Titanium.Blob>	Function to be called upon successful completion.
error	Callback	Function to call upon receiving an error.

Returns Titanium.Blob

Modules.Map.StreetViewPanorama

viewAndroidsince 5.2.0

Extends Titanium.UI.View

Provides panoramic 360-degree views from designated roads throughout its coverage area.

Each street view panorama is an image, or set of images, that provides a full 360-degree view from a single location. It provides a viewer that renders the panorama as a sphere with a camera at its center. A window can only contain one street view.

Properties 5

panning

Boolean

Determines whether the user is able to re-orient the camera by dragging.

Default: true

position

StreetViewPosition

A dictionary specifying the position of the street view.

streetNames

Boolean

Determines whether the user is able to see street names displayed.

Default: true

userNavigation

Boolean

Determines whether the user is able to move to a different panorama.

If true, users can use a single tap on navigation links, or double tap the view, to move to a new panorama.

Default: true

zoom

Boolean

Determines whether the user is able to pinch to zoom.

Default: true

Modules.Map.View

viewAndroidiPhoneiPadmacOSsince Android 3.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

Extends Titanium.UI.View

Map view is used for embedding native mapping capabilities as a view in your application.

With native maps, you can control the mapping location, the type of map, the zoom level and you can add custom annotations and routes directly to the map. Once the map view is displayed, the user can pan, zoom and tilt the map using the native control gestures.

Use the Modules.Map.createView method to create a map view.

In Alloy, use the <Module> element with the module attribute set to ti.map and method attribute set to createView to create a map view in XML markup:

<Module module="ti.map" method="createView" />

All latitude and longitude values are specified in decimal degrees. Values in degrees, minutes and seconds (DMS) must be converted to decimal degrees before being passed to the map view.

You can add Annotation objects to the map to mark points of interest. An annotation has two states: selected and deselected. A deselected annotation is marked by a pin image. When selected, the full annotation is displayed, typically including a title and an optional subtitle.

You can add Route objects to the map to create paths between two or more points of interest.

<ti:app>
    <ios>
        <plist>
            <dict>
                <key>NSLocationAlwaysUsageDescription</key>
                [string](api:Global.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>

Properties 29

animate

Boolean

Indicates if changes to the mapping region should be animated.

Setting this to 'false' will not stop the animation from clicking the My Location button, since that is native Android behavior.

Default: false

annotations

Array<Modules.Map.Annotation>

An array of annotations to add to the map.

There is no guarantee that the order of elements in the annotations property will be maintained when creating, adding or deleting annotations from the Ti.Map.View object. If the application depends on the annotations being in a set order, it should keep references to all of the annotations in a separate array.

camera

Modules.Map.Camerasince Android 9.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

The camera used for determining the appearance of the map.

A camera object defines a point above the map's surface from which to view the map. Applying a camera to a map has the effect of giving the map a 3D-like appearance. You can use a camera to rotate the map so that it is oriented to match the user's heading or to apply a pitch angle to tilt the plane of the map.

Assigning a new camera to this property updates the map immediately and without animating the change. If you want to animate changes in camera position, use the animateCamera method instead.

You must not set this property to null. To restore the map to a flat appearance, apply a camera with a pitch angle of 0, which yields a camera looking straight down onto the map surface.

compassEnabled

Booleansince Android 3.2.3, iPhone 6.1.0, iPad 6.1.0, macOS 9.2.0iOS 9.0+

Enable or disables the compass button.

Default: true

enableZoomControls

BooleanAndroid

Enables or disables the built-in zoom controls.

If enabled, the zoom controls are a pair of buttons (one for zooming in, one for zooming out) that appear on the screen. When pressed, they cause the camera to zoom in (or out) by one zoom level. If disabled, the zoom controls are not shown.

Default: true

indoorEnabled

BooleanAndroidsince 7.5.0

A Boolean value indicating whether the indoor mapping is enabled.

This property is used to enabled/disable the indoor mapping feature of Google Maps. Changing the value after the MapView is drawn can cause flickering. You can read more at: Google Indoor Maps

Default: true

liteMode

BooleanAndroidsince 5.0.3

Create a liteMode map version

When the liteMode is switched on the map will be displayed as a bitmap with limited interaction. Please refer to Google developers documentation for more details.

Default: false

mapToolbarEnabled

BooleanAndroidsince 6.1.0

Enable or disables the map toolbar.

Default: true

mapType

Number

Map type constant, either Modules.Map.NORMAL_TYPE, Modules.Map.SATELLITE_TYPE, Modules.Map.TERRAIN_TYPE, Modules.Map.HYBRID_TYPE, Modules.Map.HYBRID_FLYOVER_TYPE or Modules.Map.SATELLITE_FLYOVER_TYPE.

Default: NORMAL_TYPE

maxZoomLevel

NumberAndroidsince 3.2.3read-only

Returns the maximum zoom level available at the current camera position.

Returns the maximum zoom level for the current camera position. This takes into account what map type is currently being used. For example, satellite or terrain may have a lower max zoom level than the base map tiles.

This will only give the correct value after the 'complete' event is fired.

minClusterSize

NumberAndroidsince 5.2.0

Sets the minium size of a cluster.

The minium cluster size is the smallest number of annotations that are merged together and (minClusterSize + 1) is the smallest number that will appear on the cluster.

Default: 4

minZoomLevel

NumberAndroidsince 3.2.3read-only

Returns the minimum zoom level available at the current camera position.

Returns the minimum zoom level. This is the same for every location (unlike the maximum zoom level) but may vary between devices and map sizes.

This will only give the correct value after the 'complete' event is fired.

padding

MapViewPaddingsince 7.4.0

Sets the distance between each edges of the view to the map controls.

The map view controls may be obscured by other elements.

pitchEnabled

BooleaniPhoneiPadmacOSsince 3.2.0

A Boolean value indicating whether the map camera's pitch information is used.

When this property is set to true and a valid camera is associated with the map, the camera's pitch angle is used to tilt the plane of the map. When this property is set to false, the camera's pitch angle is ignored and the map is always displayed as if the user is looking straight down onto it.

region

MapRegionTypev2

A dictionary specifying the location and zoom level of the map.

Default: latitude 0, longitude 0

rotateEnabled

BooleaniPhoneiPadmacOSsince 3.2.0

A Boolean value indicating whether the map camera's heading information is used.

When this property is set to true and a valid camera is associated with the map, the camera's heading angle is used to rotate the plane of the map around its center point. When this property is set to false, the camera's heading angle is ignored and the map is always oriented so that true north is situated at the top of the map view.

scrollEnabled

Booleansince Android 8.0.0, iPhone 7.2.0, iPad 7.2.0, macOS 9.2.0

A Boolean value indicating whether the map can be scrolled by dragging gesture.

When this property is set to true the a map view can be panned or scrolled by dragging the map view.

Default: true

showsBuildings

BooleaniPhoneiPadmacOSsince 3.2.0

A Boolean indicating whether the map displays extruded building information.

When this property is set to true and the camera has a pitch angle greater than zero, the map extrudes buildings so that they extend above the map plane, creating a 3D effect. The mapType property must be set to Modules.Map.NORMAL_TYPE for extruded buildings to be displayed.

Default: true

showsCompass

BooleandeprecatediPhoneiPadmacOSsince 5.2.0iOS 9.0+

Deprecated since 6.1.0

Please use Modules.Map.View.compassEnabled for parity instead.

A Boolean indicating whether the map displays a compass control.

When this property is set to true, the map displays the control that lets users change the heading orientation of the map.

Default: true

showsPointsOfInterest

BooleaniPhoneiPadmacOSsince 3.2.0

A Boolean indicating whether the map displays point-of-interest information.

When this property is set to true, the map displays icons and labels for restaurants, schools, and other relevant points of interest.

Default: true

showsScale

BooleaniPhoneiPadmacOSsince 5.2.0iOS 9.0+

A Boolean indicating whether the map shows scale information.

When this property is set to true, the map displays the scale information.

Default: false

showsTraffic

BooleaniPhoneiPadmacOSsince 5.2.0iOS 9.0+

A Boolean value indicating whether the map displays traffic information.

The mapType property must be set to Modules.Map.NORMAL_TYPE or Modules.Map.HYBRID_TYPE for traffic information to be shown.

Default: false

style

StringAndroidsince 6.1.0

JSON String to style the Map.

This property will change the look (colors, roads, labels) of the map. A valid JSON can be created at Google Maps Styling Wizard

Default: false

traffic

BooleanAndroid

Toggles the traffic layer on or off.

Set to true to display the traffic layer or false to hide it. This is subject to the availability of traffic data.

Default: false

userLocation

Boolean

Boolean indicating if the user's current device location should be shown on the map.

If true, the user's location is marked with a pin, and the My Location button will appear in the top right corner of the screen. Starting in iOS 8, permissions must be added to tiapp.xml. Details in description.

Default: false

userLocationButton

BooleanAndroidsince 3.1.1

Enable or disables the My Location button. If the button is enabled, it is only shown when userLocation is enabled.

If true, the My Location button is enabled.

Default: true

zoom

NumberAndroidsince 7.1.0read-only

Returns the current zoom level from the current camera position.

Returns the current zoom level from the current camera position. Note: This will only return the correct value once the complete event is fired.

zoomEnabled

Booleansince Android 8.0.0, iPhone 7.2.0, iPad 7.2.0, macOS 9.2.0

A Boolean value indicating whether the map can be zoomed by pinching or tapping.

When this property is set to true the a map view can be zoomed by pinching inwards to zoom out and reverse to zoom in. Zooming in can also be accoplished by double-tapping the map view. Zooming out can also be accomplished by two-finger tapping the map view.

Default: true

zOrderOnTop

Boolean

Controls wether the map view's surface is placed on top of its window.

Please refer to zOrderOnTop for more details.

Default: false

Methods 34

addAnnotation

Adds a new annotation to the map.

Parameters
Parameters	Type	Description
annotation	Modules.Map.Annotation	a Modules.Map.Annotation instance.

addAnnotations

Adds one or more new annotations to the map.

Parameters
Parameters	Type	Description
annotations	Array<Modules.Map.Annotation>	Array of Annotation objects

addCircle

Adds a new circle to the map.

Parameters
Parameters	Type	Description
circle	Modules.Map.Circle	a Modules.Map.Circle instance.

addCircles

iPhoneiPadmacOS

Adds one or more new circles to the map.

Parameters
Parameters	Type	Description
circles	Array<Modules.Map.Circle>	Array of Circle objects

addHeatmap

Androidsince 10.1.0

Adds a heatmap to the map.

A heatmap is defined by an array of coordinates.

Parameters
Parameters	Type	Description
coordinates	MapPointType	An array of coordinates

addImageOverlay

since Android 7.4.0, iPhone 7.2.0, iPad 7.2.0, macOS 9.2.0

Adds a new image overlay to the map.

Parameters
Parameters	Type	Description
imageOverlay	Modules.Map.ImageOverlay	A Modules.Map.ImageOverlay instance.

addImageOverlays

since Android 7.4.0, iPhone 7.2.0, iPad 7.2.0, macOS 9.2.0

Adds one or more new image overlays to the map.

Parameters
Parameters	Type	Description
imageOverlays	Array<Modules.Map.ImageOverlay>	Array of ImageOverlay objects

addPolygon

Adds a new polygon to the map.

Parameters
Parameters	Type	Description
polygon	Modules.Map.Polygon	a Modules.Map.Polygon instance.

addPolygons

Adds one or more new polygons to the map.

Parameters
Parameters	Type	Description
polygons	Array<Modules.Map.Polygon>	Array of Polygons objects

addPolyline

Adds a new polylines to the map.

Parameters
Parameters	Type	Description
polygon	Modules.Map.Polyline	a Modules.Map.Polyline instance.

addPolylines

Adds one or more new polylines to the map.

Parameters
Parameters	Type	Description
polylines	Array<Modules.Map.Polyline>	Array of Polyline objects

addRoute

Adds a route to the map.

Parameters
Parameters	Type	Description
route	Modules.Map.Route	Modules.Map.Route

animateCamera

since Android 9.1.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

Changes the camera used for determining the map's viewing parameters and animates the change.

Parameters
Parameters	Type	Description
animationParams	CameraAnimationParams	Properties for controlling the camera animation. The property `camera` is required. 3 fields camera Modules.Map.Annotation Modules.Map.Camera to be animated to. curve Number Animation curve or easing function to apply to the animation. duration Number The amount of time (in milliseconds) that the animation will last.
callback	Callback<Object>	A method that will be called when the camera animation completes. Optionally, the completion of camera animations can be captured by listening for a `regionchanged` event with `animated` set to true.

containsCoordinate

since 10.1.0

Validated whether or not a given coordinate is currently visible in the map rect.

Parameters
Parameters	Type	Description
coordinate	MapPointType	The `latitude` and `longitude` pair represented by an Object.

Returns Boolean

Returns true if given coordinate is within the displayed map view.

deselectAnnotation

Deselects the specified annotation, so the main annotation is hidden and only a pin image is shown.

Parameters
Parameters	Type	Description
annotation	String \| Modules.Map.Annotation	Annotation to deselect, identified by an annotation title or a Modules.Map.Annotation reference.

removeAllAnnotations

Removes all annotations from the map.

removeAllCircles

Remove all circles from the map.

removeAllImageOverlays

since Android 7.4.0, iPhone 7.2.0, iPad 7.2.0, macOS 9.2.0

Remove all image overlays from the map.

removeAllPolygons

Remove all polygons from the map.

removeAllPolylines

Remove all polylines from the map.

removeAnnotation

Removes an existing annotation from the map.

Parameters
Parameters	Type	Description
annotation	String \| Modules.Map.Annotation	Annotation to remove, identified by an annotation title or a Modules.Map.Annotation reference.

removeAnnotations

Removes one or more existing annotations from the map.

Annotations can be identified by title or by a Modules.Map.Annotation reference.

Parameters
Parameters	Type	Description
annotations	Array<String> \| Array<Modules.Map.Annotation>	Array of annotations to remove.

removeCircle

Remove a circle from the map.

Parameters
Parameters	Type	Description
circle	Modules.Map.Circle	An Circle object

removeImageOverlay

since Android 7.4.0, iPhone 7.2.0, iPad 7.2.0, macOS 9.2.0

Remove an image overlay from the map.

Parameters
Parameters	Type	Description
imageOverlay	Modules.Map.ImageOverlay	An ImageOverlay object

removePolygon

Remove a polygon from the map.

Parameters
Parameters	Type	Description
polygon	Modules.Map.Polygon	A Polygon object

removePolyline

Remove a polyline from the map.

Parameters
Parameters	Type	Description
polyline	Modules.Map.Polyline	An Polyline object

removeRoute

Remove a previously added route.

Parameters
Parameters	Type	Description
route	Modules.Map.Route	An instance of Modules.Map.Route

selectAnnotation

Selects the annotation, showing the full annotation.

Parameters
Parameters	Type	Description
annotation	String \| Modules.Map.Annotation	Annotation to show, identified by an annotation title or a Modules.Map.Annotation reference.

setClusterAnnotation

since Android 7.4.0, iPhone 6.3.0, iPad 6.3.0, macOS 9.2.0iOS 11.0+

Set new cluster annotation for the clustered annotation.

This method should be called inside the clusterstart event. See the example "Map Example With Marker Annotation and Clustering".

Parameters
Parameters	Type	Description
clusterAnnotationParam	ClusterAnnotationParams	Properties for creating cluster annotation. 2 fields annotation Modules.Map.Annotation Modules.Map.Annotation instance, which you want to show as clustered annotation. There is no need to provide latitude and longitude as clustered annotation decides its location itself. memberAnnotations Array<Modules.Map.Annotation> Array of Modules.Map.Annotation, which is recieved in event 'clusteringstarted' as memberAnnotations.

setLocation

since 3.1.0

Sets the map location and zoom level.

The location is set using a simple dictionary object, described in MapLocationTypeV2. If latitudeDelta and longitudeDelta are set, these specified parameters bound the area of interest, which is centered and displayed at the greatest possible zoom level. This method can only be called after the map completes loading. Before that, use region to set the map location. For example:

myMapView.setLocation({
  latitude: 37.337681,
  longitude: -122.038193,
  animate: true,
  latitudeDelta: 0.04,
  longitudeDelta: 0.04
});

Parameters
Parameters	Type	Description
location	MapLocationTypeV2	Dictionary specifying the location and the zoom level for the map. 5 fields animate Boolean Set to `true` to animate the move to the new location. latitude Number Latitude value for the center point of the map, in decimal degrees. latitudeDelta Number The amount of north-to-south distance displayed on the map, measured in decimal degrees. longitude Number Longitude value for the center point of the map, in decimal degrees. longitudeDelta Number The amount of east-to-west distance displayed on the map, measured in decimal degrees.

setMapType

Sets the type of map (satellite, normal, or terrain).

Parameters
Parameters	Type	Description
mapType	Number	Map type constant, either Modules.Map.NORMAL_TYPE, Modules.Map.SATELLITE_TYPE, Modules.Map.TERRAIN_TYPE, Modules.Map.HYBRID_TYPE, Modules.Map.HYBRID_FLYOVER_TYPE or Modules.Map.SATELLITE_FLYOVER_TYPE.

showAnnotations

since Android 8.0.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0

Sets the visible region so that the map displays the specified annotations. If no array is passed annotations on the map will be shown. The default padding of 20px is applied and can be changed by using the Modules.Map.View.padding property.

Parameters
Parameters	Type	Description
annotations?	Array<Modules.Map.Annotation>	An array of Modules.Map.Annotation to display.

snapshot

Androidsince 3.2.3

Takes a snapshot of the map

Takes a snapshot of the current map and returns the image via onsnapshotready event.

zoom

since 3.1.0

Zooms in or out of the map.

Zooms in or out by specifying a relative zoom level. A positive value increases the current zoom level and a negative value decreases the zoom level.

Each increase in zoom level increases the magnification by a factor of two.

Parameters
Parameters	Type	Description
level	Number	Relative zoom level (positive to zoom in, negative to zoom out).

Events 12

click

Fired when the user selects or deselects an annotation, a polygon, a polyline or a circle.

Note that the click event is not fired every time the user clicks on the map. It is fired in two circumstances:

The user clicks on the annotation. This will select the annotation.
The user deselects an annotation either by clicking on the map or another annotation.
The user clicks on a polygon, a polyline or a circle.

Note that only one annotation can be selected at any given time.

The click event includes a value, clicksource, which describes the part of the annotation that was clicked. The clicksource can be one of pin, infoWindow, leftButton or rightButton on iOS and pin, title, subtitle, leftPane, rightPane, infoWindow or null on Android. If the user deselects an annotation by clicking on the pin, clicksource is pin. If the user deselects the annotation by clicking elsewhere in the map view, clicksource is map.

For polygon, polyline or circle, The click event includes the following values. clicksource is a string describing the shape type. map is the map view instance. latitude and longtitude is the corresponding coordinates on the map where the user clicked in the shape.

Event properties
Event properties	Type	Description
title	String	Title of the annotation.
subtitle	String	Subtitle of the annotation.
map	Modules.Map.View	The map view instance.
clicksource	String	Source of the click event. Can be one of `pin`, `leftPane`, `rightPane`, `infoWindow` or `null`. If it's a shape, it can be one of `polygon`, `polyline`, or `circle`. On Android, this also applies for `title` and `subtitle`.
annotation	Modules.Map.Annotation	Annotation source object.
latitude	Number	Latitude of the clicked annotation or the point clicked in the polygon, polyline and circle.
longitude	Number	Longitude of the clicked annotation or the point clicked in the polygon, polyline and circle.
deselected	Boolean	Will show if the annotation was selected (false) or deselected (true)

clusterstart

iPhoneiPadmacOSsince 6.3.0

Fired when a collision between annotations occures.

Event properties
Event properties	Type	Description
memberAnnotations	Array<Modules.Map.Annotation>	Array of annotations participating in clustering.
map	Modules.Map.View	This map view.

complete

Fired when the map completes loading.

longclick

since 3.2.0

Fired when the user makes a long-press gesture on the map.

A long press is generated by touching and holding on the touch screen.

The event occurs before the finger/button is lifted.

The longclick event returns longitude and latitude of the point on the ground that was pressed.

Event properties
Event properties	Type	Description
latitude	Number	latitude of the point on the ground that was pressed.
longitude	Number	longitude of the point on the ground that was pressed.
map	Modules.Map.View	The map view instance.

mapclick

since 6.2.0

Fired when the user clicks on the map

The mapclick event is fired when the user clicks on the map and returns the longitude/latitude of that position.

Event properties
Event properties	Type	Description
map	Modules.Map.View	The map view instance.
latitude	Number	Latitude of the clicked position.
longitude	Number	Longitude of the clicked position.

onsnapshotready

Androidsince 3.2.3

Fired when the snapshot is ready after snapshot is invoked.

Event properties
Event properties	Type	Description
snapshot	Titanium.Blob	snapshot of the current map

pinchangedragstate

since 3.1.0

Fired when the user interacts with a draggable annotation.

Event properties
Event properties	Type	Description
annotation	Modules.Map.Annotation	Annotation being dragged.
map	Modules.Map.View	This map view.
title	String	Annotation title.
newState	Number	New drag state for the annotation, one of ANNOTATION_DRAG_STATE_NONE, ANNOTATION_DRAG_STATE_START, ANNOTATION_DRAG_STATE_DRAG, ANNOTATION_DRAG_STATE_CANCEL or ANNOTATION_DRAG_STATE_END.
oldState	Number	Previous drag state for the annotation, one of ANNOTATION_DRAG_STATE_NONE, ANNOTATION_DRAG_STATE_START, ANNOTATION_DRAG_STATE_DRAG, ANNOTATION_DRAG_STATE_CANCEL or ANNOTATION_DRAG_STATE_END.

poiclick

iPhoneiPadmacOSsince 12.0.0

Fired when the user selects a Point of Interest (e.g. restaurant or hotel).

Make sure to use the <Modules.Map.View.selectableMapFeatures> property to define annotations tha should be selectable. Available in iOS 16+

Event properties
Event properties	Type	Description
name	String	The descriptive name associated with the map item.
featureType	Number	The type of map feature this annotation represents. See the Apple docs for all possible enum values.
pointOfInterestCategory	Number	The point-of-interest category for the map item. See the Apple docs for all possible enum values.
phoneNumber	String	The phone number associated with a business at the specified location.
url	String	The URL associated with the specified location.
place	Object	The placemark object containing the location information.
latitude	Number	Latitude of the annotation that was selected.
longitude	Number	Longitude of the annotation that was selected.

poideselect

iPhoneiPadmacOSsince 12.2.0

Fired when the user deselects a Point of Interest (e.g. restaurant or hotel).

regionchanged

Fired when the mapping region finished changing.

Event properties
Event properties	Type	Description
longitude	Number	Longitude value for the center point of the map, in decimal degrees.
latitude	Number	Latitude value for the center point of the map, in decimal degrees.
longitudeDelta	Number	The amount of east-to-west distance displayed on the map, measured in decimal degrees.
latitudeDelta	Number	The amount of north-to-south distance displayed on the map, measured in decimal degrees.
animated	Boolean	The regionchanged event was caused by an `animation`, such as a animating the camera.

regionwillchange

since Android 6.2.0, iPhone 6.0.0, iPad 6.0.0, macOS 9.2.0

Fired when the mapping region will change.

Event properties
Event properties	Type	Description
longitude	Number	Longitude value for the center point of the map, in decimal degrees.
latitude	Number	Latitude value for the center point of the map, in decimal degrees.
longitudeDelta	Number	The amount of east-to-west distance displayed on the map, measured in decimal degrees.
latitudeDelta	Number	The amount of north-to-south distance displayed on the map, measured in decimal degrees.
animated	Boolean	The regionwillchange event was caused by an `animation`, such as a animating the camera.
reason	Number	The reason for the camera change, either Modules.Map.REASON_API_ANIMATION, Modules.Map.REASON_DEVELOPER_ANIMATION or Modules.Map.REASON_GESTURE.

userLocation

since 7.3.0

Fired when the user changes on the map.

When the user location is available or changes at the map it will fire the event.

Event properties
Event properties	Type	Description
latitude	Number	Latitude of the point on the ground that was pressed.
longitude	Number	Longitude of the point on the ground that was pressed.

MapPointType

pseudoAndroidiPhoneiPadmacOS

An object representing a point on the map.

Properties 2

latitude

Number

Latitude value of the map point, in decimal degrees.

longitude

Number

Longitude value of the map point, in decimal degrees.

MapRegionTypev2

pseudoAndroidiPhoneiPadmacOS

Simple object representing a map location and zoom level.

Properties 8

bearing

NumberAndroidsince 3.2.3

The direction in which a vertical line on the map points, measured in degrees clockwise from north.

For more details, see Google Docs. Cannot be used in conjunction with longitudeDelta or latitudeDelta

Pass one or more of Modules.Map.FEATURE_TERRITORIES, Modules.Map.FEATURE_PHYSICAL_FEATURES or Modules.Map.FEATURE_TYPE_POINT_OF_INTEREST as an array to make these features selectable.

tilt

NumberAndroidsince 3.2.3

The camera's position on an arc between directly over the map's center position and the surface of the Earth, measured in degrees from the nadir.

For more details, see Google Docs. Cannot be used in conjunction with longitudeDelta or latitudeDelta

zoomLevel

NumberAndroidsince 5.0.2

The zoom level of the map.

For more details, see Google Docs. Cannot be used in conjunction with longitudeDelta or latitudeDelta

Install

1. Download the release archive

2. Unpack it at your project root

3. Add it to tiapp.xml

4. Require it from your app

Manifest

Android 5.6.0

API reference

Modules.Map

Requirements

Getting Started

iOS

Requirements

Getting Started

Breaking Changes

Examples

Basic Map Example

Alloy XML Markup

Map Clustering (iOS 11+)

Search Request (iOS only)

Properties 49

Methods 15

Modules.Map.Annotation

Properties 31

Methods 2

Modules.Map.Camera

Example:

Properties 5

Modules.Map.Circle

Properties 9

Modules.Map.ImageOverlay

Properties 2

Modules.Map.Polygon

Properties 8

3. Add it to `tiapp.xml`