react-native-maps-directions-routes-api

MapViewDirectionsRoutesAPI

A comprehensive React Native component built on top of Google Maps New Routes API to render directions and routes on a map. This package allows you to render routes between an origin and destination with options for alternative routes, intermediate stops, extra markers, and more.

Table of Contents

• Overview
• Installation
• Usage
  • Minimal Setup
  • Intermediate Stops Example
  • Using onReady Callback
  • Displaying Extra Markers
• API Configuration Options
• Custom Markers
• Fit to Coordinates
• MapViewDirectionsRoutesAPI Props
• Further Customization & Examples
• Screenshots
• Troubleshooting
• License

Overview

The MapViewDirectionsRoutesAPI component streamlines the process of fetching routes from the Google Maps Routes API and rendering them on a map. It uses various React hooks to manage state and effects, supports rerendering on prop changes, and includes built-in support for alternative routes and extra markers.

By adding this package to your application, you can easily configure the map rendering behavior with flexible options such as:

• Origin and Destination definition.
• Displaying alternative routes and updating the selected route.
• Inserting intermediate stops.
• Rendering customizable markers.
• Auto-fitting the map view to the displayed markers.

Installation

To install the MapViewDirectionsRoutesAPI package, run the following command in your terminal:

Using NPM

npm install react-native-maps-directions-routes-api

Using YARN

yarn add react-native-maps-directions-routes-api

Ensure you have your Google Maps API key ready for usage. Usage Minimal Setup The minimal setup only requires an origin, destination, and an API key. Import and use the component as follows:

import React from 'react';
import { View } from 'react-native';
import MapViewDirectionsRoutesAPI from 'react-native-maps-directions-routes-api';

const origin = {
 latitude: 6.5244,
 longitude: 3.3792,
 heading: 0,
 customMarker: {
     image: require('./assets/myloc.png'),
     width: 40,
     height: 50,
     pinColor: 'blue',
     title: 'Start',
 },
};

const destination = {
 latitude: 6.6000,
 longitude: 3.3500,
 heading: 0,
 customMarker: {
     image: require('./assets/destino.png'),
     width: 40,
     height: 50,
     pinColor: 'yellow',
     title: 'Destino',
     anchorX: 0.5,
     anchorY: 0.25,
     centerOffsetX: 0,
     centerOffsetY: 0,
 },
};

const MinimalSetupExample = () => (
 <View style={{ flex: 1 }}>
     <MapViewDirectionsRoutesAPI
         origin={origin}
         destination={destination}
         apikey={"GOOGLE_MAPS_APIKEY"}
     />
 </View>
);

export default MinimalSetupExample;

Screenshot: Minimal Setup

Intermediate Stops Example

To add intermediate stops along your route use the intermediates prop. This is ideal for journeys with stops or drop-offs.

import React from 'react';
import { View } from 'react-native';
import MapViewDirectionsRoutesAPI from 'react-native-maps-directions-routes-api';

const origin = { /* Same as above */ };
const destination = { /* Same as above */ };

const intermediateStop = {
 location: {
     latLng: {
         latitude: 6.5500,
         longitude: 3.3600,
         customMarker: {
             image: require('./assets/stop.png'),
             width: 30,
             height: 30,
             pinColor: 'green',
             title: 'Stop',
         },
     },
 },
};

const IntermediateStopsExample = () => (
 <View style={{ flex: 1 }}>
     <MapViewDirectionsRoutesAPI
         origin={origin}
         destination={destination}
         intermediates={[intermediateStop]}
         apikey={"GOOGLE_MAPS_APIKEY"}
     />
 </View>
);

export default IntermediateStopsExample;

Screenshot: Intermediate Setup

Using onReady Callback

The onReady callback is triggered when routes have been successfully fetched and are ready for use. You can access details like the distance, duration, legs, COORDINATES, polyline and more.

import React from 'react';
import { View, Alert } from 'react-native';
import MapViewDirectionsRoutesAPI from 'react-native-maps-directions-routes-api';

const origin = { /* Origin as above */ };
const destination = { /* Destination as above */ };

const onReadyHandler = (routes) => {
 // For instance, route distances and durations can be used to update UI components.
 console.log('Routes ready:', routes);
 Alert.alert('Routes loaded', `Distance: ${routes[0].distance} meters\nDuration: ${routes[0].duration} seconds`);
};

const OnReadyExample = () => (
 <View style={{ flex: 1 }}>
     <MapViewDirectionsRoutesAPI
         origin={origin}
         destination={destination}
         apikey={"GOOGLE_MAPS_APIKEY"}
         onReady={onReadyHandler}
     />
 </View>
);

export default OnReadyExample;

Displaying Extra Markers

You can dynamically display extra markers by tying the extraMarkers prop to a state. This is useful when you want to update markers based on real-time data (e.g., driver locations).

import React, { useState, useEffect } from 'react';
import { View } from 'react-native';
import MapViewDirectionsRoutesAPI from 'react-native-maps-directions-routes-api';

const origin = { /* Origin as above */ };
const destination = { /* Destination as above */ };

const generateExtraMarkers = () =>
 Array.from({ length: 40 }, (_, index) => {
     const isBike = Math.random() < 0.1; // 10% chance
     return {
         latitude: 6.52 + Math.random() * 0.01,
         longitude: 3.38 + Math.random() * 0.001,
         heading: Math.floor(Math.random() * 360),
         customMarker: {
             image: isBike ? require('./assets/bikemap.png') : require('./assets/carmap.png'),
             width: 30,
             height: 40,
             pinColor: isBike ? 'blue' : 'yellow',
             title: isBike ? 'Bike Stop' : 'Car Stop',
             anchorX: 0.5,
             anchorY: 0.25,
             centerOffsetX: 0,
             centerOffsetY: 0,
         },
     };
 });

const ExtraMarkersExample = () => {
 const [drivers, setDrivers] = useState([]);

 useEffect(() => {
     // Simulate fetching/updating extra markers data.
     const markers = generateExtraMarkers();
     setDrivers(markers);
 }, []);

 return (
     <View style={{ flex: 1 }}>
         <MapViewDirectionsRoutesAPI
             origin={origin}
             destination={destination}
             apikey={"GOOGLE_MAPS_APIKEY"}
             extraMarkers={drivers}
         />
     </View>
 );
};

export default ExtraMarkersExample;

Screenshot: Multiple Markers

API Configuration Options Below is a summary of the key configuration props available:

* origin (object, required): The starting point of the route. Must include latitude, longitude, heading (optional), and a customMarker object (optional) (for customizing marker appearance).

* destination (object, required): The end point of the route. Similar structure as origin.

* apikey (string, required): Your Google Maps API key.

* waypoints (array, optional): Additional stop points along the route.

* intermediates (array, optional): Intermediate stops along the route. Each element should have a location property with latLng.

* onStart (function, optional): Callback invoked when route fetching begins.

* onReady (function, optional): Callback invoked when routes are successfully fetched. Provides route details (distance, duration, legs, etc.).

* onError (function, optional): Callback invoked when there is an error fetching the route.

* onSelectRoute (function, optional): Callback when a user selects a particular route.

* mode (string, default: DRIVE): Travel mode such as driving, walking, etc.

* languageCode (string, default: en-US): Language for the API responses.

* resetOnChange (boolean, default: true): Whether to reset state when key properties change.

* optimizeWaypoints (boolean, default: false): Optimize the order of intermediate waypoints.

* computeAlternativeRoutes (boolean, default: false): Whether to compute alternative routes.

* directionsServiceBaseUrl (string, default: https://routes.googleapis.com/directions/v2:computeRoutes): Base URL for the routes API.

* units (string, default: IMPERIAL): Measurement units.

* region (string): The region code.

* precision (string, default: low): Precision of the route.

* timePrecision (string, default: none): Time precision.

* channel (string): Optional channel.

* fieldMask (string): Fields to include in the response.

* routingPreference (string, default: TRAFFIC_AWARE_OPTIMAL): Routing preference.

* polylineQuality (string, default: OVERVIEW): Quality of the encoded polyline.

* polylineEncoding (string, default: ENCODED_POLYLINE): Polyline encoding.

* departureTime (any): Departure time.

* arrivalTime (any): Arrival time.

* routeModifiers (object): Modifiers for the route.

* regionCode (string): Specific region code.

* requestedReferenceRoutes (any): To request specific reference routes.

* extraComputations (array): Additional computations such as FUEL_CONSUMPTION, TOLLS.

* transitPreferences (object): Preferences for transit.

* fitToCoordinates (object): Configuration for auto-fitting the displayed markers on the map view. See the Fit to Coordinates section.

* extraMarkers (array): Additional markers to display on the map.

Custom Markers

Customize markers by providing a customMarker object on each coordinate object. The keys include: -- # image: Local asset to use as the marker. -- # width & height: Dimensions for the marker. -- # pinColor: Color if no custom image is provided. -- # title: Title for the marker. -- # anchorX & anchorY: Anchor points. -- # centerOffsetX & centerOffsetY: Offset adjustments. If customMarker is omitted, the default marker (red) is used.

let sampleOrigin = {
                "latitude": 16.5702678, //sample coordinates
                "longitude": -3.264719, //sample coordinates
                "latitudeDelta": 0.0005, //to control zoom levels
                "longitudeDelta": 0.0005, //to control zoom levels
                heading: 0, //marker direction/angle
                customMarker: {
                    image: require("./assets/destino.png"),
                    width: 40, // image size
                    height: 50, // image size
                    pinColor: 'yellow', // not needed if image is set
                    title: 'Destino',
                    anchorX: 0.25, // play around with these figures to position your customMarker at the exact position
                    anchorY: 0.25, // play around with these figures to position your customMarker at the exact position
                    centerOffsetX: 0.5, // play around with these figures to position your customMarker at the exact position
                    centerOffsetY: 0.2 // play around with these figures to position your customMarker at the exact position
                }

Custom Text Markers

let styleMarker = {
        bubble: { backgroundColor: '#000' },
        arrow: {
            borderColor: '#000',
            borderLeftWidth: 3,
            borderRightWidth: 3,
        },

    }

 let sampleOrigin = {
                "latitude": 16.5702678, //sample coordinates
                "longitude": -3.264719, //sample coordinates
                "latitudeDelta": 0.0005, //to control zoom levels
                "longitudeDelta": 0.0005, //to control zoom levels
                heading: 0, //marker direction/angle
                customMarker: {
                    customText: "13 mins",
                    style: styleMarker // pass in your own styles to change marker properties
                    //omit style to use default text marker green (TOOLTIP STYLE)
                    anchorX: 0.25, 
                    anchorY: 0.25,
                    centerOffsetX: 0.5, 
                    centerOffsetY: 0.2 
                }

style props available

style.container = {}
style.bubble = {}
style.text = {}
style.arrow = {}

const style = {
		container: {
			flexDirection: 'column',
			alignSelf: 'flex-start',
		},
		bubble: {
			flexDirection: 'row',
			alignSelf: 'flex-start',
			backgroundColor: '#38902f', 
			padding: 4,
			borderRadius: 60,
			borderWidth: 0,
		},
		text: {
			color: '#fff',
			fontSize: 12,
		},
		arrow: {
			width: 0,
			height: 0,
			borderLeftWidth: 10,
			borderRightWidth: 10,
			borderTopWidth: 10,
			borderBottomWidth: 15,
			borderStyle: 'solid',
			borderLeftColor: 'transparent',
			borderRightColor: 'transparent',
			borderTopColor: '#38902f',
			borderBottomColor: 'transparent',
			alignSelf: 'center',
			marginTop: -1,
		},
	};

Fit to Coordinates

The component uses the mapRef to automatically adjust the map view via the fitToCoordinates property. This positions the map so that all markers are visible. Adjust the edgePadding and animation settings via the fitToCoordinates prop.

Example configuration:

fitToCoordinates={{
 edgePadding: { top: 90, right: 50, bottom: 100, left: 50 },
 animated: true,
}}

Further Customization & Examples

You can mix and match the configurations as needed to suit your application. For example:

Switching between selected and non-selected routes: Tapping a route polyline updates the selected route using the onPress handler. Dynamically update extra markers: Bind the extraMarkers prop to a state that fetches or updates marker locations in real-time. Refer to the code samples provided in the usage section for practical implementations.

MapViewDirectionsRoutesAPI Props

The MapViewDirectionsRoutesAPI component accepts the following props:

Required Props

• apikey: A string representing the API key for the directions service.
• origin: An object representing the starting point of the route. An object with latitude and longitude properties (e.g. { latitude: 40.7128, longitude: -74.0060 }).
• destination: An object representing the ending point of the route. An object with latitude and longitude properties (e.g. { latitude: 34.0522, longitude: -118.2437 }).
• intermediates: An array of objects representing intermediate points along the route. Objects with latitude and longitude properties (e.g. [{ latitude: 41.8781, longitude: -87.6298 }, { latitude: 39.7392, longitude: -104.9903 }]).

Optional Props

• extraMarkers: An array of objects representing additional markers to display along the route. Objects with latitude and longitude properties (e.g. [{ latitude: 40.7128, longitude: -74.0060 }, { latitude: 34.0522, longitude: -118.2437 }]).

Directions Service Props

• mode: A string representing the mode of transportation (e.g. "DRIVE", "WALK", "TWO_WHEELER", "BICYCLE", "TRANSIT").
• languageCode: A string representing the language code for the directions service (e.g. "en-US").
• resetOnChange: A boolean indicating whether to reset the route when the origin, destination, or intermediates change.
• optimizeWaypoints: A boolean indicating whether to optimize the route by reordering the waypoints.
• directionsServiceBaseUrl: A string representing the base URL for the directions service.
• region: A string representing the region for the directions service (e.g. "US").

Route Display Props

• selectedRouteColor: A string representing the color of the selected route.
• notselectedRouteColor: A string representing the color of the non-selected routes.
• fieldMask: A string representing the field mask for the directions service.

Advanced Props

• computeAlternativeRoutes: A boolean indicating whether to compute alternative routes.
• routingPreference: A string representing the routing preference (e.g. "TRAFFIC_AWARE", "TRAFFIC_UNAWARE", "TRAFFIC_AWARE_OPTIMAL").
• units: A string representing the units for the route distances (e.g. "METRIC", "IMPERIAL").
• polylineQuality: A string representing the quality of the polyline (e.g. "OVERVIEW", "HIGH_QUALITY").
• polylineEncoding: A string representing the encoding of the polyline (e.g. "ENCODED_POLYLINE", "GEO_JSON_LINESTRING").
• requestedReferenceRoutes: A string representing the requested reference routes (e.g. "FUEL_EFFICIENT", "SHORTER_DISTANCE").
• extraComputations: An array of strings representing the extra computations to perform (e.g. ["TOLLS", "FUEL_CONSUMPTION", "TRAFFIC_ON_POLYLINE"]).
• transitPreferences: An object representing the transit preferences (e.g. { allowedTravelModes: ["BUS", "SUBWAY"], routingPreference: "LESS_WALKING" }).
• routeModifiers: An object representing the route modifiers (e.g. { avoidTolls: true, avoidHighways: false, vehicleInfo: { emissionType: "GASOLINE" } }).

Event Handlers

• onStart: A function to call when the directions service starts.
• onReady: A function to call when the directions service is ready.
• onError: A function to call when an error

Screenshots

Below are example screenshots to demonstrate different setups:

Screenshot: Intermediate Setup no custom marker

Screenshot: custom markers Setup with extra markers and compute alternate route

Screenshot: Zoomed custom markers Setup with extra markers and compute alternate route

Screenshot: custom markers Setup NO extra markers + compute alternate route

Screenshot: Minimal Setup + custom marker

Screenshot: Intermediate Setup + custom markers Setup with extra markers and compute alternate route

Troubleshooting

Ensure your API key is valid. A missing or invalid key will cause a warning error. Verify that the origin and destination objects include both latitude and longitude. When dealing with custom markers, confirm that the asset paths are correct and accessible. Use the browser or device console to check logs printed from console.warn for additional debugging information. License Distributed under the MIT License. See LICENSE for more information.

Happy Mapping! Work is in progress PR's are welcome