Google Maps

@nativescript/google-maps

NativeScript binding for the Google Maps Android & iOS API.

Prerequisites

To use the Google Maps API, you must register your app in the Google API Console and obtain an API key.

Installation

ns plugin add @nativescript/google-maps

Config

Android

Modify the AndroidManifest to include the new meta tag along with your API key, the manifest is located in App_Resources/Android/AndroidManifest.xml

<application
  android:name="com.tns.NativeScriptApplication"
  android:allowBackup="true"
  android:icon="@mipmap/ic_launcher"
  android:label="@string/app_name"
  android:theme="@style/AppTheme"
  android:hardwareAccelerated="true"
>
  <meta-data android:name="com.google.android.geo.API_KEY" android:value="yourKey" />
</application>

iOS

Modify the Info.plist to include the new meta tag along with your API key, the manifest is located in App_Resources/iOS/Info.plist

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>TNSGoogleMapsAPIKey</key>
    <string>yourKey</string>
  </dict>
</plist>

Usage

Core

Ensure you’ve included xmlns:map="@nativescript/google-maps" on the Page element

 
<map:MapView
  lat="{{lat}}"
  lng="{{lng}}"
  zoom="{{zoom}}"
  bearing="{{bearing}}"
  tilt="{{tilt}}"
  ready="{{onReady}}"
  mapTap="{{onTap}}"
  mapLongPress="{{onLongPress}}"
  markerTap="{{onMarkerTap}}"
/>

Angular

  • TypeScript

  • HTML

import { GoogleMapsModule } from '@nativescript/google-maps/angular';

@NgModule({
    imports: [
      GoogleMapsModule
    ],
    declarations: [
      AppComponent
    ],
    bootstrap: [AppComponent]
})
<MapView
  (ready)="onReady($event)"
  (mapTap)="onTap($event)"
  (mapLongPress)="onLongPress($event)"
  (markerTap)="onMarkerTap($event)"
>
</MapView>

Vue

  • TypeScript

  • HTML

import Vue from 'nativescript-vue'
import GoogleMaps from '@nativescript/google-maps/vue'

Vue.use(GoogleMaps)
<MapView
  @ready="onReady"
  @mapTap="onTap"
  @mapLongPress="onLongPress"
  @markerTap="onMarkerTap"
/>

MapView API

Properties

The following properties are available for adjusting the camera view on initialization:

Property type Description and Data Type

lat

number

Latitude, in degrees

lng

number

Longitude, in degrees

zoom

number

Zoom level (described here)

bearing

number

Bearing, in degrees

tilt

number

Tilt, in degrees

Events

The following events are available:

Event Description

ready

Fires when the MapView is ready for use see GoogleMap

mapTap

Fires when a coordinate is tapped on the map

mapLongPress

Fires when a coordinate is long-pressed on the map

markerTap

Fires when a marker is tapped

myLocationTap

Fires when 'My Location' is tapped

myLocationButtonTap

Fires when the 'My Location' button is tapped

markerDragStart

Fires when a marker begins dragging

markerDragging

Fires while a marker is being dragged

markerDragEnd

Fires when a marker ends dragging

tileRenderingStart

Fires when tile rendering begins

tileRenderingEnd

Fires when tile rendering ends

cameraPosition

Fires when the map viewport state changes, camera states include idle | start | moving

circle

Fires when a circle is tapped

polygon

Fires when a polygon is tapped

polyline

Fires when a polyline is tapped

poi

Fires when a POI is tapped

groundOverlay

Fires when a ground overlay is tapped

infoWindowTap

Fires when a marker’s info window is tapped

infoWindowLongPress

Fires when a marker’s info window is long-pressed

infoWindowClose

Fires when a marker’s info window is closed

markerInfoContents

markerInfoWindow

activeBuilding

Fires when a building is focused on

activeLevel

Fires when the level of the focused building changes

Google Map

Instance

A GoogleMap instance is required from the map view to access many of the mapping features. The GoogleMaps instance is available from the MapViews ready event:

function onReady(event: MapReadyEvent) {
  const map: GoogleMap = event.map
}

API

Properties

Property Type Description

mapStyle

Style[]

See Map Styles

mapType

MapType

See Map Type

buildingsEnabled

boolean

Enables Buildings

maxZoomLevel

number

Maximum level of zoom

minZoomLevel

number

Minimum level of zoom

myLocationEnabled

boolean

Enables "My Location"

trafficEnabled

boolean

Enables traffic

uiSettings

IUISettings

See UI Settings

cameraPosition

CameraPosition

See Camera Position

projection

Projection

See Projection

native

any

See Native Map Object

Functions

Func Description

addMarker(marker: MarkerOptions): Marker

Adds a marker to the map

removeMarker(marker: Marker)

Removes a marker from the map

addTileOverlay(options: TileOverlayOptions): TileOverlay

Adds a tile overlay to the map

removeTileOverlay(overlay: TileOverlay)

Removes a tile overlay from the map

addCircle(circle: CircleOptions): Circle

Adds a circle to the map

removeCircle(circle: Circle)

Removes a circle from the map

addGroundOverlay(options: GroundOverlayOptions): GroundOverlay

Adds a ground overlay to the map

removeGroundOverlay(groundOverlay: GroundOverlay)

Removes a ground overlay from the map

addPolygon(options: PolygonOptions): Polygon

Adds a polygon to the map

removePolygon(polygon: Polygon)

Removes a polygon from the map

addPolyline(options: PolylineOptions): Polyline

Adds a polyline to the map

removePolyline(polyline: Polyline#polyline)

Removes a polyline from the map

animateCamera(update: CameraUpdate)

Animates camera to a new position

snapshot(): Promise<ImageSource>

Returns a platform specific image of the maps current viewport

clear()

Clears all objects added to the map

Native Map Object

GoogleMap gives you access to the platforms native map objects native| android| ios

Consult the appropriate SDK reference on how to use it: iOS | Android

Camera Position

The maps current camera position can be read from the GoogleMaps object cameraPosition.

Property Type Description

target

Coordinate

The camera target is the location of the center of the map, specified as lat and lng.

bearing

number

The direction in which the camera points measured in degrees clockwise from north.

tilt

number

The viewing angle of the camera measured in degrees

zoom

number

The scale of the map

Controlling The Camera

To programatically update the camera position you can call animateCamera from the GoogleMap object, like so:

import { CameraPosition } from '@nativescript/google-maps'

googleMap.animateCamera(
  CameraPosition.fromCoordinates(
    {
      lat: -32.1234,
      lng: 125.1234
    },
    googleMap.cameraPosition.zoom
  )
)

CameraPosition provides multiple methods to create a target CameraUpdate position.

Method Description

fromCoordinate(coordinate: Coordinate, zoom: number)

Returns a CameraUpdate from a single coordinate

fromCoordinates(coordinates: Coordinate[], padding: number)

Returns a CameraUpdate from multiple coordinates

fromCoordinates(coordinates: Coordinate[], width: number, height: number, padding: number)

Returns a CameraUpdate from multiple coordinates with specified height, width and padding

fromCameraPosition(position: CameraPosition)

Returns a CameraUpdate from a CameraPosition

zoomIn()

Returns a CameraUpdate that has zoomed in

zoomOut()

Returns a CameraUpdate that has zoomed out

zoomTo(value: number)

Returns a CameraUpdate that has zoomed to a value

zoomBy(amount: number, point?: { x: number; y: number })

Returns a CameraUpdate that has zoomed and panned

scrollBy(x: number, y: number)

Returns a panned CameraUpdate

UI Settings

You can adjust the maps UI settings from the GoogleMap object by configuring the following properties of uiSettings:

Property Type Description

compassEnabled

boolean

Whether the compass is enabled or not

indoorLevelPickerEnabled

boolean

Whether the indoor level picker is enabled or not

mapToolbarEnabled

boolean

Whether the map toolbar is enabled or not

myLocationButtonEnabled

boolean

Whether the 'My Location' button is enabled or not

rotateGesturesEnabled

boolean

Whether the compass is enabled or not

scrollGesturesEnabled

boolean

Whether map scroll gestures are enabled or not

tiltGesturesEnabled

boolean

Whether map tilt gestures are enabled or not

zoomGesturesEnabled

boolean

Whether map zoom gestures are enabled or not

zoomControlsEnabled

boolean

Whether map zoom controls are enabled or not

scrollGesturesEnabledDuringRotateOrZoom

boolean

Whether scroll gestures are enabled while rotating or zooming

Map Type

The Google Maps API offers five types of maps:

Type Description

None

No tiles. The map is rendered as an empty grid with no tiles loaded.

Normal

Typical road map. Shows roads, some features built by humans, and important natural features such as rivers. Road and feature labels are also visible.

Satellite

Satellite photograph data. Road and feature labels are not visible.

Terrain

Topographic data. The map includes colors, contour lines and labels, and perspective shading. Some roads and labels are also visible.

Hybrid

Satellite photograph data with road maps added. Road and feature labels are also visible.

To set the type of a map, adjust the GoogleMap objects mapType. You can pass in one map type from the MapType Enum. For example:

import { GoogleMap, MapType } from '@nativescript/google-map';

...
map: GoogleMap;
map.mapType = MapType.Hybrid;

Map Styles

You can customize the presentation of the standard Google Map styles, changing the visual display of features like roads, parks, businesses, and other points of interest. This means that you can emphasize particular components of the map or make the map look good with your app.

Styling works only on the normal map type. Styling does not affect indoor maps.

To style your map, use a JSON file generated by the Google Maps APIs Styling Wizard. In addition to changing the appearance of features, you can also hide features completely.

[
  {
    "featureType": "all",
    "stylers": [{ "color": "#C0C0C0" }]
  },
  {
    "featureType": "road.arterial",
    "elementType": "geometry",
    "stylers": [{ "color": "#CCFFFF" }]
  },
  {
    "featureType": "landscape",
    "elementType": "labels",
    "stylers": [{ "visibility": "off" }]
  }
]

To apply a custom style to your map you can set the mapStyle property on your GoogleMap object, like so:

import { GoogleMap } from '@nativescript/google-map';

...
map: GoogleMap;
map.mapStyle = [{
	"featureType": "landscape",
	"elementType": "labels",
	"stylers": [
		{ "visibility": "off" }
	]
}];

Markers

Adding Markers

You can create markers using the GoogleMaps object addMarker function by passing in the specified Marker Options.

function addMarker(map: GoogleMap, markerOptions: MarkerOptions): Marker {
  return map.addMarker(markerOptions)
}

Marker Options

Property Type Description

position

Coordinate

The position of the marker, specified as lat and lng

color

string | Color

Color of the marker, shades are unavailable.

title

string

A string that’s displayed in the info window when the user taps the marker

snippet

string

Additional text that’s displayed below the title

icon

Image

A image that’s displayed in place of the default marker image

draggable

boolean

Set to true if you want to allow the user to move the marker. Defaults to false

flat

boolean

By default, markers are oriented against the screen, and will not rotate or tilt with the camera. Flat markers are oriented against the surface of the earth, and will rotate and tilt with the camera

rotation

boolean

The orientation of the marker, specified in degrees clockwise

anchorU

number

Horizontal icon offset from the marker position

anchorV

number

Vertical icon offset from the marker position

userData

any

Additional information assigned to the marker

zIndex

number

Z-index of the marker

Removing Markers

You can remove a marker using the GoogleMaps removeMarker function, like so:

function removeMarker(map: GoogleMap, marker: Marker) {
  map.removeMarker(marker)
}

Circle

Adding Circles

You can create Circles using the GoogleMaps object addCircle function by passing in the specified Circle Options.

function addCircle(map: GoogleMap, circleOptions: CircleOptions): Circle {
  return map.addCircle(circleOptions)
}

Circle Options

Property Type

center

Coordinate

fillColor

Color | string

radius

number

strokeColor

Color | string

strokePattern

PatternItem & Partial<NativeObject>[]

strokeWidth

number

tappable

boolean

visible

boolean

zIndex

number

userData

{ [key: string]: any }

Removing Circles

You can remove a Circle using the GoogleMaps removeCircle function, like so:

function removeCircle(map: GoogleMap, circle: Circle) {
  map.removeCircle(circle)
}

Polygons

Adding Polygons

You can create polygons using the GoogleMaps object addPolygon function by passing in the specified Polygon Options.

function addPolygon(map: GoogleMap, polygonOptions: PolygonOptions): Polygon {
  return map.addPolygon(polygonOptions)
}

Polygon Options

Property Type

points

Coordinate[]

holes

Coordinate[]

tappable

boolean

strokeWidth

number

strokeColor

Color | string

fillColor

Color | string

strokePattern

PatternItem & Partial<NativeObject>[]

zIndex

number

geodesic

boolean

strokeJointType

JointType

visible

boolean

userData

{ [key: string]: any }

Removing Polygons

You can remove a Polygon using the GoogleMaps removePolygon function, like so:

function removePolygon(map: GoogleMap, polygon: Polygon) {
  map.removePolygon(polygon)
}

Polyline

Adding Polylines

You can create Polylines using the GoogleMaps object addPolyline function by passing in the specified Polyline Options.

function addPolyline(map: GoogleMap, polylineOptions: PolylineOptions): Polyline {
  return map.addPolyline(polylineOptions)
}

Polyline Options

Property Type

width

number

points

Coordinate[]

tappable

boolean

geodesic

boolean

visible

boolean

zIndex

number

jointType

JointType

pattern

PatternItem & Partial<NativeObject>[]

color

Color | string

startCap

Cap & Partial<NativeObject>

endCap

Cap & Partial<NativeObject>

userData

{ [key: string]: any }

Removing Polylines

You can remove a Polyline using the GoogleMaps removePolyline function, like so:

function removePolyline(map: GoogleMap, polyline: Polyline) {
  map.removePolyline(polyline)
}

Ground Overlays

Adding Ground Overlays

You can create Ground Overlays using the GoogleMaps object addGroundOverlay function by passing in the specified GroundOverlay Options.

function addGroundOverlay(
  map: GoogleMap,
  groundOverlayOptions: GroundOverlayOptions
): GroundOverlay {
  return map.addGroundOverlay(groundOverlayOptions)
}

GroundOverlay Options

Property Type

zIndex

number

visible

boolean

transparency

number

position

Coordinate

bounds

CoordinateBounds

tappable

boolean

bearing

number

image

ImageSource

userData

any

width

number

height

number

anchorU

number

anchorV

number

Removing Ground Overlays

You can remove a GroundOverlay using the GoogleMaps removeGroundOverlay function, like so:

function removeGroundOverlay(map: GoogleMap, groundOverlay: GroundOverlay) {
  map.removeGroundOverlay(groundOverlay)
}

Tile Overlays

Adding Tile Overlays

You can create Tile Overlays using the GoogleMaps object addTileOverlay function by passing in the specified TileOverlay Options.

function addTileOverlay(
  map: GoogleMap,
  tileOverlayOptions: TileOverlayOptions
): TileOverlay {
  return map.addTileOverlay(tileOverlayOptions)
}

TileOverlay Options

Property Type

fadeIn

boolean

transparency

number

visible

boolean

tileProvider

TileProvider & Partial<NativeObject>

zIndex

number

Removing Tile Overlays

You can remove a TileOverlay using the GoogleMaps removeTileOverlay function, like so:

function removeTileOverlay(map: GoogleMap, tileOverlay: TileOverlay) {
  map.removeTileOverlay(tileOverlay)
}