Cordova GoogleMaps plugin for iOS and Android (version 2.0)

This plugin is a thin wrapper for Google Maps Android API and Google Maps SDK for iOS.

Both PhoneGap and Apache Cordova are supported.

---

Quick install

Stable version(npm)

$> cordova plugin add cordova-plugin-googlemaps \
    --variable API_KEY_FOR_ANDROID="..." \
    --variable API_KEY_FOR_IOS="..."

Develop version (current multiple_maps branch)

$> cordova plugin add https://github.com/mapsplugin/cordova-plugin-googlemaps#multiple_maps \
    --variable API_KEY_FOR_ANDROID="..." \
    --variable API_KEY_FOR_IOS="..."

If you re-install the plugin, please always remove the plugin first, then remove the SDK

$> cordova plugin rm cordova-plugin-googlemaps

$> cordova plugin rm com.googlemaps.ios

$> cordova plugin add cordova-plugin-googlemaps \
    --variable API_KEY_FOR_ANDROID="..." \
    --variable API_KEY_FOR_IOS="..." \
    --no-fetch

Configuration

You can also configure the following variables to customize the iOS location plist entries

• LOCATION_WHEN_IN_USE_DESCRIPTION for NSLocationWhenInUseUsageDescription (defaults to "Show your location on the map")
• LOCATION_ALWAYS_USAGE_DESCRIPTION for NSLocationAlwaysUsageDescription (defaults t "Trace your location on the map")

Example using the Cordova CLI

$> cordova plugin rm cordova-plugin-googlemaps

$> cordova plugin rm com.googlemaps.ios

$> cordova plugin add cordova-plugin-googlemaps \
    --variable API_KEY_FOR_ANDROID="..." \
    --variable API_KEY_FOR_IOS="..." \
    --variable LOCATION_WHEN_IN_USE_DESCRIPTION="My custom when in use message" \
    --variable LOCATION_ALWAYS_USAGE_DESCRIPTION="My custom always usage message"

Example using config.xml

<plugin name="cordova-plugin-googlemaps" spec="2.0.0">
    <variable name="API_KEY_FOR_ANDROID" value="YOUR_ANDROID_API_KEY_IS_HERE" />
    <variable name="API_KEY_FOR_IOS" value="YOUR_IOS_API_KEY_IS_HERE" />
    <variable name="LOCATION_WHEN_IN_USE_DESCRIPTION" value="My custom when in use message" />
    <variable name="LOCATION_ALWAYS_USAGE_DESCRIPTION" value="My custom always usage message" />
</plugin>

Quick demo

<script type="text/javascript">
var map;
document.addEventListener("deviceready", function() {
  var div = document.getElementById("map_canvas");

  // Initialize the map view
  map = plugin.google.maps.Map.getMap(div);

  // Wait until the map is ready status.
  map.addEventListener(plugin.google.maps.event.MAP_READY, onMapReady);
}, false);

function onMapReady() {
  var button = document.getElementById("button");
  button.addEventListener("click", onButtonClick);
}

function onButtonClick() {

  // Move to the position with animation
  map.animateCamera({
    target: {lat: 37.422359, lng: -122.084344},
    zoom: 17,
    tilt: 60,
    bearing: 140,
    duration: 5000
  }, function() {

    // Add a maker
    map.addMarker({
      position: {lat: 37.422359, lng: -122.084344},
      title: "Welecome to \n" +
             "Cordova GoogleMaps plugin for iOS and Android",
      snippet: "This plugin is awesome!",
      animation: plugin.google.maps.Animation.BOUNCE
    }, function(marker) {

      // Show the info window
      marker.showInfoWindow();

      // Catch the click event
      marker.on(plugin.google.maps.event.INFO_CLICK, function() {

        // To do something...
        alert("Hello world!");

      });
    });
  });
}
</script>

---

Documentation

All documentations are here!!

Quick examples

Map	var options = { camera: { position: {lat: ..., lng: ...}, zoom: 19 } }; var map = plugin.google.maps.Map.getMap(mapDiv, options)
Marker	map.addMarker({ position: {lat: ..., lng: ...}, title: "Hello Cordova Google Maps for iOS and Android", snippet: "This plugin is awesome!" }, function(marker) { ... })
MarkerCluster	map.addMarkerCluster({ //maxZoomLevel: 5, boundsDraw: true, markers: dummyData(), icons: [ {min: 2, max: 100, url: "./img/blue.png", anchor: {x: 16, y: 16}}, {min: 100, max: 1000, url: "./img/yellow.png", anchor: {x: 16, y: 16}}, {min: 1000, max: 2000, url: "./img/purple.png", anchor: {x: 24, y: 24}}, {min: 2000, url: "./img/red.png",anchor: {x: 32,y: 32}} ] }, function(markerCluster) { ... });
HtmlInfoWindow	var html = "<img src='./House-icon.png' width='64' height='64' >" + "<br>" + "This is an example"; htmlInfoWindow.setContent(html); htmlInfoWindow.open(marker);
Circle	map.addCircle({ 'center': {lat: ..., lng: ...}, 'radius': 300, 'strokeColor' : '#AA00FF', 'strokeWidth': 5, 'fillColor' : '#880000' }, function(circle) { ... });
Polyline	map.addPolyline({ points: AIR_PORTS, 'color' : '#AA00FF', 'width': 10, 'geodesic': true }, function(polyline) { ... });
Polygon	map.addPolygon({ 'points': GORYOKAKU_POINTS, 'strokeColor' : '#AA00FF', 'strokeWidth': 5, 'fillColor' : '#880000' }, function(polygon) { ... });
GroundOverlay	map.addPolygon({ 'points': GORYOKAKU_POINTS, 'strokeColor' : '#AA00FF', 'strokeWidth': 5, 'fillColor' : '#880000' }, function(polygon) { ... });
TileOverlay	map.addTileOverlay({ debug: true, opacity: 0.75, getTile: function(x, y, zoom) { return "../images/map-for-free/" + zoom + "_" + x + "-" + y + ".gif" } }, function(tileOverlay) { ... });
Geocoder	plugin.google.maps.Geocoder.geocode({ // US Capital cities "address": [ "Montgomery, AL, USA", ... "Cheyenne, Wyoming, USA" ] }, function(mvcArray) { ... });

---

How different between Google Maps JavaScript API v3?

This plugin displays the map view of native(Java and Objective-C) features, which is faster than Google Maps JavaScript API v3.

And the native map view works even if the device is offline.

This plugin provides the features of the native map view to JS developers.

You can write your code similar like the Google Maps JavaScript API v3.

Features compare table

	Google Maps JavaScript API v3	Cordova-Plugin-GoogleMaps
Rendering system	JavaScript + HTML	JavaScript + Native APIs
Offline map	Not possible	Possible (only you displayed area)
3D View	Not possible	Possible
Platform	All browsers	Android and iOS app only
Tile image	Bitmap	Vector

Class compare table

Google Maps JavaScript API v3	Cordova-Plugin-GoogleMaps
google.maps.Map	Map
google.maps.Marker	Marker
google.maps.InfoWindow	Default InfoWindow, and HtmlInfoWindow
google.maps.Circle	Circle
google.maps.Rectangle	Polygon
google.maps.Polyline	Polyline
google.maps.Polygon	Polygon
google.maps.GroundOverlay	GroundOverlay
google.maps.ImageMapType	TileOverlay
google.maps.MVCObject	BaseClass
google.maps.MVCArray	BaseArrayClass
google.maps.Geocoder	plugin.google.maps.geocoder
google.maps.geometry.spherical	plugin.google.maps.geometry.spherical
google.maps.geometry.encoding	plugin.google.maps.geometry.encoding
(not available)	MarkerCluster
google.maps.KmlLayer	KMLLayer (v1.4.5 is available)
google.maps.StreetView	(not available)
google.maps.Data	(not available)
google.maps.DirectionsService	(not available)
google.maps.DistanceMatrixService	(not available)
google.maps.FusionTablesLayer	(not available)
google.maps.TransitLayer	map.setTrafficEnabled()
google.maps.places.*	(not available)
google.maps.visualization.*	(not available)

How does this plugin work?

This plugin generates native map views, and put them under the browser.

The map views are not an HTML element. It means they are not kind of <div> or something. But you can specify the size, position of the map view using <div>.

This plugin changes the background as transparent of your app. Then the plugin detects your finger tap position which is for: native map or html element.

The benefit of this plugin is able to detect which HTML elements are over the map or not automatically.

In the below image, you tap on the header div, which is over the map view. This plugin detects your tap is for the header div or the map view, then pass the mouse event.

It means you can use the native Google Maps views similar like HTML element.

---

Buy me a beer

I have been spend tons of time for this plugin project, but even though the plugin is still FREE!!.

I appreciate if you donate some amount to help this project from this button.

The donated amount is used for buying testing machine (such as iPhone, Android) or new software.