My favorites | English | Sign in

Faster JavaScript with Closure Tools New!

Google Maps Data API (Labs)

Developer Guide: HTTP Protocol

The Maps Data API allows client applications to view and update maps (and features on those maps) through the use of Google Data API feeds. These feeds are provided as URLs using the popular Atom standard. You programmatically create, alter and delete data using HTTP requests.

In addition to providing some background on the capabilities of the Maps Data API, this document provides a conceptual overview of Data API interactions using "raw" XML and HTTP operations.

In practical usage, you will likely not use raw HTTP request to perform these operations. As a result, we've provided client libraries for the Maps Data API in Java and JavaScript, which you can use in the development of your applications. You can learn more about interacting with the API using these client libraries by reading the programming-language-specific sections of this developer's guide.

Contents

  1. Audience
  2. Getting Started
    1. Creating a Maps Data API Account
    2. Authenticating to the Maps Data API Service
      1. AuthSub Proxy Authentication
      2. ClientLogin Authentication
  3. Retrieving a List of Maps
  4. Maps
    1. Retrieving Maps
    2. Creating Maps
    3. Updating Maps
    4. Deleting Maps
  5. Map Features
    1. Retrieving Map Features
    2. Creating Map Features
    3. Updating Map Features
    4. Deleting Map Features

Audience

This document is intended for programmers who want to write client applications that can interact with Google Maps Data API using XML and HTTP. Users who are using a client library instead of HTTP may also find this document helpful for a basic understanding of how the Maps Data API works "under the hood."

This document assumes that you understand the general ideas behind the Google Data APIs protocol, and that you're familiar with KML, Google Maps, and how data is typically presented on Google Maps.

If you're using a UNIX system and you want to try initiating requests in this document without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.

For Maps Data API reference information, consult the HTTP Protocol Reference. That document contains a complete reference of all HTTP operations provided by the Maps Data API. Each supported client library also has an associated reference as well.

Getting Started

Using the Maps Data API requires the following:

  • A Google user account, used for associating your data
  • An appropriate Authentication scheme, used for validating permissible operations
  • A means to initiate HTTP GET,PUT, POST and DELETE requests
  • A browser or XML editor to inspect data

The following sections describe these concepts in detail.

Creating a Maps Data API Account

Maps are stored and associated with user IDs attached to a Google Account. If you do not currently have a Google account, sign up for one here.

The Maps Data API manipulates maps which appear within the MyMaps feature on Google Maps. MyMaps includes two types of maps: Public, and Unlisted. A sample MyMap is shown below:


You can use MyMaps within your browser to inspect the state of your map after data updates. Additionally, if you create Public maps, these will be indexed and may show up in search results. Note that you do not need to use MyMaps to present your data. Any application that can present KML is an appropriate "browser" for data returned by the Maps Data API.

Authenticating to the Maps Data API Service

You may only access your own maps using the Maps Data API. You must authenticate to read private maps within a maps feeds. It can authenticate using either of two approaches:

Note: Map feeds which contain both public and unlisted maps are denoted as private map feeds within this document.

For more information about authentication with Google Data APIs in general, see the authentication documentation.

AuthSub Proxy Authentication

AuthSub Proxy Authentication is used by web applications that need to authenticate to a (Google Account) user's data. Rather than authenticating directly, applications using AuthSub will first make an AuthSub HTTP request for a particular user's data. This request will trigger a notification to the user, who can either approve or deny the request. If approved, the AuthSub service generates an authentication token which the web application can use for authentication purposes.

The AuthSub authentication mechanism allows Maps Data API users to grant access to web applications without needing to provide the third-party with username or password details. Tokens may be provided for single-usage or as "session" tokens, which don't expire. Additionally, secure tokens may also be generated, though only for applications which are registered with Google and have a security certificate on file.

For more detailed information, see the AuthSub documentation.

When a user first visits your application, they have not yet been authenticated. You should display appropriate information alerting them of this and provide a link to the Google AuthSubRequest URL:

https://www.google.com/accounts/AuthSubRequest

An AuthSub is initiated via an AuthSubRequest request URL with the following parameters:

next
URL of the page to which Google should redirect the user after authentication. (This parameter should be URL-encoded.)
scope
URL identifying the service to be accessed. For Maps Data feeds, this URL is http://maps.google.com/maps/feeds/. (This parameter should be URL-encoded.)
session
Boolean flag indicating whether the one-time-use token may be exchanged for a session token (1) or not (0).
secure
Boolean flag indicating whether the authentication transaction should issue a secure token (1) or a non-secure token (0). Secure tokens are available to registered applications only.

A typical Maps Data API AuthSubRequest URL might look like this:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fmaps.google.com%2Fmaps%2Ffeeds%2Fmaps%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

Note that this URL is URL-encoded. For more information about URL encoding, see http://en.wikipedia.org/wiki/Percent-encoding.

Once the user authenticates, the AuthSub system will redirect them to the URL you specified in the next query parameter of the AuthSubRequest URL. The AuthSub system appends an authentication token to that URL, as the value of the token query parameter. For example:

http://www.example.com/welcome.html?token=yourAuthToken

Since all requests to private map feeds require authentication you must set an Authorization header in all subsequent interactions with the Maps Data API, using the following format:

Authorization: AuthSub auth=yourAuthToken

For complete information about AuthSub authentication, consult the AuthSub Authentication for Web Applications documentation.

ClientLogin username/password Authentication

ClientLogin authentication uses more traditional username/password requests to authenticate an application. Typically, this authentication scheme is useful for standalone, single-user clients (such as a desktop application). ClientLogin is also useful for testing purposes. The ClientLogin scheme generates an authentication token so that future actions can reference the token rather than require further username/password authentications. Additionally, ClientLogin authentication can be extended to use CAPTCHAs™ or other enhancements.

To request an authentication token using the ClientLogin mechanism, send a secure HTTP (HTTPS) POST request to the ClientLogin URL:

https://www.google.com/accounts/ClientLogin

The POST body must be constructed as a form post with default encoding application/x-www-form-urlencoded. The body of the POST request should specify the set of query parameters:

accountType
Type of account to be authenticated. The default is GOOGLE; if you want to support Google Apps for Your Domain users, use HOSTED_OR_GOOGLE.
Email
The user's email address.
Passwd
The user's password.
service
The Maps Data API service name (local). (For other service names, see the service name list.)
source
Short name identifying your client application, used for logging purposes. This string should take the form companyName-applicationName- versionID.

Upon successful authentication, the server returns an HTTP 200 OK status code, plus three alphanumeric codes in the body of the response: SID, LSID, and Auth. The Auth value contains the authorization token that you'll use to authenticate to the Maps Data API on subsequent maps-feed requests. (You can ignore the SID and LSID values.)

Since all requests to private map feeds require authentication you must set an Authorization header in all subsequent interactions with the Maps Data API, using the following format:

Authorization: GoogleLogin auth=yourAuthToken

For more information about ClientLogin authentication, including sample requests and responses, see the Authentication for Installed Applications documentation.

Retrieving a List of Maps

The Maps Data API provides a feed that lists the maps created by a particular user; this feed is known as a "metafeed". A typical Maps Data API metafeed is a GET request of the following form:

#
# The default feed requests all maps associated with the authenticated user
#
GET http://maps.google.com/maps/feeds/maps/default/full
Authorization: GoogleLogin auth="authorization_token"
#
# The standard metafeed requests all maps associated with the 
# associated userID
#
GET http://maps.google.com/maps/feeds/maps/userID/full
Authorization: GoogleLogin auth="authorization_token"

Note that both GET requests require an Authorization HTTP header, passing an AuthSub or GoogleLogin token, depending on which authentication scheme you've implemented. (The GoogleLogin token corresponds to the ClientLogin authentication process.)

The default metafeed requests all maps created by the user associated with the passed authentication token. (Additionally the default metafeed is useful for determing your userID, which is included in the response.)

The standard metafeed returns all feeds associated with a given userID. If the userID matches your authentication token, all private, public and unlisted maps will be returned. This userID is a unique token associated with your Google account username and is returned by the default metafeed noted above.

The metafeed request generates an XML response that looks like the following: 

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'>
  <id>
  http://maps.google.com/maps/feeds/maps/userID/full</id>
  <updated>2009-04-15T18:46:47.269Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
  term='http://schemas.google.com/maps/2008#map' />
  <title type='text'>My maps</title>
  <link rel='alternate' type='text/html'
  href='http://maps.google.com/maps/ms?msa=1' />
  <link rel='http://schemas.google.com/g/2005#feed'
  type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/maps/userID/full' />
  <link rel='http://schemas.google.com/g/2005#batch'
  type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/maps/userID/full/batch' />
  <link rel='http://schemas.google.com/g/2005#post'
  type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/maps/userID/full' />
  <author>
    <name>Tom</name>
  </author>
  <openSearch:totalResults>3</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>3</openSearch:itemsPerPage>
  +<entry>
  +<entry>
  +<entry>
  ...
</feed>

The XML response contains an <id> element which defines the metafeed for this user account. Within that URL is the requestor's userID which you can use within additional requests. (You can also use the explicit Google account email address associated with this user in place of this userID.

The XML response also contains <entry> elements for each map available for access by the authenticated user. These <entry> elements only contain meta information about the map; they do not contain specific feature information about maps. You will need to request specific information about a map to gain a full listing of features attached to the map. (See Retrieving Features below.)

Additionally the response contains several link elements:

  • #feed which defines the full maps metafeed
  • #batch which defines a URL for batch processing
  • #post which defines a URL for POST new map elements

Note: if you request a feed for a non-authenticated user (i.e. not yourself), you will not receive a #post feed URL.

Each <entry> also contains a number of elements that contain more information about a specific map. A sample entry returned by the metafeed is shown below:

 <entry>
    <id>
    http://maps.google.com/maps/feeds/maps/userID/full/elementID</id>
    <published>2009-04-14T05:36:43.283Z</published>
    <updated>2009-04-14T05:41:44.564Z</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
    2009-04-16T20:45:16.072Z</app:edited>
    <app:control xmlns:app='http://www.w3.org/2007/app'>
      <app:draft>yes</app:draft>
    </app:control>
    <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/maps/2008#map' />
    <title type='text'>Bike Ride, 10 Years Old</title>
    <summary>This was my first long trip on a bicycle
    that I remember as a child.</summary>
    <content src='http://maps.google.com/maps/feeds/features/userID/elementID/full'/>
    <link rel='self' type='application/atom+xml'
    href='http://maps.google.com/maps/feeds/maps/userID/full/elementID' />
    <link rel='edit' type='application/atom+xml'
    href='http://maps.google.com/maps/feeds/maps/userID/full/elementID' />
    <author>
      <name>Tom</name>
    </author>
  </entry>

Note that each entry contains:

  • An <id> element containing a URL used to specify this particular entry (map).
  • Additional meta information for date of publication and modification
  • A <title> and <summary> element, which correspond to the title and description entered within the My Maps editor.

  • <link> elements containing URLS for performing operations on this map:

    • self for requesting this information on this element. This feed simply returns the entry you see here.
    • edit for PUT requests to update information in this element
  • <author> and <name> elements describing the author of this map.
  • A <content> element whose src attribute specifies the feed for retrieving the full list of features for this map.

Note that the map entry does not itself describe any of its feature content (markers, polylines,polygons, etc.) To retrieve that additional information, you will need to request a feature feed on a map. (See Requesting Features below.)

For complete information about these elements, consult the Maps Data API feed elements reference guide, Google Data APIs Protocol Reference document, or the Atom 1.0 specification.

Additional Metafeeds

In addition to http://maps.google.com/maps/feeds/maps/default/full, which retrieves all feeds associated with a given user, the following subsets are available:

  • http://maps.google.com/maps/feeds/maps/default/owned returns all maps created by the user
  • http://maps.google.com/maps/feeds/maps/default/public returns all public maps created by the user
  • http://maps.google.com/maps/feeds/maps/default/unlisted returns all unlisted maps created by the user

Maps

The fundamental <entry> within a Maps Data API feed is an instance of a map. Using the Maps Data API, you may perform the following operations on maps:

  • Retrieving Individual Maps
  • Creating New Maps
  • Updating Map Information
  • Deleting Maps

Each of these operations is discussed in the following sections.

Retrieving a Map

To retrieve a map, simply initiate a GET request to the self URL specified within the map's entry.

GET http://maps.google.com/maps/feeds/maps/userID/full/mapID
Authorization: GoogleLogin auth="authorization_token"

Upon success, the server responds:

200 OK

<?xml version='1.0' encoding='utf-8'?>
 <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:batch='http://schemas.google.com/gdata/batch'
    xmlns:gd='http://schemas.google.com/g/2005'>
    <id>
    http://maps.google.com/maps/feeds/maps/userID/full/elementID</id>
    <published>2009-04-14T05:36:43.283Z</published>
    <updated>2009-04-14T05:41:44.564Z</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
    2009-04-16T20:45:16.072Z</app:edited>
    <app:control xmlns:app='http://www.w3.org/2007/app'>
      <app:draft>yes</app:draft>
    </app:control>
    <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/maps/2008#map' />
    <title type='text'>Bike Ride, 10 Years Old</title>
    <summary>This was my first long trip on a bicycle
    that I remember as a child.</summary>
    <content src='http://maps.google.com/maps/feeds/features/userID/elementID/full' />
    <link rel='self' type='application/atom+xml'
    href='http://maps.google.com/maps/feeds/maps/userID/full/elementID' />
    <link rel='edit' type='application/atom+xml'
    href='http://maps.google.com/maps/feeds/maps/userID/full/elementID' />
    <author>
      <name>Tom</name>
    </author>
  </entry>

Note that this entry is identical to the entry returned within the full maps metafeed. Generally, you either use the maps metafeed or GET a specific map, but there's usually not a reason to do both.

Creating Maps

Authenticated applications can publish new maps by using the metafeed's #post URL.

To create a new map, first create an XML representation of the map to publish. This XML needs to be in the form of an Atom <entry> element, which typically looks like this:

<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Bike Ride, 10 Years Old</title>
  <summary></summary>
</entry>

To publish this entry, send the XML file to the map's post URL as follows:

  1. First, place your Atom <entry> element in the body of a new POST request, using the application/atom+xml content type. Make sure to declare xmlns="http://www.w3.org/2005/Atom" as the default namespace.

  2. Second, find the map's POST URL in the metafeed by locating the <link> element which contains s rel attribute ending with #post.This post URL is of this format:

    http://maps.google.com/maps/feeds/maps/userID/full

  3. Initiate the POST request as follows:

    POST http://maps.google.com/maps/feeds/maps/userID/full
Content-type: application/atom+xml
Authorization: GoogleLogin auth="authorization_token"

<entry xmlns="http://www.w3.org/2005/Atom">
  <title>My Map</title>
  <summary>My Description</summary>
</entry>

    4. The Maps Data API creates a map using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new map in the form of an <entry> element. The entry returned is the same one you sent, but also contains various elements added by Maps Data API, such as an <id> element and creation information.

    If your request fails for some reason, the Maps Data API may return a different status code. For information about the status codes, see the Google Data API protocol reference document.

    Updating Maps

    To update an existing map, first retrieve the entry you want to update, modify its XML, and then send a PUT request to the map's edit URL, passing the updated XML. Be sure to set the application/atom+xml content type within the PUT request's header. Also ensure that the <id> value in the entry you PUT exactly matches the <id> of the existing entry.

    In the following example, we simply change the map's description:

    PUT http://maps.google.com/maps/feeds/maps/userID/full/mapID
Content-type: application/atom+xml
Authorization: GoogleLogin auth="authorization_token"

<entry xmlns="http://www.w3.org/2005/Atom">
  <title>My Map</title>
  <summary>My newly Revised and Updated 
  Description</summary>
  <author>
    <name>Tom</name>
  </author>
</entry>

    Troubleshooting Tip: Some firewalls block HTTP PUT requests. As a workaround, you can include a X-HTTP-Method-Override: PUT header in a POST request. For details, see the Google Data API protocol basics document.

    Deleting Maps

    To delete a map, send a DELETE request to the map's edit URL. This is the same URL used to update a map.

    DELETE http://maps.google.com/maps/feeds/maps/userID/full/mapID
Authorization: GoogleLogin auth="authorization_token"

    Troubleshooting Tip: Some firewalls block HTTP DELETE messages. To get around this, you can include a X-HTTP-Method-Override: DELETE header in a POST request. For details, see the Google Data API protocol basics document.

    Note: To update existing maps, see Updating Maps; don't update maps by deleting and then re-adding them.

    Map Features

    So far, we have only discussed maps, but we haven't discussed the things we want to put on maps: markers, lines, shapes, etc. These elements are known as features in the Maps Data API. Each map contains a feature feed which returns a list of the features attached to a map. You may then add, modify, or delete features using this feed.

    This chapter discusses the feature feed, what makes up a feature in the Maps Data API, and how to perform the following functions:

    • Retrieving Individual Features
    • Creating New Features
    • Updating Features
    • Deleting Features

    Feature Feeds

    A map's feature feed is published in the map's <content> tag within its src attibute. The feature feed not only contains a userID but also a mapID of the map in question. To retrieve the feature feed for a particular map, send a GET request to this URL:

    GET http://maps.google.com/maps/feeds/features/userID/mapID/full
Authorization: GoogleLogin auth="authorization_token"

    Upon success, a feature feed will return containing information about the map in question and a list of <entry> elements for each feature.

    <?xml version='1.0' encoding='utf-8'?>
<atom:feed xmlns='http://www.opengis.net/kml/2.2'
    xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
    xmlns:batch='http://schemas.google.com/gdata/batch'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"ETag"'>
  <atom:id>
  http://maps.google.com/maps/feeds/features/userID/mapID/full</atom:id>
  <atom:updated>2009-04-16T18:31:57.271Z</atom:updated>
  <atom:category scheme='http://schemas.google.com/g/2005#kind'
  term='http://schemas.google.com/maps/2008#feature' />
  <atom:title type='text'>Bike Ride, 10 Years Old</atom:title>
  <atom:link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/features/userID/mapID/full' />
  <atom:link rel='self' type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/features/userID/mapID/full' />
  <atom:link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/features/userID/mapID/full/batch' />
  <atom:link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/features/userID/mapID/full' />
  <atom:link rel='next' type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/features/userID/mapID/full?previd=featureID' />
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1</openSearch:itemsPerPage>
  +<atom:entry>
  +<atom:entry>
  +<atom:entry>
  ...
</atom:feed>

    There are several things to notice about this feed:

    • It has a default namespace for KML. This allows you to retrieve and modify KML without needing to namespace the KML entities individually. (For example as <kml:Placemark> elements.)
    • The <id> consists of a URL containing both a userID and the mapID of the corresponding map entry in the Maps Data API metafeed. This is the same URL as that displayed in the maps metafeed for the map in question.

    • It contains a set of links for performing the following operations:

      • #feed which defines the full feature feed for this map
      • #batch which defines a URL for batch processing.
      • #post which defines a URL for POSTing of new feature elements
      • self which identifies this feed. This feed is identical to #feed above.
      • next which identifies the last element in this feature feed.
    • It contains a set of <entry> elements for each feature contained within the map. These features consist of KML within each <entry>'s content tag.

    KML Features

    Features are added to maps as KML Placemarks within the feature's <content>. Since KML is already an XML language it does not need to be escaped within the feature XML.

    Currently each feature maps to one (and only one) <Placemark> of the following types:
    • <Point>
    • <LineString>
    • <Polygon>

    Additionally, <Placemark>s may contain <Style> elements of the following types:

    • <IconStyle> for <Point> elements
    • <LabelStyle>
    • <LineStyle> for <LineString> elements
    • <PolyStyle> for <Polygon> elements

    Additionally, the <Placemark> may contain the following additional elements:

    • An <atom:author> to denote the author of a feature. This allows you to create community maps, for example, where features have different authors than the underlying map.
    • An <atom:link> element containing a client-supplied URL to be indexed in search results, if the feed is public.
    • A <kml:address> element to contain the unstructured (human-readable) address of this feature.

    At this time, the Maps Data API does not support the full KML specification (including elements not noted above, or nested folder operations), and does not support multiple <Placemark> elements within one feature. (Adding multiple <Placemark>s will generate an error.) We intend to add more KML support in the future.

    Retrieving Features

    To retrieve a specific feature, simply initiate a GET request to the self URL specified within the feature's entry.

    GET http://maps.google.com/maps/feeds/maps/userID/mapID/full/featureID
Authorization: GoogleLogin auth="authorization_token"

    Upon success, the server responds:

    200 OK

<atom:entry xmlns='http://www.opengis.net/kml/2.2'
    xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:batch='http://schemas.google.com/gdata/batch'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <atom:id>
  http://maps.google.com/maps/feeds/features/userID/mapID/full/featureID</atom:id>
  <atom:published>2008-08-14T17:46:06.462Z</atom:published>
  <atom:updated>2008-08-14T18:12:31.589Z</atom:updated>
  <atom:category scheme='http://schemas.google.com/g/2005#kind' 
  term='http://schemas.google.com/maps/2008#feature' />
  <atom:title type='text'  >East River Line</atom:title>
  <atom:content type='application/vnd.google-earth.kml+xml'>
    <Placemark xmlns="http://www.opengis.net/kml/2.2">
      <name>East River Line</name>
      <description>
        <![CDATA[A streetcar proposal for New York's Brooklyn and Queens
        waterfront]]>
      </description>
      <Style>
        <LineStyle>
          <color>73FF0000</color>
          <width>5</width>
        </LineStyle>
      </Style>
      <LineString>
        <tessellate>1</tessellate>
        <coordinates>-73.872446,40.774481,0.0
        ...
        -74.005537,40.671329,0.0</coordinates>
      </LineString>
    </Placemark>
  </atom:content>
  <atom:link rel='self' type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/features/userID/mapId/full/featureID' />
  <atom:link rel='edit' type='application/atom+xml'
  href='http://maps.google.com/maps/feeds/features/userID/mapId/full/featureID' />
  <atom:author>
    <atom:name>Tom</atom:name>
  </atom:author>
  <atom:contributor>
    <atom:name>Tom</atom:name>
  </atom:contributor>
</atom:entry>

    This feature entry looks similar to a map entry but there are some differences.

    First, the elements within this entry generally contain an atom: namespace prefix with KML specified as the default namespace. This allows you to extract and replace KML without needing to preface the KML elements with a kml: namespace.

    Second, the <content> element has a type set to application/vnd.google-earth.kml+xml. You must use this content type when adding or updating feature elements.

    Third, the content consists of standard KML (which has been abbreviated for clarity).

    Note that this feature entry is identical to the feature entry returned within the full feature feed. Generally, you either use the feature feed or GET a specific feature, but there's usually not a reason to do both.

    Creating Features

    Authenticated applications can publish new features to maps by using the feature feed's #post URL.

    To create a new feature, first create an KML <Placemark> as noted above. This KML needs to be in the form of an Atom <entry> element, which typically looks like this:

    <atom:entry xmlns='http://www.opengis.net/kml/2.2'
    xmlns:atom='http://www.w3.org/2005/Atom'>
   <atom:title type='text'>Faulkner's Birthplace</atom:title>
   <atom:content type='application/vnd.google-earth.kml+xml'>
     <Placemark>
       <name>Faulkner's Birthplace</name>
       <description/>
       <Point>
         <coordinates>-89.520753,34.360902,0.0</coordinates>
       </Point>
     </Placemark>
   </atom:content>
</atom:entry>

    Note: KML presents geographic coordinates in the order of {longitude,latitude,elevation} which is different than the standard Maps API usage of {latitude,longitude}.

    To publish this feature entry, send the XML file to the map's post URL as follows:

    1. First, place your Atom feature <entry> element in the body of a new POST request, using the application/atom+xml content type. Note that you should declare the default namespace for KML and use atom: prefixes for the Atom namespace.

    2. Second, find the feature's POST URL in the feature feed by locating the <link> element which contains a rel attribute ending with #post.This post URL is of this format:

      http://maps.google.com/maps/feeds/features/userID/mapID/full

    3. Initiate the POST request as follows:

      POST http://maps.google.com/maps/feeds/features/userID/mapID/full
Content-type: application/atom+xml
Authorization: GoogleLogin auth="authorization_token"

<atom:entry xmlns='http://www.opengis.net/kml/2.2'
    xmlns:atom='http://www.w3.org/2005/Atom'>
   <atom:title type='text'>Faulkner's Birthplace</atom:title>
   <atom:content type='application/vnd.google-earth.kml+xml'>
     <Placemark>
       <name>Faulkner's Birthplace</name>
       <description/>
       <Point>
         <coordinates>-89.520753,34.360902,0.0</coordinates>
       </Point>
     </Placemark>
   </atom:content>
</atom:entry>

      4. The Maps Data API creates a new feature attached to the map using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new feature in the form of an <atom:entry> element. The entry returned is the same one you sent, but also contains various elements added by Maps Data API, such as an <atom:id> element and creation information.

      If your request fails for some reason, the Maps Data API may return a different status code. For information about the status codes, see the Google Data API protocol reference document.

      Updating Features

      To update an existing feature, first retrieve the feature entry you want to update, modify its XML, and then send a PUT request to the feature's edit URL, passing the updated XML. Be sure to set the application/atom+xml content type within the PUT request's header. Also ensure that the <id> value in the entry you PUT exactly matches the <id> of the existing feature.

      In the following example, we change the feature's description by adding some HTML within a CDATA element:

      PUT http://maps.google.com/maps/feeds/features/userID/mapID/full/featureID
Content-type: application/atom+xml
Authorization: GoogleLogin auth="authorization_token"

<atom:entry xmlns='http://www.opengis.net/kml/2.2'
    xmlns:atom='http://www.w3.org/2005/Atom'>
   <atom:title type='text'>Faulkner's Birthplace</title>
   <atom:content type='application/vnd.google-earth.kml+xml'>
     <Placemark>
       <name>Faulkner's Birthplace</name>
       <description>
         <![CDATA[
           <p><b>William Faulkner</b> adopted Oxford, Mississippi as his 
           hometown when his family moved to Oxford from nearby New Albany 
           when he was three.</p>    
         ]]>
       </description>
       <Point>
         <coordinates>-89.520753,34.360902,0.0</coordinates>
       </Point>
     </Placemark>
   </atom:content>
   <atom:author>
     <atom:name>Tom</name>
   </atom:author>
</atom:entry>

      IMPORTANT: To ensure forward compatibility, be sure that when you PUT an updated entry, you preserve all XML that was present when you retrieved the entry from Maps Data API. Otherwise, when we implement new functionality and include <new-awesome-feature> elements in the feed, your client won't return them and your users will miss out. The Google Data API client libraries all handle this correctly, so if you're using one of the libraries you're all set.

      Troubleshooting Tip: Some firewalls block HTTP PUT requests. As a workaround, you can include a X-HTTP-Method-Override: PUT header in a POST request. For details, see the Google Data API protocol basics document.

      Deleting Features

      To delete a feature, send a DELETE request to the feature's edit URL. This is the same URL used to update a feature.

      DELETE http://maps.google.com/maps/feeds/features/userID/mapID/full/featureID
Authorization: GoogleLogin auth="authorization_token"

      Troubleshooting Tip: Some firewalls block HTTP DELETE messages. To get around this, you can include a X-HTTP-Method-Override: DELETE header in a POST request. For details, see the Google Data API protocol basics document.

      Note: To update existing features, see Updating Features; don't update features by deleting and then re-adding them.