Servicios de la versión 2 del API de JavaScript de Google Maps

Nota: desde el 19 de mayo de 2010, la versión 2 del API de JavaScript de Google Maps ha quedado oficialmente obsoleta. Podrás seguir utilizando la versión 2 del API de acuerdo con la política de funciones obsoletas, pero te recomendamos que realices la migración del código a la versión 3 del API de JavaScript de Google Maps.

Visión general de los servicios

El API de Google Maps se amplía regularmente mediante la adición de nuevas funciones y características que se suelen publicar primero en maps.google.com. En esta sección se describen estos servicios. Nota: dado que la definición de un "servicio" es flexible, esta sección es una especie de cajón de sastre. Básicamente, esta sección es donde ponemos todas las cosas ingeniosas que no podíamos poner en ninguna otra parte.

Análisis de datos y código XML

El API de Google Maps exporta un método predeterminado para crear objetos XmlHttpRequest() independientes del navegador que funcionen en las versiones más recientes de Internet Explorer, Firefox y Safari. Al igual que todos los objetos XmlHttpRequest, los archivos recuperados deben encontrarse en el dominio local. El siguiente ejemplo descarga un archivo denominado myfile.txt y muestra su contenido en un objeto alert() de JavaScript:

var request = GXmlHttp.create();
request.open("GET", "myfile.txt", true);
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    alert(request.responseText);
  }
}
request.send(null);

El API también exporta un métodoGDownloadUrl() más sencillo para las solicitudes GET HTTP que elimina la necesidad de realizar la comprobación de XmlHttpRequest() readyState. El ejemplo anterior se puede reescribir para emplear GDownloadUrl():

GDownloadUrl("myfile.txt", function(data, responseCode) {
  alert(data);
});

Puedes analizar un documento XML con el método estático GXml.parse(), que requiere una cadena XML como único argumento. Este método es compatible con la mayoría de los navegadores modernos, pero genera una excepción si el navegador no admite el análisis XML de forma nativa.

En este ejemplo, descargamos un archivo estático ("data.xml") que contiene una lista de coordenadas de latitud y de longitud en XML mediante el método GDownloadUrl. Una vez completada la descarga, analizamos el documento XML con GXml y creamos un marcador en cada uno de estos puntos del documento XML.

var map = new GMap2(document.getElementById("map_canvas"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// Download the data in data.xml and load it on the map. The format we
// expect is:
// <markers>
//   <marker lat="37.441" lng="-122.141"/>
//   <marker lat="37.322" lng="-121.213"/>
// </markers>
GDownloadUrl("data.xml", function(data, responseCode) {
  var xml = GXml.parse(data);
  var markers = xml.documentElement.getElementsByTagName("marker");
  for (var i = 0; i < markers.length; i++) {
    var point = new GLatLng(parseFloat(markers[i].getAttribute("lat")),
                            parseFloat(markers[i].getAttribute("lng")));
    map.addOverlay(new GMarker(point));
  }
});

Ver ejemplo (xhr-requests.html). En este ejemplo se ha utilizado un archivo de datos XML externo data.xml.

Para obtener más información, consulta las referencias de las clases GXmlHttp y GXml.

Codificación geográfica

La codificación geográfica es el proceso de transformar direcciones (como "1600 Amphitheatre Parkway, Mountain View, CA") en coordenadas geográficas (como 37.423021 de latitud y -122.083739 de longitud), que se pueden utilizar para colocar marcadores o situar el mapa. El API de Google Maps incluye un servicio web de codificación geográfica al que se puede acceder directamente mediante una solicitud HTTP o utilizando un objeto GClientGeocoder.

El API de Google Maps proporciona un geocoder de cliente para codificar direcciones de forma geográfica, a partir de la información introducida por el usuario. Si por el contrario quieres asignar códigos geográficos a direcciones conocidas y estáticas, consulta la documentación del servicio de codificación geográfica.

El objeto de codificación geográfica

Puedes acceder al servicio de codificación geográfica del API de Google Maps a través del objeto GClientGeocoder. Utiliza GClientGeocoder.getLatLng() para convertir una cadena de dirección en un objeto GLatLng. Este método utiliza como parámetros una cadena de dirección que se debe convertir y una función de devolución de llamada que se debe ejecutar al recuperar la dirección. La función de devolución de llamada es necesaria, dado que la codificación geográfica implica el envío de una solicitud a los servidores de Google y puede tardar bastante.

En este ejemplo, se codifica de forma geográfica una dirección, se añade un marcador en ese punto y se abre una ventana de información que muestra la dirección. Observa que la devolución de llamada se transmite como una función literal.

var map = new GMap2(document.getElementById("map_canvas"));
var geocoder = new GClientGeocoder();

function showAddress(address) {
  geocoder.getLatLng(
    address,
    function(point) {
      if (!point) {
        alert(address + " not found");
      } else {
        map.setCenter(point, 13);
        var marker = new GMarker(point);
        map.addOverlay(marker);

        // As this is user-generated content, we display it as
        // text rather than HTML to reduce XSS vulnerabilities.
        marker.openInfoWindow(document.createTextNode(address));
      }
    }
  );
}

Ver ejemplo (geocoding-simple.html).

También puedes modificar el geocoder del API de Google Maps para dar preferencia a los resultados situados dentro de una determinada ventana gráfica (expresada como un cuadro delimitador del tipo GLatLngBounds) mediante el método GClientGeocoder.setViewport(). Puedes hacer que los resultados se devuelvan ajustados a medida de un dominio (país) concreto mediante el método GClientGeocoder.setBaseCountryCode(). Puedes enviar solicitudes de codificación geográfica para todos los dominios en los que la aplicación principal de Google Maps ofrezca la función de codificación geográfica. Por ejemplo, las búsquedas de "Toledo" devolverán resultados distintos en el dominio de España (http://maps.google.es) especificado con el código de país "es" y en el dominio predeterminado de Estados Unidos (http://maps.google.com).

Cómo extraer direcciones estructuradas

Si deseas acceder a información estructurada sobre una dirección, GClientGeocoder también proporciona un método getLocations() que devuelve un objeto JSON que consta de la información que se indica a continuación.

• Status
• • request: el tipo de solicitud. En este caso, siempre es geocode.
  • code: un código de respuesta (similar a los códigos de estado HTTP) que indica si la solicitud de codificación geográfica se ha realizado correctamente o no. Consulta la lista completa de códigos de estado.
• Placemark: si el geocoder encuentra varias coincidencias, es posible que se devuelvan varias marcas de posición.
• • address: una versión de la dirección con formato elegante y uso correcto de mayúsculas y minúsculas.
  • AddressDetails: la dirección en formato xAL (lenguaje de direcciones extensible), un estándar internacional para el formato de direcciones.
  • • Accuracy: un atributo que indica la precisión con la que se puede realizar la codificación geográfica de la dirección. Consulta una lista de posibles valores.
  • Point: un punto en el espacio 3D
  • • coordinates: la longitud, latitud y altitud de la dirección. En este caso, la altitud siempre se define como 0.

A continuación, reproducimos el objeto JSON devuelto por el geocoder para la dirección de la sede principal de Google:

{
  "name": "1600 Amphitheatre Parkway, Mountain View, CA, USA",
  "Status": {
    "code": 200,
    "request": "geocode"
  },
  "Placemark": [
    {
      "address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "AddressDetails": {
        "Country": {
          "CountryNameCode": "US",
          "AdministrativeArea": {
            "AdministrativeAreaName": "CA",
            "SubAdministrativeArea": {
              "SubAdministrativeAreaName": "Santa Clara",
              "Locality": {
                "LocalityName": "Mountain View",
                "Thoroughfare": {
                  "ThoroughfareName": "1600 Amphitheatre Pkwy"
                },
                "PostalCode": {
                  "PostalCodeNumber": "94043"
                }
              }
            }
          }
        },
        "Accuracy": 8
      },
      "Point": {
        "coordinates": [-122.083739, 37.423021, 0]
      }
    }
  ]
}

En este ejemplo, utilizamos el método getLocations() para realizar la codificación geográfica de las direcciones y extraemos la versión con formato elegante de la dirección y el código de país de dos letras del JSON para mostrar estos datos en la ventana de información.

var map;
var geocoder;

function addAddressToMap(response) {
  map.clearOverlays();
  if (!response || response.Status.code != 200) {
    alert("\"" + address + "\" not found");
  } else {
    place = response.Placemark[0];
    point = new GLatLng(place.Point.coordinates[1],
                        place.Point.coordinates[0]);
    marker = new GMarker(point);
    map.addOverlay(marker);
    marker.openInfoWindowHtml(place.address + '<br>' + 
      '<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
  }
}

Ver ejemplo (geocoding-extraction.html).

Codificación geográfica inversa

El término codificación geográfica suele hacer referencia al proceso de convertir una dirección interpretable por humanos en un punto de un mapa. El proceso contrario, la conversión de un punto en una dirección interpretable por humanos, se conoce como codificación geográfica inversa.

El método GClientGeocoder.getLocations() es compatible con ambos tipos de codificación geográfica, la estándar y la inversa. Si transmites este método a un objeto GLatLng en lugar de una dirección String, el geocoder realizará una búsqueda inversa y devolverá un objeto JSON estructurado de la ubicación localizable mediante dirección más cercana. Ten en cuenta que la ubicación localizable mediante dirección más cercana puede estar situada a cierta distancia de los valores de latitud y longitud originales de la consulta, si el objeto GLatLng proporcionado no se corresponde exactamente con ninguna de las ubicaciones localizables mediante dirección.

Nota: la codificación geográfica inversa no es una ciencia exacta. El geocoder intentará buscar la ubicación localizable mediante dirección más cercana dentro de un determinado margen; si no encuentra ninguna correspondencia, el geocoder devolverá, por lo general, un código de estado G_GEO_UNKNOWN_ADDRESS (602).

var map;
var geocoder;
var address;

function initialize() {
  map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(new GLatLng(40.730885,-73.997383), 15);
  map.addControl(new GLargeMapControl);
  GEvent.addListener(map, "click", getAddress);
  geocoder = new GClientGeocoder();
}

function getAddress(overlay, latlng) {
  if (latlng != null) {
    address = latlng;
    geocoder.getLocations(latlng, showAddress);
  }
}

function showAddress(response) {
  map.clearOverlays();
  if (!response || response.Status.code != 200) {
    alert("Status Code:" + response.Status.code);
  } else {
    place = response.Placemark[0];
    point = new GLatLng(place.Point.coordinates[1],place.Point.coordinates[0]);
    marker = new GMarker(point);
    map.addOverlay(marker);
    marker.openInfoWindowHtml(
        '<b>orig latlng:</b>' + response.name + '<br/>' + 
        '<b>latlng:</b>' + place.Point.coordinates[1] + "," + place.Point.coordinates[0] + '<br>' +
        '<b>Status Code:</b>' + response.Status.code + '<br>' +
        '<b>Status Request:</b>' + response.Status.request + '<br>' +
        '<b>Address:</b>' + place.address + '<br>' +
        '<b>Accuracy:</b>' + place.AddressDetails.Accuracy + '<br>' +
        '<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
  }
}

Ver ejemplo (geocoding-reverse.html).

Cachés de codificación geográfica

GClientGeocoder está equipado de forma predeterminada con una memoria caché en el lado del cliente. La caché almacena las respuestas del geocoder, a fin de permitir respuestas más rápidas si las direcciones se vuelven a codificar. Para desactivar la caché, transmite null al método setCache() del objeto GClientGeocoder. No obstante, recomendamos dejar activada la caché, dado que esto mejora el rendimiento. Para cambiar la caché utilizada por GClientGeocoder, ejecuta setCache() y transmite la nueva caché. Para vaciar el contenido de la caché actual, ejecuta el método reset() en el geocoder o en la caché directamente.

Animamos a los programadores a crear sus propias cachés en el lado del cliente. En este ejemplo, construimos una caché que contiene respuestas del geocoder preprocesadas para seis capitales de países cubiertas por el API de codificación geográfica. En primer lugar, creamos una matriz de respuestas de codificación geográfica. A continuación, creamos una caché personalizada que amplía un objeto GeocodeCache estándar. Una vez definida la caché, ejecutamos el método setCache(). No se realiza una comprobación estricta de los objetos almacenados en la caché, por lo que también es posible almacenar otro tipo de información (como el número de habitantes).

// Builds an array of geocode responses for the 6 capitals
var city = [
  {
    name: "Washington, DC",
    Status: {
      code: 200,
      request: "geocode"
    },
    Placemark: [
      {
        address: "Washington, DC, USA",
        population: "0.563M",
        AddressDetails: {
          Country: {
            CountryNameCode: "US",
            AdministrativeArea: {
              AdministrativeAreaName: "DC",
              Locality: {
                LocalityName: "Washington"
              }
            }
          },
          Accuracy: 4          
        },
        Point: {
          coordinates: [-77.036667, 38.895000, 0]
        }
      }
    ]
  },
  ... // etc., and so on for other cities
];

  var map;
  var geocoder;

  // CapitalCitiesCache is a custom cache that extends the standard GeocodeCache.
  // We call apply(this) to invoke the parent's class constructor.
  function CapitalCitiesCache() {
    GGeocodeCache.apply(this);
  }

  // Assigns an instance of the parent class as a prototype of the
  // child class, to make sure that all methods defined on the parent
  // class can be directly invoked on the child class.
  CapitalCitiesCache.prototype = new GGeocodeCache();

  // Override the reset method to populate the empty cache with
  // information from our array of geocode responses for capitals.
  CapitalCitiesCache.prototype.reset = function() {
    GGeocodeCache.prototype.reset.call(this);
    for (var i in city) {
      this.put(city[i].name, city[i]);
    }
  }

  map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(new GLatLng(37.441944, -122.141944), 6);

  // Here we set the cache to use the UsCitiesCache custom cache.
  geocoder = new GClientGeocoder();
  geocoder.setCache(new CapitalCitiesCache());

Ver ejemplo (geocoding-cache.html).

Cómo usar el servicio web de codificación geográfica

Google también proporciona un servicio web de codificación geográfica a través de HTTP. Este servicio de codificación geográfica es distinto al API de JavaScript de Google Maps. No se recomienda el uso del servicio web de codificación geográfica para la recuperación directa o dinámica de solicitudes de codificación geográfica; utiliza el geocoder de cliente de JavaScript que se indica en este capítulo. Sin embargo, el geocoder HTTP resulta útil para completar un conjunto de datos estático, para la depuración o para aquellos casos en los que no existe un objeto GClientGeocoder de JavaScript.

Para obtener más información, consulta el servicio de web de codificación geográfica.

Cómo usar los objetos de Street View

El uso de objetos panorámicos de Street View requiere que el navegador del cliente sea compatible con el complemento de Flash.

Google Street View proporciona vistas panorámicas de 360 grados desde las carreteras designadas en todas las áreas donde Google Maps tiene cobertura. A continuación, se muestra una imagen de Street View de ejemplo.

Para mostrar estas imágenes interactivas, Google Street View utiliza el complemento Flash®, compatible con la mayoría de navegadores. El API de Google Maps ofrece el servicio Street View que permite obtener y manipular las imágenes utilizadas en Street View de Google Maps.

¡Nuevo! Ahora, el servicio Street View ofrece fotos de usuarios procedentes de repositorios de imágenes compatibles como Panoramio y Picasa. Consulta la sección Cómo visualizar fotos de usuarios en Street View que se encuentra más abajo.

El objeto GStreetviewPanorama

Las imágenes de Street View son compatibles gracias al uso del objeto GStreetviewPanorama, que proporciona una interfaz del API al visor Flash® de Street View. Para incorporar Street View a la aplicación del API de Google Maps, debes seguir estos sencillos pasos:

1. Crea un contenedor (normalmente un elemento <div>) que aloje el visor Flash® de Street View.
2. Crea un objeto GStreetviewPanorama y colócalo en el contenedor.
3. Inicializa el objeto de Street View de modo que haga referencia a una ubicación específica y muestre un punto de vista inicial.
4. Gestiona los navegadores incompatibles comprobando el valor del error 603.

El objeto GStreetviewPanorama requiere un elemento de contenedor en su constructor. Opcionalmente, también permite establecer su ubicación mediante el parámetro GStreetviewPanoramaOptions. Puedes ejecutar setLocationAndPOV() en el objeto después de construirlo para cambiar su ubicación y punto de vista.

Nota: aunque la función Street View está diseñada para utilizarse con un mapa, este uso no es obligatorio. Puedes utilizar un objeto de Street View independiente sin un mapa.

A continuación se ofrece más información sobre los contenedores y sobre la definición de ubicaciones y de puntos de vista.

Contenedores de Street View

El visor Flash de Street View requiere un nodo DOM de contenedor en el que mostrar el contenido, normalmente un elemento <div>. Para una visualización óptima de las imágenes panorámicas, te recomendamos que establezcas un tamaño mínimo de 200 x 200 píxeles. No recomendamos utilizar visores de gran tamaño, ya que pueden provocar que el visor Flash consuma demasiada memoria y afectar negativamente al rendimiento del navegador.

El constructor GStreetviewPanorama requiere que un parámetro container identifique el elemento del contenedor inicial con el que mostrar el visor Flash de Street View. Puedes utilizar la acción hide() con el objeto GStreetviewPanorama para desactivar temporalmente la visualización o show() para volver a activar la presentación visual del visor.

Si en algún momento deseas modificar el contenedor del visor Flash de Street View, envíale un método setContainer(), pasándole el nuevo elemento al que debe adjuntarse. Si se modifica el tamaño del contenedor, puedes enviar un método checkResize() al objeto GStreetviewPanorama para forzar un cambio de tamaño, de modo que se ajuste a las nuevas dimensiones.

Si quieres eliminar por completo del DOM el visor Flash de Street View y liberar la memoria correspondiente, transmite el método remove() al objeto. Debes ejecutar este método antes de eliminar el elemento contenedor del objeto de Street View del DOM; si no realizas esta operación, se producirán pérdidas de memoria o errores de JavaScript en el navegador del cliente.

Ubicaciones de Street View

Una imagen de Street View consta de una ubicación (que se corresponde con un objeto GLatLng) y una orientación concreta (un objeto GPov), que juntos identifican la vista para la visualización de la imagen. Ambos parámetros se pueden especificar al construir el objeto de Street View mediante el parámetro opcional GStreetviewPanoramaOptions.

En la página del Centro de asistencia de Google, puedes encontrar una lista de las ciudades compatibles actualmente con Street View. Existen tres métodos básicos para determinar si una ubicación admite datos de Street View:

• Puedes almacenar el objeto GLatLng de una ubicación válida conocida de Street View.
• Puedes examinar la superposición de mosaico GStreetviewOverlay e inspeccionar visualmente la red de carreteras. Las carreteras que admiten Street View se muestran destacadas en azul en la superposición. Puedes utilizar eventos de clic o lógica de codificación geográfica para transmitir ubicaciones compatibles a objetos de GStreetviewPanorama. (Consulta las superposiciones de Street View).
• Puedes utilizar el objeto GStreetviewClient para realizar consultas de objetos de Street View una vez que se hayan transmitido los objetos GLatLng. El objeto GStreetviewClient admite varias consultas para encontrar datos panorámicos. (Consulta las consultas de clientes de Street View).

Ten en cuenta que los dos últimos métodos son inexactos: el servicio Street View no requiere (y normalmente no recibe) latitudes y longitudes exactas en estos casos, sino que busca la existencia de datos panorámicos cerca de un objeto GLatLng determinado.

El siguiente ejemplo emplea GStreetviewPanoramaOptions para especificar la latitud y la longitud iniciales que deben emplearse en Street View. El valor de punto de vista se deja en blanco, lo que indica la vista predeterminada hacia el Norte.

var fenwayPark = new GLatLng(42.345573,-71.098326);
panoramaOptions = { latlng:fenwayPark };
var myPano = new GStreetviewPanorama(document.getElementById("pano"), panoramaOptions);

Ver ejemplo (streetview-simple.html).

Gestión de errores de Street View

Dado que Street View requiere compatibilidad con el complemento Flash®, tu código debe comprobar si dicho complemento se puede utilizar en el navegador del usuario. Para realizar esta comprobación en la aplicación, registra un detector de eventos para el evento error en el objeto GStreetviewPanorama. El evento error transmite un código de error que puedes evaluar.

El siguiente código de ejemplo lleva a cabo una comprobación rápida de la compatibilidad con el complemento Flash y muestra un cuadro de diálogo de alerta si dicha compatibilidad no existe.

var fenwayPark = new GLatLng(42.345573,-71.098326);
panoramaOptions = { latlng:fenwayPark };
myPano = new GStreetviewPanorama(document.getElementById("pano"), panoramaOptions);
GEvent.addListener(myPano, "error", handleNoFlash);
    
function handleNoFlash(errorCode) {
  if (errorCode == 603) {
    alert("Error: Flash doesn't appear to be supported by your browser");
    return;
  }
}  

Puntos de vista de Street View

La ubicación de Street View define la posición geométrica de la cámara para proporcionar una imagen, pero no así la orientación de la cámara para dicha imagen. Con este objetivo, el objeto literal GPov define tres propiedades:

• yaw define el ángulo de rotación en torno a la posición geométrica de la cámara, expresado en grados obtenidos a partir del norte absoluto. Estos ángulos se miden en el sentido de las agujas del reloj (90 grados es el este absoluto).
• pitch define la variación del ángulo hacia "arriba" o hacia "abajo" en relación con la inclinación inicial predeterminada de la cámara, que suele corresponderse (aunque no siempre es así) con una posición completamente horizontal. Por ejemplo, lo más probable es que una imagen tomada en una colina muestre una inclinación predeterminada que no es horizontal. Los ángulos de inclinación se miden con valores negativos hacia arriba (hasta -90 grados en ángulo recto y ortogonal a la inclinación predeterminada) y con valores positivos hacia abajo (hasta +90 grados en ángulo recto y ortogonal a la inclinación predeterminada).
• zoom define el nivel de zoom de la vista (delimitando de forma efectiva el campo de visión). El valor 0 indica un alejamiento total. Distintas ubicaciones de Street View pueden proporcionar niveles de zoom mayores o menores.

De forma predeterminada, todos estos valores permanecen en 0 y definen una vista plana horizontal, directamente al norte, con el campo de visión más amplio posible.

Definición de la vista panorámica

Tal como hemos descrito anteriormente, puedes establecer la ubicación y el valor GPov para un objeto panorámico al construirlo mediante el parámetro GStreetviewPanoramaOptions.

fenwayPark = new GLatLng(42.345573,-71.098326);
myPOV = {yaw:370.64659986187695,pitch:-20};
svOpts = {latlng:fenwayPark, pov:myPOV};
var myPano = new GStreetviewPanorama(document.getElementById("pano"), svOpts);

También puedes definir la ubicación y el punto de vista mediante el método setLocationAndPOV() después de construir el objeto GStreetviewPanorama. En el siguiente ejemplo, creamos un objeto GStreetviewPanorama y definimos su ubicación y punto de vista con un valor específico.

var myPano = new GStreetviewPanorama(document.getElementById("pano"));
fenwayPark = new GLatLng(42.345573,-71.098326);
myPOV = {yaw:370.64659986187695,pitch:-20};
myPano.setLocationAndPOV(fenwayPark, myPOV);

Ver ejemplo (streetview-object.html).

Cómo usar la superposición de Street View

La manera más sencilla de determinar si una carretera admite Street View es mediante el objeto GStreetviewOverlay. Basta con crear una superposición de este tipo y añadirla al mapa. Las carreteras que contienen datos de Street View se mostrarán destacadas en el mapa mediante un contorno azul.

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
svOverlay = new GStreetviewOverlay();
map.addOverlay(svOverlay);

Ver ejemplo (streetview-layer.html).

Si sabes que una zona geográfica admite Street View, introduce información en el objeto GStreetviewPanorama para añadir lógica que responda a clics en carreteras de Street View válidas.

var myPano = new GStreetviewPanorama(document.getElementById("pano"));
var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(42.345573,-71.098326), 14);
svOverlay = new GStreetviewOverlay();
map.addOverlay(svOverlay);
GEvent.addListener(map,"click", function(overlay,latlng) {
  myPano.setLocationAndPOV(latlng);
});

Ver ejemplo (streetview-click.html).

Si sabes que una ubicación concreta admite Street View, puedes guardar la información de la ubicación y el punto de vista y colocar esa información dentro del propio objeto.

Cómo visualizar fotos de usuarios en Street View

El objeto GStreetviewPanorama no solo admite imágenes de Street View, sino que también puede mostrar de forma adicional fotos de usuarios procedentes de repositorios de fotos populares como Picasa y Panoramio. A continuación se muestran ejemplos de fotos de usuarios en Street View:

Al navegar hasta una ubicación que contiene fotos de usuarios cercanas, Street View mostrará una pequeña ventana etiquetada como "Fotos de usuarios" que conduce a un conjunto de fotos de usuarios cuando se hace clic en ella.

Activación de las fotos de usuarios

En Street View, las fotos de usuarios se encuentran activadas de forma predeterminada. Para desactivar las fotos de usuarios en Street View, establece userPhotos como false en el parámetrofeatures de GStreetviewPanoramaOptions. De forma adicional, puedes indicar los repositorios de fotos específicos que deseas activar en el campo userPhotoOptions de la opción.

Actualmente se admiten las siguientes opciones de GStreetviewUserPhotoOptions:

• "panoramio"
• "picasa"
• "flickr"

Si no especificas ningún repositorio de fotos en particular, se activarán todos.

El siguiente ejemplo muestra un mapa de Boston en el que se han activado fotos de usuarios procedentes de los repositorios Picasa y Panoramio:

var panoOpts = {
  features: {
    streetView: true,
    userPhotos: true
  },
  userPhotoOptions: {
    photoRepositories: [ 'panoramio', 'picasa']
  }
};
var myPano = new GStreetviewPanorama(document.getElementById("pano"), panoOpts);
var boston = new GLatLng(42.345573,-71.098326);
GEvent.addListener(myPano, "error", handleNoFlash);  

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(boston, 14);
svOverlay = new GStreetviewOverlay();
map.addOverlay(svOverlay);
myPano.setLocationAndPOV(boston);

Ver ejemplo (streetview-photos.html)

Nota: no era necesario activar de forma explícita las fotos de usuarios en este ejemplo, pero lo hemos hecho para ilustrar el API.

Cómo recuperar fotos específicas

Algunos repositorios de fotos (normalmente el repositorio "panoramio") te permiten identificar fotos específicas. El objeto de Street View te permite seleccionar fotos específicas y mostrarlas en él seleccionando la foto mediante el objeto GPhotoSpec. Un objeto GPhotoSpec consta de un identificador repository y un campo id que identifica la foto individual.

El siguiente ejemplo muestra una foto de Fenway Park en Boston, el estadio de los Red Sox, campeones de la serie mundial de béisbol de 2004:

var panoOpts = {
  features: {
    streetView: false,
    userPhotos: true
  },
  userPhotoOptions: {
    photoRepositories: [ 'panoramio']
  }
};
var myPano = new GStreetviewPanorama(document.getElementById("pano"), panoOpts);
var fenway = {
  repository: "panoramio",
  id: 8323025
};
GEvent.addListener(myPano, "error", handleNoFlash);
myPano.setUserPhoto(fenway);

Ver ejemplo (streetview-photo-id.html)

Para obtener más información sobre la obtención de identificaciones para fotos individuales, consulta el API de Panoramio.

Consultas de clientes de Street View

No siempre es posible o deseable desde la perspectiva del usuario determinar si una carretera admite Street View mediante la inspección visual de GStreetviewOverlay. Por ese motivo, el API ofrece un servicio que permite programar solicitudes para recuperar datos de Street View. Este servicio se ofrece mediante el uso del objeto GStreetviewClient.

Búsquedas de Street View

El objeto GStreetviewClient lleva a cabo búsquedas de datos panorámicos mediante el servicio de Street View de Google. Dado que la búsqueda es asincrónica, los métodos de esta clase requieren funciones de devolución de llamada que se deben ejecutar al recibir los datos. Todas las devoluciones de llamada dadas transmiten null si no se devuelve ningún valor, de modo que deberás comprobar este caso dentro de tus funciones de devolución de llamada.

El método getNearestPanoramaLatLng() de GStreetviewClientrecupera el objeto GLatLng de una imagen panorámica cercana de una ubicación determinada (se transmite a sí mismo comoGLatLng).

Tanto getNearestPanorama() como getPanoramaById() recuperan objetos GStreetviewData, que almacenan metadatos sobre el objeto panorámico concreto. Estos datos se describen en la siguiente sección.

Gestión de respuestas de los clientes

La estructura de un objeto GStreetviewData consta de tres propiedades: location y copyright (que contienen información sobre la imagen específica que se muestra) y links (que ofrece información sobre los objetos panorámicos adyacentes). La estructura de estas propiedades se describe a continuación:

# The location property uses the GStreetviewLocation object literal
location: {
  latlng: GLatLng, 
  pov: { 
    yaw: String, 
    pitch: String, 
    zoom: String
  }, 
  description: String, 
  panoId: String
}

copyright: String

# The links property uses the GStreetviewLink object literal
links[]: {
  yaw: String, 
  description: String, 
  panoId: String
}

(Para obtener descripciones completas de los objetos literales GStreetviewLocation y GStreetviewLink, consulta la Referencia del API de Google Maps).

Nota: la propiedad GStreetviewData.location no se debe confundir con la propiedad window.location. Si intentas extraer datos desde la propiedad location de este objeto, asegúrate de recibir realmente una respuesta del servidor de Street View (ver a continuación). De lo contrario, la propiedad location tendrá de forma predeterminada el valor de window.location y se producirá un comportamiento inesperado.

Si una solicitud a un objeto GStreetviewClient es correcta, transmitirá un objeto GLatLng o GStreetviewData a la función de devolución de llamada especificada. Dado que la recuperación de datos de Street View es asincrónica, es posible que el objeto del cliente no recupere los objetos de datos, por lo que el código no debe depender de que estos datos estén presentes. En lugar de ello, siempre se debe comprobar el valor code devuelto desde cualquier solicitud, ya que este valor siempre se devuelve. El siguiente fragmento de código ilustra este concepto.

panoClient = new GStreetviewClient();
panoClient.getPanoramaById(panoData.location.panoId, processReturnedData);
    
function processReturnedData(panoData) {
  if (panoData.code != 200) {
    GLog.write('showPanoData: Server rejected with code: ' + panoData.code);
    return;
  }
  
  // Code to actually process the GStreetviewData object is contained here
  
}  

A continuación reproducimos una respuesta completa con una estructura GStreetviewData de ejemplo:

{
  location: {
    latlng: GLatLng("42.345566, -71.098354")
    pov: {
      yaw: "370.64659986187695"
      pitch: "-20"
      zoom: "1"
    }
    description: "Yawkey Way"
    panoId: "-KNGDaZvSQjMqug7ISM_CA"
  }
  copyright: "© 2008 Google"
  links:[ {
    yaw: "0"
    description: "Yawkey Way"
    panoId: "S142iWXa_4Fi7L7d8HKhuQ"
  },
  {
    yaw: "0"
    description: "Yawkey Way"
    panoId: "2vFI79AjOpHTAYJSCKquFg"
  }
  ]
}

La siguiente aplicación de ejemplo muestra un objeto panorámico inicial, extrae su identificación, almacena el objeto panorámico vinculado en el objeto GStreetviewData devuelto y muestra el conjunto de datos asociado al objeto de Street View. Cada vez que el usuario hace clic en "Siguiente", se repite el proceso, con lo que el usuario puede desplazarse por un conjunto de objetos panorámicos adyacentes.

var map;
var myPano;   
var panoClient;
var nextPanoId;

function initialize() {
  var fenwayPark = new GLatLng(42.345573,-71.098326);
  var fenwayPOV = {yaw:370.64659986187695,pitch:-20};
      
  panoClient = new GStreetviewClient();      
   
  map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(fenwayPark, 15);
  GEvent.addListener(map, "click", function(overlay,latlng) {
    panoClient.getNearestPanorama(latlng, showPanoData);
  });
      
  myPano = new GStreetviewPanorama(document.getElementById("pano"));
  myPano.setLocationAndPOV(fenwayPark, fenwayPOV);
  GEvent.addListener(myPano, "error", handleNoFlash);  
  panoClient.getNearestPanorama(fenwayPark, showPanoData);
}
    
function showPanoData(panoData) {
  if (panoData.code != 200) {
    GLog.write('showPanoData: Server rejected with code: ' + panoData.code);
    return;
  }
  nextPanoId = panoData.links[0].panoId;
  var displayString = [
    "Panorama ID: " + panoData.location.panoId,
    "LatLng: " + panoData.location.latlng,
    "Copyright: " + panoData.copyright,
    "Description: " + panoData.location.description,
    "Next Pano ID: " + panoData.links[0].panoId
  ].join("<br/>");
  map.openInfoWindowHtml(panoData.location.latlng, displayString);
     
  GLog.write('Viewer moved to' + panoData.location.latlng);
  myPano.setLocationAndPOV(panoData.location.latlng);
}
    
function next() {
  // Get the next panoId
  // Note that this is not sophisticated. At the end of the block, it will get stuck
  panoClient.getPanoramaById(nextPanoId, showPanoData);
}
    
function handleNoFlash(errorCode) {
  if (errorCode == 603) {
    alert("Error: Flash doesn't appear to be supported by your browser");
    return;
  }
} 

Ver ejemplo (streetview-data.html).

Integración con el complemento de Google Earth

El API de Google Maps permite a los desarrolladores manipular una instancia del complemento de Google Earth en sus aplicaciones del API de Google Maps. La capa de mapa de Google Earth se carga mediante un tipo de mapa GMapType independiente, con un aspecto y con un comportamiento similar a la aplicación de Google Earth independiente, lo que permite girar perspectivas, ver elevaciones y consultar la información del KML de Google Earth en el navegador.

Nota: el complemento de Google Earth se debe instalar en el equipo del usuario para utilizar este tipo de mapa GMapType de Google Earth. Actualmente este complemento está disponible para Microsoft Windows y Apple Mac OS X. Para obtener información sobre los requisitos completos del sistema, consulta la Guía para desarrolladores del API de Google Earth.

El complemento de Google Earth también se puede controlar a través de su propia API, que es independiente y distinta al API de Google Maps. Para obtener información completa sobre el uso del complemento y del API del Google Earth, consulta la Guía para desarrolladores del API de Google Earth.

Carga del complemento de Google Earth

Para instalar el complemento, consulta las instrucciones de instalación del API de Google Earth o accede a cualquier sitio web que utilice el complemento de Google Earth. En tu aplicación, a los usuarios finales que no tengan instalado el complemento se les ofrecerá un enlace de descarga al cambiar al tipo de mapa GMapType de Google Earth. Una vez que el complemento de Google Earth se haya instalado correctamente, se cargará automáticamente (o cuando la página se haya vuelto a cargar, en función del navegador).

Cómo añadir el tipo de mapa de Google Earth

Para agregar la instancia de Google Earth a tu mapa, añade G_SATELLITE_3D_MAP a tu mapa con GMap2.addMapType(). Para mostrar este tipo de mapa directamente a través de GMap2.setMapType() o permitir que el usuario lo seleccione en un control GMapTypeControl, añade un control de tipo de mapa a través de GMap2.addControl().

El siguiente código añade el tipo de mapa G_SATELLITE_3D_MAP y, a continuación, carga Google Earth de forma explícita en el contenedor de mapa.

var map = new GMap2(document.getElementById("map_canvas"),{ size: new GSize(640,480) } );
map.setCenter(new GLatLng(42.366662,-71.106262), 11);

// Enable the Earth map type
map.addMapType(G_SATELLITE_3D_MAP);

var mapControl = new GMapTypeControl();
map.addControl(mapControl);
map.setMapType(G_SATELLITE_3D_MAP);

Ver ejemplo (services-earth-plugin.html).

Acceso al API de Google Earth en el API de Google Maps

Es posible acceder a los objetos del API de Google Earth desde el API de Google Maps. Para acceder al objeto GEPlugin raíz del tipo de mapa en 3D, ejecuta GMap2.getEarthInstance:

map.getEarthInstance(function(ge) {
  // Direct Earth API calls can go here
  ge.getLayerRoot().enableLayerById(
      ge.LAYER_BORDERS, true);  // Turn on borders and labels
});

Cómo añadir la función de búsqueda local a tu mapa

Para que los usuarios puedan buscar empresas locales, puedes utilizar GoogleBar para insertar un control de búsqueda local en tu sitio. GoogleBar se ha actualizado con una nueva interfaz de usuario y también ha añadido resultados publicitarios que se pueden configurar para obtener ingresos con tu sitio del API.

Cómo configurar GoogleBar

Para utilizar GoogleBar, primero debes especificar su comportamiento mediante el objeto GGoogleBarOptions, que debes transmitir al constructor GMap2. Una vez que se haya construido el mapa, ejecuta GMap2.enableGoogleBar() para habilitar GoogleBar. GoogleBar se ha rediseñado para tener una nueva apariencia y para añadir canales de ingresos a los sitios del API de Google Maps.

Nota: GoogleBar proporciona un envoltorio fino alrededor del API AJAX de Google para búsquedas, un producto independiente con sus propias condiciones del servicio.

Puesto que el nuevo GoogleBar tiene un comportamiento distinto al de la versión anterior, hemos proporcionado su nueva interfaz de usuario como una opción de aceptación. Para habilitar el nuevo GoogleBar, establece la propiedad style en "new" en el objeto GGoogleBarOptions. En un futuro próximo, habilitaremos este comportamiento de forma predeterminada.

El siguiente ejemplo configura GoogleBar con la nueva apariencia:

var map;
if (GBrowserIsCompatible()) {
  var mapOptions = {
    googleBarOptions : {
      style : "new",
    }
  }
  map = new GMap2(document.getElementById("map_canvas"), mapOptions);
  map.setCenter(new GLatLng(33.956461,-118.396225), 13);
  map.setUIToDefault();
  map.enableGoogleBar();
}

Ver ejemplo (control-googlebar.html).

Ten en cuenta que los resultados de este control contienen publicidad. Si quieres obtener ingresos de los resultados de búsqueda publicitarios de GoogleBar, consulta la sección de obtención de ingresos publicitarios que se muestra a continuación.

Publicidad mediante AdSense para Google Maps

Google ofrece ahora varios productos de AdSense para Google Maps para obtener ingresos con tu aplicación del API de Google Maps:

• visualización de publicidad junto con resultados de búsqueda de empresas locales a través de GoogleBar,
• visualización de publicidad basada en la ventana gráfica de Google Maps a través del bloque de anuncios de Google Maps.

Para obtener ingresos con esta publicidad, debes vincular estos objetos de AdSense para Google Maps a una cuenta de AdSense habilitada con AdSense para búsqueda y con AdSense para contenido, respectivamente.

Estos métodos de publicidad son básicamente distintos y requieren diferentes productos de Google AdSense. La visualización de anuncios en GoogleBar responde a las búsquedas directas de los usuarios, por lo que tu cuenta de AdSense se debe habilitar para AdSense para búsqueda. La visualización de anuncios en un panel del mapa, basada en la ventana gráfica de un visor, requiere que tu cuenta de AdSense esté habilitada para AdSense para contenido.

Si aún no tienes una cuenta de AdSense, regístrate para obtener una. Una vez que te hayas registrado (o si ya tienes una cuenta), asegúrate también de tener la cuenta habilitada con AdSense para búsqueda o con AdSense para contenido.

Una vez que tengas una cuenta de Adsense para búsqueda o de AdSense para contenido, recibirás una ID de editor de AdSense para búsqueda o de AdSense para contenido. Esta ID de editor se utiliza en tu código para vincular la publicidad que aparece en tu cuenta de AdSense.

Publicidad en GoogleBar

Para empezar a obtener ingresos generados a través de la publicidad con las búsquedas de los usuarios mediante GoogleBar, especifica tu ID de editor en la propiedad client del objeto GGoogleBarAdsOptions al crear tu mapa. Empezarás a obtener ingresos generados a través de la publicidad por los clics realizados en los resultados locales en tu aplicación del API. De forma opcional, también puedes especificar un canal channel de AdSense para búsqueda si lo has configurado. (Para obtener más información sobre los canales publicitarios, visita esta página).

También puedes especificar el adsafe nivel de seguridad de anuncios para asociarlo a tu publicidad y el idioma (language) en el que quieres que aparezcan los resultados.

El siguiente ejemplo muestra GoogleBar configurado para obtener ingresos generados a través de la publicidad. Ten en cuenta que debes utilizar tu propia ID de editor en tu aplicación.

var map;
if (GBrowserIsCompatible()) {
  var mapOptions = {
    googleBarOptions : {
      style : "new",
      adsOptions: {
        client: "partner-google-maps-api",
        channel: "AdSense for Search channel",
        adsafe: "high",
        language: "en"
      }
    }
  }
  map = new GMap2(document.getElementById("map_canvas"), mapOptions);
  map.setCenter(new GLatLng(33.956461,-118.396225), 13);
  map.setUIToDefault();
  map.enableGoogleBar();
}

Ver ejemplo (control-googlebar-ads.html).

Para obtener más información, consulta la GGoogleBarAdsOptions Referencia del API.

Publicidad mediante el bloque de anuncios de Google Maps

El bloque de anuncios de Google Maps es una nueva opción publicitaria dentro de la cartera de AdSense para Google Maps, creada a través de la especificación de una opción en el constructor GAdsManager. El bloque de anuncios de Google Maps muestra un pequeño panel que contiene publicidad adaptada a lo que se ve en el mapa.

Puedes habilitar el bloque de anuncios de Google Maps especificando un estilo 'adunit' en el objeto GAdsManagerOptions. Asegúrate también de especificar tu ID de editor en el constructor GAdsManager. Empezarás a obtener ingresos generados a través de la publicidad por los clics en los anuncios del bloque de anuncios de Google Maps en tu aplicación del API. De forma opcional, también puedes especificar un canal channel de AdSense para contenido si los has configurado. (Para obtener más información sobre los canales publicitarios, visita esta página).

El siguiente ejemplo muestra GAdsManager configurado para obtener ingresos generados a través de la publicidad. Ten en cuenta que debes utilizar tu propia ID de editor en tu aplicación.

var publisher_id = yourPublisherID;

var adsManagerOptions = {
  maxAdsOnMap : 2,
  style: G_ADSMANAGER_STYLE_ADUNIT,
  // The channel field is optional - replace this field with a channel number 
  // for Google AdSense tracking
  channel: 'your_channel_id'  
};

adsManager = new GAdsManager(map, publisher_id, adsManagerOptions);
adsManager.enable();

Ver ejemplo (adsmanager-adunit.html).

Nota: debes seleccionar el estilo de tus anuncios en el objeto GAdManagerOptions después de su construcción. El único estilo admitido actualmente es G_ADSMANAGER_STYLE_ADUNIT.

Para obtener más información, consulta la GAdsManager Referencia del API.

Superposiciones KML y GeoRSS

El API de Google Maps admite los formatos de datos KML y GeoRSS para la visualización de información geográfica. Estos formatos de datos se añaden a un mapa a través de un objeto GGeoXml, cuyo constructor toma la URL de un archivo XML de acceso público. Las marcas de posición de GGeoXml se muestran como objetos GMarker, mientras que las polilíneas y los polígonos de GGeoXml se muestran como polilíneas y polígonos del API de Google Maps API. Los elementos <GroundOverlay> de los archivos KML se representan como elementos GGroundOverlay en el mapa.

Los objetos GGeoXml se añaden al mapa mediante el método addOverlay() (puedes eliminarlos del mapa mediante removeOverlay()). Se admiten archivos KML y XML de GeoRSS. Ten en cuenta que GGeoXml es un objeto modular dentro del API de Google Maps y no se carga completamente hasta que se utiliza por primera vez. En consecuencia, solo se debe llamar a su constructor cuando la página se haya cargado completamente. Normalmente esto se logra llamando al constructor GGeoXml en el manipulador onload de <body>.

// The GGeoXml constructor takes a URL pointing to a KML or GeoRSS file.
// You add the GGeoXml object to the map as an overlay, and remove it as an overlay as well.
// The Maps API determines implicitly whether the file is a KML or GeoRSS file.

var map;
var geoXml;

function initialize() {
  if (GBrowserIsCompatible()) {
    map = new GMap2(document.getElementById("map_canvas")); 
    geoXml = new GGeoXml("http://gmaps-samples.googlecode.com/svn/trunk/ggeoxml/cta.kml");
    map.addControl(new GLargeMapControl());
    map.setCenter(new GLatLng(41.875696,-87.624207), 11); 
    map.addControl(new GLargeMapControl());
    map.addOverlay(geoXml);
  }
} 

Ver ejemplo de GeoRSS (geoxml-rss.html).

Ver ejemplos de KML (geoxml-kml.html).

Superposiciones de tráfico

El API de Google Maps te permite añadir información de tráfico a tus mapas mediante el objeto GTrafficOverlay, que implementa la interfaz GOverlay. Para añadir la información de tráfico a tu mapa, utiliza el método GMap2.addOverlay(). GTrafficOverlay tiene dos métodos (hide() y show()) para cambiar la visualización de la superposición del tráfico. La información de tráfico solo se muestra para las ciudades que lo admiten.

Opcionalmente, puedes transmitir opciones al constructor de GTrafficOverlay a través del objeto GTrafficOverlayOptions literal.

// The GTrafficOverlay is unique in that only one object of that type 
// should be added to a map. Adding multiple traffic overlays produces
// no added benefit.

var map;
var trafficInfo;

function initialize() {
  map = new GMap2(document.getElementById("map_canvas")); 
  map.setCenter(new GLatLng(49.496675,-102.65625), 3); 
  var trafficOptions = {incidents:true};
  trafficInfo = new GTrafficOverlay(trafficOptions);
  map.addOverlay(trafficInfo);
} 

Ver ejemplo de tráfico (trafficOverlay.html).

Rutas

El objeto GDirections permite añadir la capacidad de calcular rutas para distintos medios de transporte. El objeto GDirections solicita y recibe resultados de direcciones mediante cadenas de consulta (por ejemplo "Nueva York, NY a Chicago, IL") o latitudes y longitudes textuales (por ejemplo "40.712882, -73.967257 a 41.943181, -87.770677"). El objeto GDirections también admite rutas segmentadas mediante una serie de hitos. Las rutas se muestran como polilíneas que trazan la ruta en un mapa, como una serie de descripciones textuales en un elemento <div> (por ejemplo, "Gira a la derecha en la salida a Williamsburg Bridge) o de ambas formas.

Para utilizar rutas en el API de Google Maps, crea un objeto de tipo GDirections y designa un objeto GMap2 o <div> para recibir y mostrar los resultados. De forma predeterminada, el mapa está centrado y limitado por la ruta devuelta (aunque puedes modificar este comportamiento con los parámetros de un objeto GDirectionOptions).

Carga de rutas

Las rutas se solicitan mediante el método GDirections.load(). Este método requiere una cadena de consulta y un conjunto de parámetros opcionales de GDirectionsOptions. Se encuentran disponibles las siguientes opciones:

• locale especifica el idioma que se debe utilizar para devolver los resultados, anulando el parámetro hl del API de Google Maps si se ha proporcionado. Si no se especifica ni el parámetro locale ni hl, se utilizará el idioma predeterminado del navegador.
• travelMode especifica el método de transporte que se va a utilizar al calcular los resultados.
• avoidHighways especifica que se deben evitar las autopistas al calcular las rutas.
• getPolyline especifica que el objeto de rutas debe devolver datos de polilíneas para dibujar las rutas de regreso. De forma predeterminada, el objeto GDirections solo devuelve datos de polilínea si hay un objeto de mapa que lo muestre. Si estableces este valor true y no proporcionas un mapa, deberás procesar los datos de las polilíneas directamente.
• getSteps especifica que el objeto de rutas debe devolver indicaciones textuales, aunque no se proporcione un panel <div> para visualizar las rutas. Si estableces este valor true y no proporcionas un panel, deberás procesar los datos de los pasos directamente.
• preserveViewport especifica que el mapa no se debe centrar ni ampliar automáticamente con respecto al cuadro delimitador de las rutas devueltas; en su lugar, el mapa permanecerá centrado con respecto a la ventana gráfica actual.

Modos de viaje

De forma predeterminada, se asume que las rutas son rutas en automóvil, aunque puedes solicitar otros modos de viaje. Para ello, debes transmitir un objeto GTravelMode al ejecutar el método Directions.load(). A continuación, se indican los modos de viaje compatibles:

• G_TRAVEL_MODE_DRIVING indica las indicaciones para llegar en coche a través de la red de carreteras
• G_TRAVEL_MODE_WALKING solicita rutas a pie a través de aceras y rutas peatonales (según disponibilidad).

Nota: las rutas a pie pueden incluir a veces rutas peatonales claras que solo se admiten si has proporcionado un elemento <div> en el constructor GDirections; este elemento <div> se utiliza para mostrar una advertencia al usuario en las rutas textuales detalladas que se devuelven. Si no dispones de un objeto <div>, la solicitud de rutas a pie devolverá un error.

Gestión de las rutas devueltas

Si el objeto GDirections se ha construido con un objeto GMap2 proporcionado, la ruta devuelta contendrá una superposición de polilínea. Si el objeto GDirections se creó con un elemento <div> proporcionado, las rutas devueltas contendrán un objeto GRoute, que contendrá a su vez un conjunto de objetos GStep (si la ruta consta de indicaciones en varios puntos, la ruta devuelta contendrá varios objetos GRoute, cada uno de los cuales incluirá una serie de objetos GStep).

Ten en cuenta que esta información devuelta no se añade al objeto de ruta de inmediato. Por este motivo, el objeto GDirections define un evento de carga que se puede interceptar para determinar el estado.

Una vez devueltas las rutas, el mapa mostrará, de forma predeterminada, una polilínea con la ruta y las rutas textuales aparecerán dentro del objeto <div> proporcionado para dicho fin. El objeto GDirections también almacenará internamente los resultados, que podrás recuperar mediante los métodos GDirections.getPolyline() o GDirections.getRoute(i:Number). Los pasos de una ruta se pueden recuperar mediante el método GRoute.getStep(i:Number) y el resumen HTML de cada paso se puede recuperar mediante GStep.getDescriptionHtml(). (Consulta las rutas y los pasos que se indican a continuación).

El objeto GDirections también activa tres eventos que se pueden interceptar:

• "load": este evento se activa cuando un resultado de ruta se devuelve correctamente, pero antes de la adición de cualquier elemento de superposición al mapa/panel.
• "addoverlay": este evento se activa después de que los componentes de las polilíneas o de las rutas textuales se añadan al mapa o a los elementos DIV.
• "error": este evento se activa si una solicitud de ruta genera un error. Se puede emplear GDirections.getStatus() al realizar llamadas para obtener más información sobre el error.

// Create a directions object and register a map and DIV to hold the 
// resulting computed directions

var map;
var directionsPanel;
var directions;

function initialize() {
  map = new GMap2(document.getElementById("map_canvas"));
  directionsPanel = document.getElementById("my_textual_div");
  map.setCenter(new GLatLng(49.496675,-102.65625), 3);
  directions = new GDirections(map, directionsPanel);
  directions.load("from: 500 Memorial Drive, Cambridge, MA to: 4 Yawkey Way, Boston, MA 02215 (Fenway Park)");
}

Ver ejemplo (directions-simple.html).

El siguiente ejemplo es idéntico al primero, salvo en que las rutas se ejecutan mediante la transmisión de un objeto G_TRAVEL_MODE_WALKING:

Ver ejemplo (directions-walking.html).

Rutas y pasos

El objeto GDirections también admite rutas de varios puntos, que se pueden construir mediante el método GDirections.loadFromWaypoints(). Este método requiere una matriz de direcciones de entrada o puntos de latitud y longitud textuales. Cada hito se procesa como una ruta independiente y se devuelve en un objetoGRoute independiente, cada uno de los cuales consta de varios objetos GStep.

Los objetos GRoute almacenan el número de pasos (de tipo GStep) para esa ruta, el código geográfico de inicio y de fin de la ruta y otros datos procesados, como la distancia, la duración y la latitud y longitud exactas del punto final de la ruta (que puede ser distinto del código geográfico de fin si el código no se encuentra en un segmento de carretera). Cada objeto GStep también contiene la descripción del texto (por ejemplo: "Incorporación a US-101 S desde la salida a San José"), así como información procesada que incluye la distancia, la duración y los valores exactos de latitud y de longitud.

Para obtener documentación completa de los distintos objetos, métodos y eventos del paquete del API de rutas, consulta la Referencia del API.

Ver ejemplo (directions-advanced.html).