Cómo usar Google Maps en una aplicación React

Índice de contenidos

1. Introducción
2. Conseguir tu API Key
3. Instalación de React Google Maps
4. Componentes
   • 4.1. Api Provider
   • 4.2. Map
   • 4.3. Map Control
   • 4.4. Info Window
   • 4.5. Marker
   • 4.6. Advanced Marker
   • 4.7. Pin
5. Hooks
6. Conclusión
7. Glosario
8. Referencias bibliográficas

1. Introducción

¿Alguna vez te ha surgido la idea de desarrollar un proyecto en el que quisieras incluir un mapa de Google Maps, pero pensaste que resultaba demasiado complejo y tedioso?

Pues, en este artículo veremos una breve introducción que te proporcionará los conocimientos necesarios para renderizar un mapa y añadir marcadores gracias a la librería react-google-maps. ¡Vamos a ello!

2. Conseguir tu API Key

El uso de la API de Google Maps no es gratuito; sin embargo, Google ofrece un crédito mensual gratuito, que resulta más que suficiente para proyectos pequeños y pruebas.

Lo primero que necesitaremos para interactuar con la API de Google Maps es obtener nuestra API Key. Para ello, accede a Google Cloud Platform con tu cuenta de Google.

Haz clic en el botón para acceder a la Consola:

A continuación, selecciona tu proyecto o crea uno nuevo si aún no tienes ninguno:

Una vez dentro de tu proyecto, despliega el menú lateral y haz clic en "APIs y servicios". Luego, presiona el botón que dice "HABILITAR APIS Y SERVICIOS". Busca la opción "Maps JavaScript API", la cual te permitirá interactuar con tus mapas, estilizarlos y visualizar datos en ellos:

Haz clic en la API y actívala:

Aparecerá una modal con tu API Key; asegúrate de copiarla:

Por último, haz clic en el botón para acceder a Google Maps Platform. Se abrirá otra modal para restringir el uso de la API Key. En este caso, no aplicaremos restricciones, pero te recomendamos hacerlo en proyectos personales para mejorar la seguridad y evitar consumos indeseados de la cuota.

3. Instalación de React Google Maps

Una vez que tienes la API Key, ya puedes comenzar a usar la API de Google Maps. Para ello, crea un proyecto de React con Vite e instala la librería react-google-maps. Si no sabes cómo crear un proyecto de React con Vite, te dejo este enlace a un artículo que escribí recientemente explicando el proceso.

Una vez creado el proyecto, instala la librería ejecutando el siguiente comando:

npm install @vis.gl/react-google-maps

O, si prefieres usar Yarn:

yarn add @vis.gl/react-google-maps

4. Componentes

En este apartado, veremos los principales componentes de React que nos proporciona la librería.

4.1 API Provider

El componente <APIProvider> es el encargado de cargar el API JavaScript de Google Maps.
Provee el contexto necesario mediante APIProviderContext para el correcto funcionamiento de otros componentes y hooks de la librería.
Normalmente, se utiliza una única instancia de <APIProvider>, la cual se puede ubicar en cualquier nivel de la aplicación.
Este componente solo requiere el API Key generado anteriormente para funcionar:

import React from 'react';
import { APIProvider } from '@vis.gl/react-google-maps';

export const App = () => (
  <APIProvider apiKey={'API_KEY'}>
    {/* otros componentes */}
  </APIProvider>
);

Además, dispone de otras propiedades opcionales para configurar el idioma, la región, etc.
Se recomienda establecer las diferentes keys como variables de entorno y asegurarse de que no sean accesibles públicamente.

4.2 Map

El componente <Map> es fundamental, ya que se encarga de renderizar el mapa de Google.
Para que el mapa se renderice correctamente, debe estar contenido dentro del <APIProvider>, además de que el elemento contenedor debe tener asignadas propiedades de altura y anchura.
Entre las propiedades más relevantes se encuentran:

• zoom / defaultZoom:
  Define el nivel de acercamiento del mapa. Según la documentación se recomiendan los siguientes valores:

  • 1: El mundo entero
  • 5: Masas continentales
  • 10: Ciudades
  • 15: Calles
  • 20: Estructuras

• center / defaultCenter:
  Indica el punto geográfico en el que se centra el mapa, mediante un objeto con los valores de latitud y longitud:

  { lat: number, lng: number }

Otra propiedad destacada es mapId, que permite adaptar el mapa a tus necesidades mediante un Map ID, el cual se crea desde Google Maps Platform.

Para ello, accede a la pestaña de Administración de mapas y haz clic en el botón para crear un nuevo Map ID:

Continúa con la creación del Map ID mediante el formulario:

Una vez creado, copia el Map ID y añádelo a tu componente <Map>

import {APIProvider, Map} from '@vis.gl/react-google-maps';

export const App = () => (
  <APIProvider apiKey={API_KEY}>
    <Map zoom={10} center={{lat: 53.54992, lng: 10.00678}} mapId={MAP_ID} style={{width: '100vw', height: '100vh'}} />
  </APIProvider>
);

Una vez que dispones del Map ID, podrás personalizar el mapa desde el apartado de Diseños de Mapa:

4.3 Map Control

El componente <MapControl> te permite renderizar controles interactivos dentro de la instancia del mapa. Estos controles facilitan acciones como hacer zoom, desplazar el mapa, entre otras funcionalidades.

Posee una propiedad principal, position, que define la ubicación en la que se posicionará el control dentro del mapa.

import { APIProvider, ControlPosition, Map, MapControl } from '@vis.gl/react-google-maps';

export const App = () => (
  <APIProvider apiKey={API_KEY}>
    <Map 
      zoom={10} 
      center={{ lat: 53.54992, lng: 10.00678 }} 
      mapId={MAP_ID} 
      style={{ width: '100vw', height: '100vh' }}
    >
      <MapControl position={ControlPosition.TOP_RIGHT}>
        {/* Contenido del control */}
      </MapControl>
    </Map>
  </APIProvider>
);

Info Window

El componente <InfoWindow> se utiliza para mostrar una pequeña ventana informativa en el mapa, similar a una modal, que ofrece detalles sobre ubicaciones específicas. Estas ventanas pueden ubicarse en cualquier posición del mapa o incluso anclarse a un componente <Marker>, que veremos más adelante.

Este componente puede renderizar cualquier elemento JSX como hijo, aunque presenta algunas limitaciones en cuanto a la personalización de estilos.

Algunas de sus propiedades más importantes son:

• position: Objeto que define la latitud y longitud para posicionar la ventana.
• anchor: Especifica el Marker al que se ancla la ventana.
• zIndex: Define el orden de superposición con respecto a otros elementos.
• pixelOffset: Indica la separación en píxeles entre la ventana y el punto de referencia del mapa.
• disableAutoPan: Activa o desactiva el desplazamiento automático del mapa para asegurar que la ventana sea completamente visible al abrirse.
• shouldFocus: Indica si el foco debe trasladarse a la ventana al abrirse.
• headerContent: Define el contenido que se mostrará en la cabecera de la ventana.
• headerDisabled: Desactiva la sección de cabecera y oculta el botón de cierre.

Además, el componente recibe dos eventos:

• onClose: Se dispara cuando se cierra el InfoWindow.
• onCloseClick: Se dispara al hacer clic en el botón de cierre.

import {APIProvider, InforWindow, Map, MapControl} from '@vis.gl/react-google-maps';

export const App = () => (
  <APIProvider apiKey={API_KEY}>
    <Map zoom={10} center={{lat: 53.54992, lng: 10.00678}} mapId={MAP_ID} style={{width: '100vw', height: '100vh'}}>
        <InfoWindow position={{lat: 67.54599, lng: 88.03233}}>
           ...
        </InfoWindow>
    </Map>
  </APIProvider>
);

Marker

El componente <Marker> se encarga de renderizar un marcador en una posición específica del mapa. Para visualizar un marcador, solo es necesario pasarle la propiedad position con la latitud y longitud de la ubicación.
Las propiedades del componente <Marker> amplían las opciones disponibles en la interfaz del Marker del API JavaScript de Google Maps. Puedes consultarlo aquí. Además, permite agregar diferentes event listeners.

import { APIProvider, Map, MapControl, Marker } from '@vis.gl/react-google-maps';

export const App = () => (
  <APIProvider apiKey={API_KEY}>
    <Map 
      zoom={10} 
      center={{ lat: 53.54992, lng: 10.00678 }} 
      mapId={MAP_ID} 
      style={{ width: '100vw', height: '100vh' }}
    >
      <Marker position={{ lat: 67.54599, lng: 88.03233 }} />
    </Map>
  </APIProvider>
);

Advanced Marker

Por defecto, el componente <AdvancedMarker> muestra el típico pin rojo de Google Maps. Sin embargo, permite personalizar el marcador, ya sea mediante el componente <Pin> o creando uno propio con HTML/CSS, lo que posibilita el uso de imágenes, SVGs, animaciones, entre otros.

Este componente soporta la mayoría de las opciones definidas en AdvancedMarkerElementOptions.

Otras propiedades interesantes son:

• title: Proporciona un texto accesible al marcador.
• collisionBehavior: Define cómo se comportan los marcadores cuando colisionan entre sí.

Además, se puede utilizar el hook useAdvancedMarkerRef, que facilita la conexión entre el marcador y el InfoWindow.

En el siguiente ejemplo, sustituimos el marcador por defecto por el emoji 📍:

import { AdvancedMarker, APIProvider, Map, MapControl } from '@vis.gl/react-google-maps';

export const App = () => (
  <APIProvider apiKey={API_KEY}>
    <Map 
      zoom={10} 
      center={{ lat: 53.54992, lng: 10.00678 }} 
      mapId={MAP_ID} 
      style={{ width: '100vw', height: '100vh' }}
    >
      <AdvancedMarker position={{ lat: 67.54599, lng: 88.03233 }}>
        📍
      </AdvancedMarker>
    </Map>
  </APIProvider>
);

Pin

El componente <Pin> se utiliza para personalizar la apariencia del marcador por defecto.
Las propiedades de este componente siguen la interfaz del API JavaScript de Google Maps, definida en PinElementOptions.

import { AdvancedMarker, APIProvider, Pin, Map, MapControl } from '@vis.gl/react-google-maps';

export const App = () => (
  <APIProvider apiKey={API_KEY}>
    <Map 
      zoom={10} 
      center={{ lat: 53.54992, lng: 10.00678 }} 
      mapId={MAP_ID} 
      style={{ width: '100vw', height: '100vh' }}
    >
      <AdvancedMarker position={{ lat: 67.54599, lng: 88.03233 }}>
        <Pin background={'#FBBC04'} glyphColor={'#000'} borderColor={'#000'} />
      </AdvancedMarker>
    </Map>
  </APIProvider>
);

Hooks

La librería react-google-maps también proporciona varios hooks que facilitan la interacción con los mapas. Algunos de ellos son:

• useMap: Permite acceder a la instancia del mapa dentro del APIProvider.
• useMapsLibrary: Facilita el acceso a las diferentes librerías del API JavaScript de Google Maps.
• useApiIsLoaded: Proporciona información sobre si el API ha terminado de cargarse.
• useApiLoadingStatus: Indica el estado actual de la carga del API.

Conclusión

En este tutorial hemos explorado los principales componentes y utilidades que nos ofrece la librería react-google-maps. Esta herramienta posee un enorme potencial, por lo que te invito a experimentar con ella y a desarrollar tus ideas de forma creativa e innovadora.

Muchas gracias por acompañarme hasta el final. Espero que este tutorial te haya resultado útil y te inspire a seguir profundizando en el desarrollo de aplicaciones con Google Maps y React.

Glosario

API

Conjunto de reglas y herramientas que permiten que dos aplicaciones se comuniquen entre sí. En este contexto, se usa para interactuar con Google Maps.

API Key

Clave única que autoriza el acceso a una API, permitiendo el uso seguro de los servicios de Google Maps.

API Provider

Componente o servicio que carga y gestiona el acceso a la API de Google Maps dentro de la aplicación, proporcionando el contexto necesario para que otros componentes funcionen correctamente.

JSX

Sintaxis que combina JavaScript y HTML, utilizada en React para describir interfaces de usuario de forma intuitiva.

React

Biblioteca de JavaScript desarrollada por Facebook para construir interfaces de usuario interactivas y escalables.

Vite

Herramienta moderna para el desarrollo de aplicaciones web que ofrece un entorno rápido y optimizado, muy utilizada en proyectos de React.

Hooks

Funciones especiales en React que permiten usar estado y otras características sin necesidad de escribir clases, facilitando la reutilización de lógica entre componentes.

Renderizar

Proceso de transformar el código (por ejemplo, JSX) en elementos visuales que se muestran en la pantalla.

Marker

Ícono o pin que se coloca en un mapa para indicar una ubicación específica.

Advanced Marker

Versión más avanzada y personalizable del marcador, que permite modificar su apariencia utilizando imágenes, SVGs o contenido HTML.

Pin

Componente visual que representa un marcador personalizado, permitiendo cambiar colores, bordes y otros estilos.

InfoWindow

Ventana emergente que muestra información adicional sobre una ubicación o marcador en el mapa.

Map Control

Componente que añade controles interactivos (como botones de zoom o desplazamiento) directamente en la instancia del mapa.

Map ID

Identificador único asignado a un diseño o configuración personalizada de un mapa en Google Maps Platform, que permite adaptar su apariencia y funcionalidad.

Contexto

Método en React para compartir datos entre componentes sin necesidad de pasarlos manualmente a través de cada nivel de la aplicación.

Event Listener

Función que se ejecuta en respuesta a una acción del usuario (como un clic o un movimiento del mouse), permitiendo que la aplicación reaccione a interacciones específicas.

Google Cloud Platform

Plataforma de servicios en la nube de Google que ofrece herramientas y APIs, incluida la de Google Maps, para desarrollar y alojar aplicaciones.

Google Maps Platform

Conjunto de servicios y APIs que permite integrar mapas, localización y otras funcionalidades geoespaciales en aplicaciones web y móviles.

Referencias bibliográficas

1. Google Developers. (n.d.). Google Maps JavaScript API Reference. Recuperado de Google Developers

2. React Community. (n.d.). React Documentation. Recuperado de React

3. Vite. (n.d.). Vite Documentation. Recuperado de Vite.js

4. VisGL. (n.d.). react-google-maps Library. Recuperado de react-google-maps

5. Sridhar, S. (2021). Learning React: Modern Patterns for Developing React Apps. O’Reilly Media.

6. Haverbeke, M. (2020). Eloquent JavaScript: A Modern Introduction to Programming. No Starch Press.