Documente Academic
Documente Profesional
Documente Cultură
Google Maps Data API (Labs) Home Docs FAQ Blog Forum Terms
Maps and map features are stored on Google's servers. A web interface to a user's maps is available through Google
My Maps at http://maps.google.com/maps/mm.
Client libraries for other programming languages are also available, and are listed in the Developer's Guide
introduction. If you're interested in understanding more about the underlying protocol that these libraries use, see the
HTTP Protocol Guide.
Contents
Audience
Getting Started
Creating a Maps Data API Account
Loading the Google Maps Data API
Creating the MapsService Object
Authenticating to the Maps Data API Service
Authenticating in a Web Client with AuthSub
Authenticating in a Gadget with the OAuth Proxy
Overview: Maps and Features
Maps
Retrieving a List of Maps
Retrieving a Map
Creating a Map
Updating a Map
Deleting a Map
Features
Retrieving a List of Features
Retrieving a Feature
Creating a Feature
Updating a Feature
Deleting a Feature
Controlling Access to Maps
Scopes and Roles
Retrieving an ACL
Retrieving an ACL Entry
Adding an ACL Entry
Updating an ACL Entry
Deleting an ACL Entry
Debugging
More Resources
…google.com/…/developers_guide_jav… 1/16
5/3/2010 Developer Guide: JavaScript - Google …
Audience
This document is intended for JavaScript programmers who wish to interact with the Google Maps Data API to create,
update, or delete maps and map features.
For reference information about the classes and methods provided by the client library, see the JSDoc. For general
Maps Data API reference information, see the HTTP Protocol Reference.
Getting Started
Using the Maps Data API JavaScript client library requires the following:
A Google Account, used for associating your data
A JavaScript-enabled browser
The Maps Data API manipulates maps which appear within the My Maps feature on Google Maps. My Maps includes
two types of maps: Public, and Unlisted. A sample My Map is shown below:
You can use My Maps within your browser to inspect the state of your map after data updates.
Maps created with the Maps Data API are created as Public maps, meaning they will be indexed and may show up in
search results. To change your maps to Unlisted mode, you must edit them through the My Maps web UI.
…google.com/…/developers_guide_jav… 2/16
5/3/2010 Developer Guide: JavaScript - Google …
Loading the Google Maps Data API
Before your client can use the client library, the client has to request the client library code from the server. There are
two ways of requesting the client library:
Using the Google common loader
Using the Autoloader
function onGoogleDataLoad() {
// Put your code here
}
</script>
google.setOnLoadCallback() is called once the Google Data JavaScript client library has been fully loaded.
This ensures that the browser doesn't attempt to execute your code before the library is available. Your client code must
be placed inside the onGoogleDataLoad() function.
For more information on the common loading mechanism, refer to the Loading the library section of Using the
JavaScript Client Library.
…google.com/…/developers_guide_jav… 3/16
5/3/2010 Developer Guide: JavaScript - Google …
The onLoad value in the string above defines the callback function to invoke once the API is loaded. Place your client
code within the onLoad() function to ensure that the client library is fully loaded before you attempt to create a new
MapsService object. More information about autoloading is available from the Autoloading section of the AJAX APIs
documentation.
where docs-example is the application's name. The application name is used only as an identifier.
To simplify the code samples included in this document, the MapsService object is assumed to have been
declared as a global variable, service.
function doLogin() {
var token = google.accounts.user.login('http://maps.google.com/maps/feeds');
}
Calling this function directs the user to a Google-hosted login page, where they are given the choice to allow or
disallow access to their account from your application. If access is granted, they are directed back to the URL from
which the login function was called.
…google.com/…/developers_guide_jav… 4/16
5/3/2010 Developer Guide: JavaScript - Google …
google.accounts.user.logout(function() {
window.location.reload();
});
}
<ModulePrefs>
...
<OAuth>
<Service name="google">
<Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
<Request url="https://www.google.com/accounts/OAuthGetRequestToken?
scope=http://maps.google.com/maps/feeds/" method="GET" />
<Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback"
/>
</Service>
</OAuth>
...
</ModulePrefs>
More information about using the OAuth Proxy in gadgets is available from Writing OAuth Gadgets.
Maps are containers for any number of features. A map has attributes that include a title, author, and the time this map
was last updated, but does not include any geographic information or placemarks.
Features are objects on a map. A feature is associated with only one map, and is defined using KML. A feature is a
KML placemark element and can contain geographic information, descriptive information (such as a title, icon, and
description balloon contents), and associated geometry, such as lines or polygons.
…google.com/…/developers_guide_jav… 5/16
5/3/2010 Developer Guide: JavaScript - Google …
Maps
The Google Maps Data API can return a list of a user's maps as a feed object, or individual maps can be retrieved if
their URL is known.
Map feeds are requested by calling getMapFeed() on the MapsService object. getMapFeed() takes as
parameters:
a feed URL, as listed above
a function to be called when the feed is returned
an error handler
Upon success, getMapFeed() passes a feed object to the continuation function. The list of maps can be accessed
from the feed object's feed parameter:
…google.com/…/developers_guide_jav… 6/16
5/3/2010 Developer Guide: JavaScript - Google …
function listMaps() {
var list = document.createElement('ul');
var mapFeedUrl = 'http://maps.google.com/maps/feeds/maps/default/owned';
service.getMapFeed(mapFeedUrl, function(feedRoot) {
var feed = feedRoot.feed;
var entries = feed.getEntries();
for (var i = 0; i < entries.length; i++) {
var entry = entries[i];
var mapTitle = entry.getTitle().getText();
var listItem = document.createElement('li');
var listText = document.createTextNode(mapTitle);
listItem.appendChild(listText);
list.appendChild(listItem);
}
document.body.appendChild(list);
}, errorHandler);
}
Retrieving a Map
If a map's URL is known, it can be requested directly by calling getMapEntry() on the MapsService object. A
single map's URL has the following structure:
http://maps.google.com/maps/feeds/maps/userID/full/mapID
The URL of a specific map can be obtained from a feed of all maps by calling getSelfLink().getHref() on an
entry:
service.getMapFeed(mapFeedUrl, function(feedRoot) {
var feed = feedRoot.feed;
var entries = feed.getEntries();
for (var i = 0; i < entries.length; i++) {
var entry = entries[i];
if (entry.getTitle().getText() == "Roadtrip 2009") {
mapUrl = entry.getSelfLink().getHref();
}
}
}, errorHandler);
…google.com/…/developers_guide_jav… 7/16
5/3/2010 Developer Guide: JavaScript - Google …
Note that the MapEntry object returned by the getMapEntry() method is identical to that returned within a
getMapFeed() feed.
The following example retrieves a map entry and prints its title as an h1 element on the page.
service.getMapEntry(mapUrl, function(entryRoot) {
var entry = entryRoot.entry;
var mapTitle = entry.getTitle().getText();
Creating a Map
To create a new map, call insertEntry() on the map feed. A title and a summary must be specified; all other
properties are optional. The example below creates a new map with the title 'Roadtrip 2009' and inserts it into the
user's feed.
function addMap() {
Updating a Map
A map's fields can be updated by calling updateEntry() on the map object. updateEntry() must be passed a
function to be called upon successful update, and a function to be called if the update is unsuccessful.
function updateMap() {
service.getMapEntry(mapUrl, function(entryRoot) {
var entry = entryRoot.entry;
var newTitle = new google.gdata.atom.Text();
newTitle.setText('An updated title');
entry.setTitle(newTitle);
entry.updateEntry(loadMaps, errorHandler);
}, errorHandler);
}
…google.com/…/developers_guide_jav… 8/16
5/3/2010 Developer Guide: JavaScript - Google …
Deleting a Map
To delete a map, call deleteEntry() on the MapsService. Provide the URL of the map to be deleted, a function
to be called when the deletion has succeeded, and a function to call if the deletion is not successful.
function deleteMap(i) {
Caution: Deleting a map also deletes all features associated with that map. There is no way to retrieve a map or its
features once the map has been deleted.
Features
Features are the objects that appear on a map. Each feature within the Maps Data API is defined by a single KML
<Placemark> element; the Placemark must contain a name element and one of the following elements:
<Point>
<LineString>
<Polygon>
All other KML elements are silently removed when the KML is uploaded.
To obtain the URL of a map's feature feed, call getContent().getUri() on a map entry:
var featureFeedUrl;
service.getMapEntry(mapUrl, function(entryRoot) {
var entry = entryRoot.entry;
…google.com/…/developers_guide_jav… 9/16
5/3/2010 Developer Guide: JavaScript - Google …
featureFeedUrl = entry.getContent().getUri();
}, errorHandler);
service.getFeatureFeed(featureFeedUrl, function(feedRoot) {
Retrieving a Feature
Individual features can be retrieved with their identifying URLs. The URL can be obtained from a map's feature feed by
calling getSelfLink().getHref() on the feature entry:
var featureUrl;
service.getFeatureFeed(featureFeedUrl, function(feedRoot) {
var feed = feedRoot.feed;
var entries = feed.getEntries();
…google.com/…/developers_guide_jav… 10/16
5/3/2010 Developer Guide: JavaScript - Google …
Once a feature's URL is known, call getFeatureEntry() on the MapsService object. getFeatureEntry()
takes three parameters:
the URL of the feature to retrieve
a function to call upon success, and
a function to call if the retrieval is unsuccessful.
service.getFeatureEntry(featureUrl, function(featureRoot) {
var entry = featureRoot.entry;
var title = entry.getTitle().getText();
var content = entry.getContent().getText();
}, errorHandler);
Creating a Feature
Features are created by passing a FeatureEntry object to insertEntry() on the feature feed. To create the
entry:
Create a new google.gdata.maps.FeatureEntry object.
Pass the feature's title to setTitle() on the FeatureEntry object.
Create a new google.gdata.maps.KmlContent object.
Pass the feature's KML as a string to setText() on the KmlContent object.
Call setType() on the KmlContent object, specifying
TYPE_APPLICATION_VND_GOOGLE_EARTH_KML_XML.
Set the KmlContent object as the feature entry's content using setContent().
service.getFeatureFeed(featureFeedUrl, function(feedRoot) {
var newFeature = new google.gdata.maps.FeatureEntry();
kmlContent.setType(google.gdata.maps.KmlContent.TYPE_APPLICATION_VND_GOOGLE_EARTH_KML_XML
);
Updating a Feature
…google.com/…/developers_guide_jav… 11/16
5/3/2010 Developer Guide: JavaScript - Google …
A feature can be updated by calling updateEntry() on the feature entry after the object has been updated.
updateEntry() takes a function to call upon successful update, and a function to be called if the update fails.
service.getFeatureEntry(featureLink, function(featureRoot) {
var entry = featureRoot.entry;
var name = new google.gdata.atom.Text();
name = 'Roadtrip 2009, updated';
entry.setTitle(name);
entry.updateEntry(function() {window.location.reload()}, errorHandler);
}, errorHandler);
Example
The following example uses the content of a form (whose textarea element has the name formInput) to update
a feature entry.
kmlContent.setType(google.gdata.maps.KmlContent.TYPE_APPLICATION_VND_GOOGLE_EARTH_KML_XML
);
entry.setContent(kmlContent);
entry.updateEntry(function() {window.location.reload()}, errorHandler);
}, errorHandler);
}
Deleting a Feature
To delete a feature, call deleteEntry() on the feature entry, passing a function to be called upon successful
deletion of the feature, and a function to be called if the deletion is unsuccessful.
service.getFeatureEntry(featureLink, function(featureRoot) {
var entry = featureRoot.entry;
entry.deleteEntry(function() {
document.getElementById('app_status').innerHTML = 'Feature deleted';
…google.com/…/developers_guide_jav… 12/16
5/3/2010 Developer Guide: JavaScript - Google …
}, errorHandler);
}, errorHandler);
Access control is accomplished using the google.gdata.acl class. Each map has one ACL feed, containing one
or more ACL entries. Each entry specifies a scope and a role; the scope defines the user affected, and the role defines
their access level. All feeds contain an entry for the default scope, which applies to all users without their own entry.
appender - Add -
default Explicitly grants a user the same role as is granted the default scope.
none Assigning a role of none to a user will remove that user's ACL entry.
Retrieving an ACL
A map's ACL can be retrieved with its unique URL. This URL can be inferred from the map entry's id property, as
follows:
getAclFeed() takes the ACL feed URL, a function to be called upon successful retrieval, and an error handler.
Upon success, getAclFeed() passes a feedRoot object to the continuation function.
…google.com/…/developers_guide_jav… 13/16
5/3/2010 Developer Guide: JavaScript - Google …
function continuation_func(feedRoot) {
var aclEntries = feedRoot.feed.getEntries();
for (var i = 0; i < aclEntries.length; i++) {
var aclEntry = aclEntries[i];
}
function retrieveAclEntry(aclFeedURL) {
var aclEntryURL = aclFeedURL +
'/user%3Ajohn%40gmail.com'; // URL-encoded scope_type:scope_value
service.getAclEntry(aclEntryURL, showAclEntry, errorHandler);
}
function showAclEntry(entryRoot) {
var entry = entryRoot.entry;
var scopeType = entry.getScope().getType();
var scopeValue = entry.getScope().getValue();
var roleValue = entry.getRole().getValue();
alert(scopeType + '\n' + scopeValue + '\n' + roleValue);
}
function addAclEntry() {
var entry = new google.gdata.acl.AclEntry();
…google.com/…/developers_guide_jav… 14/16
5/3/2010 Developer Guide: JavaScript - Google …
}
function showNewEntryURL(entryRoot) {
var entry = entryRoot.entry;
var aclEntryURL = entry.getSelfLink().getHref();
alert(aclEntryURL);
}
Only the role value of an entry can be changed; scope can not be updated.
function changeRole(aclEntry) {
var role = aclEntry.getRole();
role.setValue('appender');
aclEntry.setRole(newRole);
aclEntry.updateEntry(displayNewRole, errorHandler);
}
function displayNewRole(entryRoot) {
var entry = entryRoot.entry;
var role = entry.getRole().getValue();
alert(role);
}
deleteEntry() will pass the deleted entry's entryRoot object to the continuation function.
function deleteAclEntry(entry) {
entry.deleteEntry(notifyDeleted, errorHandler);
}
function notifyDeleted(entryRoot) {
var entry = entryRoot.entry;
alert("The " + entry.getScope().getValue() +
" scope has been deleted.");
}
Debugging
A JavaScript debugger is highly recommended while developing. Some free debuggers include Firebug for Firefox,
Microsoft Script Debugger for IE, and the built-in tools in Safari and Google Chrome.
Many methods call for an error handler function as a parameter. If an error occurs when calling one of these methods,
the browser's Error object will be passed to your specified error handler. If the error is from an HTTP response, it will
include a cause parameter. You can use the information from the Error object to help troubleshoot your application.
function errorHandler(e) {
…google.com/…/developers_guide_jav… 15/16
5/3/2010 Developer Guide: JavaScript - Google …
var errorDiv = document.createElement('div');
document.body.appendChild(errorDiv);
if (e instanceof Error) {
errorDiv.innerHTML = 'Error on line ' + e.lineNumber + ' in ' + e.fileName
+ '\nMessage: ' + e.message;
if (e.cause) {
errorDiv.innerHTML = errorDiv.innerHTML + '<br />Root cause: HTTP error '
+ e.cause.status + ': ' + e.cause.statusText;
}
} else {
alert(e.toString());
}
}
More Resources
More information about the Google Maps Data API and/or the Google Data JavaScript client is available from the
following sources:
The Google Maps Data API group on Google Groups
The Google Data JavaScript Client group on Google Groups
The gdata-javascript-client project on Google Code.
©2010 Google - Code Home - Terms of Service - Privacy Policy - Site Directory
Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
…google.com/…/developers_guide_jav… 16/16