Eso es todo.

Para comenzar a desarrollar, consulta nuestra documentación para desarrolladores.

Activar la Google Maps Android API

Para que puedas comenzar, te proporcionaremos orientación en la Google Developers Console a fin de que hagas primero algunas acciones:

  1. Crear o seleccionar un proyecto
  2. Activar la Google Maps Android API
  3. Crear claves correspondientes
Continuar

Marcadores

Los marcadores indican ubicaciones únicas en el mapa. Puedes personalizar tus marcadores cambiando el color predeterminado o reemplazando el icono de estos por una imagen personalizada. Las ventanas de información pueden proporcionar contexto adicional a un marcador.

Ejemplos de código

En el repositorio de ApiDemos de GitHub se incluye un ejemplo en el que se muestran varias funciones de los marcadores:

Introducción

Los marcadores identifican ubicaciones en el mapa. En el marcador estándar se usa un icono estándar que se adecua al aspecto de Google Maps. Es posible cambiar el color, la imagen y el punto de anclaje del icono a través de la API. Los marcadores son objetos del tipo Marker y se agregan al mapa con el método GoogleMap.addMarker(markerOptions).

Los marcadores están diseñados para ser interactivos. Reciben eventos de click de manera predeterminada, y a menudo se usan junto con receptores de eventos para activar ventanas de información. Fijar la propiedad draggable en el valor true permite al usuario modificar la posición del marcador. Aplica una pulsación prolongada para activar la posibilidad de mover el marcador.

De manera predeterminada, cuando un usuario toca un marcador aparece la barra de herramientas en la parte inferior derecha del mapa. Esta permite al usuario acceder rápidamente a la aplicación móvil de Google Maps. Puedes deshabilitar la barra de herramientas. Para obtener más información, consulta la guía de controles.

Primeros pasos con los marcadores

En esta entrega de Maps Live, se analizan los aspectos básicos de la incorporación de marcadores a tu mapa con la Google Maps Android API.

Agregar un marcador

El siguiente ejemplo, se demuestra la manera de agregar un marcador a un mapa: Se crea el marcador en las coordenadas 10,10 y se muestra la cadena “¡Hola mundo!” en una ventana de información al hacer clic.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Hello world"));
}

Mostrar información adicional sobre un marcador

Un requisito común es el de mostrar información adicional sobre un sitio o una ubicación cuando el usuario presiona un marcador en el mapa. Consulta la guía sobre ventanas de información.

Asociar datos con un marcador

Puedes almacenar un objeto de datos arbitrario con un marcador usando Marker.setTag() y recuperar el objeto de datos usando Marker.getTag(), como se muestra en este ejemplo de código:

/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends FragmentActivity implements
        OnMarkerClickListener,
        OnMapReadyCallback {

    private static final LatLng PERTH = new LatLng(-31.952854, 115.857342);
    private static final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
    private static final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

    private Marker mPerth;
    private Marker mSydney;
    private Marker mBrisbane;

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.marker_demo);

        SupportMapFragment mapFragment =
                (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /** Called when the map is ready. */
    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;

        // Add some markers to the map, and add a data object to each marker.
        mPerth = mMap.addMarker(new MarkerOptions()
                .position(PERTH)
                .title("Perth");
        mPerth.setTag(0);

        mSydney = mMap.addMarker(new MarkerOptions()
                .position(SYDNEY)
                .title("Sydney");
        mSydney.setTag(0);

        mBrisbane = mMap.addMarker(new MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane");
        mBrisbane.setTag(0);

        // Set a listener for marker click.
        mMap.setOnMarkerClickListener(this);
    }

    /** Called when the user clicks a marker. */
    @Override
    public boolean onMarkerClick(final Marker marker) {

        // Retrieve the data from the marker.
        Integer clickCount = (Integer) marker.getTag();

        // Check if a click count was set, then display the click count.
        if (clickCount != null) {
            clickCount = clickCount + 1;
            marker.setTag(clickCount);
            Toast.makeText(this,
                           marker.getTitle() +
                           " has been clicked " + clickCount + " times.",
                           Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false;
    }
}

A continuación, te mostramos algunos ejemplos de situaciones en las que resulta útil almacenar y recuperar datos con marcadores:

  • Tu app puede proporcionar diferentes tipos de marcadores, y debes administrarlos de formas diferentes cuando el usuario hace clic en ellos. Para lograr esto, puedes almacenar una String con el marcador que indique el tipo.
  • Puedes interactuar con sistemas que poseen identificadores de registro único, con marcadores que representan registros específicos en ese sistema.
  • Los datos de un marcador pueden indicar la prioridad que se debe usar al decidir el índice z de un marcador.

Hacer que un marcador pueda arrastrarse

Puedes cambiar la posición de un marcador, una vez agregado al mapa, en tanto su propiedad draggable esté fijada en true. Mantenlo presionado durante un tiempo prolongado para habilitar el arrastre. Cuando se retire el dedo de la pantalla, el marcador permanecerá en la posición establecida.

De manera predeterminada, los marcadores no pueden arrastrarse. Debes configurar de forma explícita el marcador para que pueda arrastrarse, ya sea con MarkerOptions.draggable(boolean) antes de agregarlo al mapa o con Marker.setDraggable(boolean) una vez agregado. Puedes detectar eventos de arrastre en el marcador, según lo descrito en Eventos de arrastre de marcadores.

Con el fragmento de código siguiente se agrega un marcador que puede arrastrarse en Perth, Australia.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .draggable(true));

Personalizar un marcador

En este video se muestran maneras de usar marcadores para visualizar ubicaciones en un mapa.

Los marcadores pueden definir una imagen personalizada que debe mostrarse en lugar del icono predeterminado. Definir un icono implica configurar varias propiedades que tienen efecto sobre el comportamiento visual del marcador.

Los marcadores admiten la personalización a través de las siguientes propiedades:

Position (obligatorio)
ValorLatLng de la posición del marcador en el mapa. Esta es la única propiedad obligatoria para un objeto Marker.
Anchor
El punto de la imagen que se dispondrá en la posición de LatLng del marcador. Su valor predeterminado es el centro de la parte inferior de la imagen.
Alpha
Establece la opacidad del marcador. Valor predeterminado es 1.0.
Title
Una cadena que se muestra en la ventana de información cuando el usuario toca el marcador.
Snippet
Texto adicional que aparece debajo del título.
Icon
Un mapa de bits que se muestra en lugar de la imagen de marcador predeterminada.
Draggable
Debe fijarse en el valor true si deseas permitir que el usuario mueva el marcador. El valor predeterminado es false.
Visible
Debe fijarse en el valor false para que el marcador sea invisible. El valor predeterminado es true.
Orientación plana o de cartelera
De manera predeterminada, los marcadores se orientan contra la pantalla y no giran ni se inclinan con la cámara. Los marcadores planos se orientan respecto de la superficie terrestre, y giran y se inclinan con la cámara. El tamaño de ambos tipos de marcadores no cambia según el zoom. Usa GroundOverlays si deseas lo contrario.
Rotación
La orientación del marcador, especificada en grados en sentido horario. La posición cambia si el marcador es plano. La posición predeterminada de un marcador plano se alinea respecto del norte. Cuando el marcador no es plano, de manera predeterminada se orienta hacia arriba y la rotación hace que siempre apunte hacia la cámara.

Con el fragmento de código siguiente se crea un marcador simple que lleva el icono predeterminado.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE));

Personalizar el color del marcador

Es posible personalizar el color de la imagen de marcador predeterminada pasando un objeto BitmapDescriptor al método icon(). Puedes usar un conjunto de colores predefinidos en el objeto BitmapDescriptorFactory, o configurar un color de marcador personalizado con el método BitmapDescriptorFactory.defaultMarker(float hue). El matiz es un valor que va de 0 a 360 y representa puntos de una rueda de color.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));

Personalizar la opacidad de los marcadores

Puedes controlar la opacidad de un marcador con el método MarkerOptions.alpha(). Alpha debe especificarse como un valor flotante entre 0,0 y 1,0, donde 0 implica una transparencia total y 1 una opacidad total.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .alpha(0.7f));

Personalizar la imagen de los marcadores

Puedes reemplazar la imagen de marcador predeterminada por una personalizada, denominada icono. Los íconos personalizados siempre se configuran como un BitmapDescriptor y se definen con uno de los métodos de la clase BitmapDescriptorFactory.

fromAsset(String assetName)
Crea un marcador personalizado usando el nombre de una imagen de mapa de bits en el directorio de recursos.
fromBitmap(Bitmap image)
Crea un marcador personalizado a partir de una imagen de mapa de bits.
fromFile(String fileName)
Crea un ícono personalizado usando el nombre de un archivo de imagen de mapa de bits ubicado en el almacenamiento interno.
fromPath(String absolutePath)
Crea un marcador personalizado a partir de una ruta de acceso absoluta a un archivo de imagen de mapa de bits.
fromResource(int resourceId)
Crea un marcador personalizado usando el ID del recurso de una imagen de mapa de bits.

Con el fragmento de código siguiente se crea un marcador que lleva un icono predeterminado.

  private static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
  private Marker melbourne = mMap.addMarker(new MarkerOptions()
                            .position(MELBOURNE)
                            .title("Melbourne")
                            .snippet("Population: 4,137,400")
                            .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

Aplanar un marcador

Los iconos de marcadores normalmente se dibujan respecto de la pantalla. La rotación, la inclinación o el zoom del mapa no modifican la orientación del marcador. Puedes configurar la orientación de un marcado de modo que se vea plano respecto de la Tierra. Los marcadores que tienen esta orientación giran cuando sucede lo mismo con el mapa, y su perspectiva cambia cuando este se inclina. Los marcadores planos conservan el tamaño cuando se aplica zoom de acercamiento o alejamiento al mapa.

Para cambiar la orientación del marcador, fija el valor de la propiedad flat de este en true.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .flat(true));

Girar un marcador

Puedes hacer girar un marcador sobre su punto de anclaje a través del método Marker.setRotation(). Esta rotación se mide en grados en sentido horario a partir de la posición predeterminada. Cuando el marcador se encuentra plano sobre el mapa, la posición predeterminada es el norte. Cuando el marcador no es plano, de manera predeterminada se orienta hacia arriba y la rotación hace que siempre apunte hacia la cámara.

En el ejemplo siguiente, se hace girar el marcador 90°. Cuando se fija el punto de anclaje en 0.5,0.5, el marcador gira sobre su centro en lugar de su base.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .anchor(0.5,0.5)
                          .rotation(90.0));

Índice z del marcador

El índice z especifica el ordenamiento de pila de este marcador con respecto a otros marcadores del mapa. Un marcador con un índice z alto se dibuja encima de los marcadores con índices z bajos. El valor predeterminado del índice z es 0.

Configura el índice z en el objeto de opciones del marcador llamando a MarkerOptions.zIndex(), como se muestra en el siguiente fragmento de código:

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Marker z1")
        .zIndex(1.0f));
}

Puedes acceder al índice z del marcador llamando a Marker.getZIndex(), y puedes cambiarlo llamando a Marker.setZIndex().

Los marcadores siempre se dibujan encima de las superposiciones de mosaicos y otras superposiciones que no sean marcadores (superposiciones de suelo, polilíneas, polígonos y otras formas) independientemente del índice z de las demás superposiciones. Se considera que los marcadores se encuentran efectivamente en un grupo de índice z independiente en comparación con otras superposiciones.

Lee información sobre el efecto del índice z en eventos de clics, a continuación.

Administrar eventos de marcadores

La Google Maps API te permite escuchar eventos de marcadores y responder a ellos. Para escuchar estos eventos, debes configurar el receptor correspondiente en el objeto GoogleMap al cual pertenece el marcador. Cuando el evento tiene lugar en los marcadores del mapa, se invoca el callback del receptor y se pasa el objeto Marker correspondiente como un parámetro. Para comparar este objeto Marker con tu propia referencia a un objeto Marker, debes usar equals() en lugar de ==.

Puedes escuchar los siguientes eventos:

Eventos de clic de marcadores

Puedes usar un OnMarkerClickListener para escuchar eventos de clic en el marcador. Para configurar este receptor en el mapa, llama a GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). Cuando un usuario haga un clic en un marcador, se llamará a onMarkerClick(Marker) y el marcador se pasará como un argumento. Este método devuelve un booleano que indica si consumiste el evento (es decir, si deseas suprimir el comportamiento predeterminado). Si devuelve un valor false, el comportamiento predeterminado se sumará al comportamiento personalizado que elijas. El comportamiento predeterminado de un evento de clic de marcador consiste en mostrar su ventana de información (si está disponible) y mover la cámara de modo que el marcador quede centrado en el mapa.

Efecto del índice z en eventos de clics:

  • Cuando un usuario hace clic en un clúster de marcadores, se activa el evento de clics para el marcador con el índice z más alto.
  • Como máximo, se activa un evento por clic. En otras palabras, el clic no se pasa a los siguientes marcadores ni a otras superposiciones con valores de índice z más bajo.
  • Los clics sobre clústeres de marcadores hacen que con los clics posteriores se recorran los clústeres y se seleccione cada uno. El orden del ciclo primero prioriza el índice z y luego la proximidad al punto del clic.
  • Si el usuario hace clic fuera de la proximidad del clúster, la API vuelve a calcular el clúster y restablece el estado del ciclo de clics para que comience desde el principio.
  • El evento de clics falla en los clústeres de marcadores y genera otras formas y superposiciones antes de reiniciar el ciclo.
  • Se considera que los marcadores se encuentran efectivamente en un grupo de índice z independiente en comparación con otras superposiciones o formas (polilíneas, polígonos, círculos o superposiciones de suelo), independientemente del índice z de las demás superposiciones. Si diferentes marcadores, superposiciones o formas se apilan una sobre otra, el evento de clic primero pasa por el clúster de marcadores y luego se activa para otras superposiciones o formas que admitan clics según sus valores de índice z.

Eventos de arrastre de marcadores

Puedes usar un OnMarkerDragListener para escuchar eventos de arrastre de un marcador. Para configurar este receptor en el mapa, llama a GoogleMap.setOnMarkerDragListener. Para arrastrar un marcador, un usuario debe mantener presionado el marcador por un tiempo prolongado. Cuando el usuario retire el dedo de la pantalla, el marcador permanecerá en la posición determinada. Cuando se arrastra un marcador, inicialmente se llama a onMarkerDragStart(Marker). Cuando se arrastra el marcador, se llama a onMarkerDrag(Marker) en forma constante. Al final de la operación de arrastre, se llama a onMarkerDragEnd(Marker). Puedes obtener la posición del marcador en cualquier momento llamando a Marker.getPosition().

Nota: De manera predeterminada, los marcadores no pueden moverse. La posibilidad de que un usuario arrastre un marcador debe establecerse específicamente. Esto es posible con MarkerOptions.draggable(boolean) antes de agregar el marcador al mapa, o con Marker.setDraggable(boolean) una vez que se ha agregado a este.

Enviar comentarios sobre…

Google Maps Android API
Google Maps Android API
¿Necesitas ayuda? Visita nuestra página de asistencia.