Cordova GoogleMaps plugin for iOS and Android (version 2.3.3)

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@2.3.3 \
    --variable API_KEY_FOR_ANDROID="..." \
    --variable API_KEY_FOR_IOS="..."

(Optional variables)
  // [Android]
  //    The Google Play Services SDK version
  //    You need to specify the same version number with all other plugins.
  //    Check out the latest version here.
  //    https://developers.google.com/android/guides/releases
  PLAY_SERVICES_VERSION="15.0.1" (for Android)

  // [Android]
  //    This plugin requires the Android support library v4.
  //    The minimum version is 24.1.0
  //    Check out the latest version here.
  //    https://developer.android.com/topic/libraries/support-library/revisions.html
  ANDROID_SUPPORT_V4_VERSION="27.1.1" (for Android)

  // [iOS]
  //    These variable messages are displayed when application requests
  //    end-user location.
  LOCATION_WHEN_IN_USE_DESCRIPTION="(your custom message)"  (for iOS)
  LOCATION_ALWAYS_USAGE_DESCRIPTION="(your custom message)"  (for iOS)

PhoneGap Build settings

<widget ...>
  <plugin name="cordova-plugin-googlemaps" spec="^2.3.3">
    <variable name="API_KEY_FOR_ANDROID" value="(api key)" />
    <variable name="API_KEY_FOR_IOS" value="(api key)" />

    <!-- these are optional settings -->
    <variable name="PLAY_SERVICES_VERSION" value="15.0.1" />
    <variable name="ANDROID_SUPPORT_V4_VERSION" value="27.1.1" />
    <variable name="LOCATION_WHEN_IN_USE_DESCRIPTION" value="(your custom message)" />
    <variable name="LOCATION_ALWAYS_USAGE_DESCRIPTION" value="(your custom message)" />
  </plugin>

  <!--
    You need to specify cli-7.1.0 or greater version.
    https://build.phonegap.com/current-support
  -->
  <preference name="phonegap-version" value="cli-8.0.0" />
</widget>

Release Notes

v2.3.3
- Comment out debug code (only this)
v2.3.2
- Update: reduce the number of times of DOM tree parse process. (= improve performance.)
- Fix: map.getMyLocation() and LocationService.getMyLocation() do not work.
- Fix: can not execute any methods of the marker obtained from MARKER_CLICK event of marker cluster
- Fix: can not touch Div element which is moved with css transition over map view.
- Fix: internal event does not work well with ionic 1 project.
v2.3.1
- Fix: incompatible with @ionic-native/google-maps
v2.3.0
- New feature: StreetView
- A callback is no longer required for the most part.
- Promise is supported instead of callback

Quick demo

document.addEventListener("deviceready", function() {
  var div = document.getElementById("map_canvas");

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


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

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

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

    // 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!");

    });
  }
}, false);

Documentation

All documentations are here!!

https://github.com/mapsplugin/cordova-plugin-googlemaps-doc/blob/master/v2.3.0/README.md

Quick examples

Map	var options = { camera: { target: {lat: ..., lng: ...}, zoom: 19 } }; var map = plugin.google.maps.Map.getMap(mapDiv, options)
Marker	var marker = map.addMarker({ position: {lat: ..., lng: ...}, title: "Hello Cordova Google Maps for iOS and Android", snippet: "This plugin is awesome!" })
MarkerCluster	var 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}} ] });
HtmlInfoWindow	var html = "<img src='./House-icon.png' width='64' height='64' >" + "<br>" + "This is an example"; htmlInfoWindow.setContent(html); htmlInfoWindow.open(marker);
Circle	var circle = map.addCircle({ 'center': {lat: ..., lng: ...}, 'radius': 300, 'strokeColor' : '#AA00FF', 'strokeWidth': 5, 'fillColor' : '#880000' });
Polyline	var polyline = map.addPolyline({ points: AIR_PORTS, 'color' : '#AA00FF', 'width': 10, 'geodesic': true });
Polygon	var polygon = map.addPolygon({ 'points': GORYOKAKU_POINTS, 'strokeColor' : '#AA00FF', 'strokeWidth': 5, 'fillColor' : '#880000' });
GroundOverlay	var groundOverlay = map.addGroundOverlay({ 'url': "./newark_nj_1922.jpg", 'bounds': [ {"lat": 40.712216, "lng": -74.22655}, {"lat": 40.773941, "lng": -74.12544} ], 'opacity': 0.5 });
TileOverlay	var tileOverlay = map.addTileOverlay({ debug: true, opacity: 0.75, getTile: function(x, y, zoom) { return "../images/map-for-free/" + zoom + "_" + x + "-" + y + ".gif" } });
KmlOverlay	map.addKmlOverlay({ 'url': 'polygon.kml' }, function(kmlOverlay) { ... });
Geocoder	plugin.google.maps.Geocoder.geocode({ // US Capital cities "address": [ "Montgomery, AL, USA", ... "Cheyenne, Wyoming, USA" ] }, function(mvcArray) { ... });
poly utility	var GORYOKAKU_POINTS = [ {lat: 41.79883, lng: 140.75675}, ... {lat: 41.79883, lng: 140.75673} ] var contain = plugin.google.maps.geometry.poly.containsLocation( position, GORYOKAKU_POINTS); marker.setIcon(contain ? "blue" : "red");
encode utility	var GORYOKAKU_POINTS = [ {lat: 41.79883, lng: 140.75675}, ... {lat: 41.79883, lng: 140.75673} ] var encodedPath = plugin.google.maps.geometry. encoding.encodePath(GORYOKAKU_POINTS);
spherical utility	var heading = plugin.google.maps.geometry.spherical.computeHeading( markerA.getPosition(), markerB.getPosition()); label.innerText = "heading : " + heading.toFixed(0) + "°";
Location service	plugin.google.maps.LocationService.getMyLocation(function(result) { alert(["Your current location:\n", "latitude:" + location.latLng.lat.toFixed(3), "longitude:" + location.latLng.lng.toFixed(3), "speed:" + location.speed, "time:" + location.time, "bearing:" + location.bearing].join("\n")); });
StreetView	var div = document.getElementById("pano_canvas1"); var panorama = plugin.google.maps.StreetView.getPanorama(div, { camera: { target: {lat: 42.345573, lng: -71.098326} } });

What is the difference between this plugin and Google Maps JavaScript API v3?

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

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

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

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

Feature comparison table

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

Class comparison 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
google.maps.geometry.poly	plugin.google.maps.geometry.poly
(not available)	MarkerCluster
google.maps.KmlLayer	KMLLayer
(not available)	LocationService
google.maps.StreetView	StreetView ✨
google.maps.Data	(not available)
google.maps.DirectionsService	(not available)
google.maps.DistanceMatrixService	(not available)
google.maps.FusionTablesLayer	(not available)
google.maps.TransitLayer	(not available)
google.maps.places.*	(not available)
google.maps.visualization.*	(not available)

How does this plugin work?

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

The map views are not HTML elements. This means that they are not a <div> or anything HTML related. But you can specify the size and position of the map view using its containing <div>.

This plugin changes the background to transparent in your application. Then the plugin detects your touch position, which is either meant for the native map or an html element (which can be on top of your map, or anywhere else on the screen).

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

For instance, in the image below, say you tap on the header div (which is over the map view). The plugin will detect whether your tap is for the header div or for the map view and then pass the touch event appropriately.

This means you can use the native Google Maps views similar to HTML elements.

Official Communities

Google+ : (managed by @wf9a5m75)

https://plus.google.com/communities/117427728522929652853
Gitter : (managed by @Hirbod)

https://gitter.im/nightstomp/cordova-plugin-googlemaps

Buy us a beer

Thank you for supporting our activities.

All donations are used for purchasing testing devices (both iOS and Android) and/or new software.

Buy us a beer (with bitcoin)

Thank you for supporting us via bitcoin.

3LyVAfANZwcitEEnFbsHup3mDJfuqp8QFb

max-in-bc/cordova-plugin-googlemaps