Getting Started

Using the Tileset API requires the following:

• A Google user account used that is associated with your Cloud instance
• An appropriate Authentication scheme, used for validating permissible operations
• A means to initiate HTTP GET,PUT, POST and DELETE requests
• A browser or text editor to inspect data

The following sections describe these concepts in detail.

Authentication using Google Accounts

Each Tileset is associated with an ACL list of Google Accounts. Each list contains rolls for reading and writing data to the resource. The Default Site ACL allows all authenticated users to read and only admins to write. An ACL can also be set to allow anonymous access (no Google Account) but in most cases you should be tracking who is writing to your Cloud.

You can authenticate using either of two approaches:

• ClientLogin username/password authentication
• ProxyLogin username/password authentication

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 Google AppEngine service name (ah). (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 Datasource API, using the following format:

 
Cookie: ACSID=yourAuthToken 

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

Proxy Login username/password Authentication

You can log directly to your Cloud instance using your Google Account without having to use the ClientLogin authentication described above. When you use the proxy login, your Cloud instance calls the appropriate Google ClientLogin url in the background and returns an opaque token that you can use on your urls. Your Google username and password are not stored and the Proxy must be used via secure https. The token will timeout based on the timespan the administator has set (the default value is one day)

Google's LoginClient is the preferred method for obtaining access to your Cloud but Proxy is a good alternative when subsequent client requests cannot set the authorization header. For instance, Google Earth KML NetworkLinks will not set any custom headers so secure access to dynamic KML resources can be accomplished by appending the proxy token to the urls (http://anyurl?token=tokenFromProxy)

In all of the following examples, the Google ClientLogon ACSID cookie header is used but you could change all of them to use the proxy login token inthe url iteself instead.

 
https://yourInstance.appspot.com/services/getToken 

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:

credentials

The Username and Password of your account separated by the bar ("|") username|password.

 
Usage Example:
GET http://yourInstance.appspot.com/a2e/data/tilesets/tilesetName/10/10000/10000.png?token=tokenFromProxy

Authentication using OpenID

coming soon...

Tileset API

The Tileset API allows users to create and manage set map tile caches. A tile cache is collection of map images that are drawn and cut to conform to the mapping grid used by Google Maps, Microsoft Bing and other large online map providers. Each cache is made up of levels (0-22) and each level contains the associated map images.

Get a List of All Tilesets

Get a List of All Tilesets

GET http://yourInstance.appspot.com/a2e/data/tilesets?f=json&acl=true
Cookie: ACSID=yourAuthToken 

Get Tileset

Get information about a single Tileset

GET http://yourInstance.appspot.com/a2e/data/tileset/YourTilesetname?f=json&acl=true
Cookie: ACSID=yourAuthToken 

Map Tiles

Map Tiles can be accessed using either the Google Maps or Microsoft Bing naming conventions.

Add Tileset

Add Tileset - Create a new tileset using the passed unique id.

PUT http://yourInstance.appspot.com/a2e/data/datasources?id=new_tileset_name
Cookie: ACSID=yourAuthToken 

 
Response: 201
{
"status": 201, 
"message": "Tileset 'newTS' created", 
"result": 
{
}
}

Errors:
401 - Forbidden
409 - Tileset already exists
400 - Invalid parameter

Delete Tileset

Delete Tileset and all associated tiles

DELETE http://yourInstance.appspot.com/a2e/data/datasources/tileset_name
Cookie: ACSID=yourAuthToken 

 
Response: 200
{
{"status": 200, "message": "Tileset 'tsName' deleted"}
}

Errors:
401 - Forbidden
404 - Tileset doesn't exist

Bulk Upload Tiles

Upload groups of individual map tiles into a newly created or existing Tileset. The tile image must added a standard gzip archive and the name of each tile must be the level, x and y grids values (ex: 10_105100_100200). The file name, in grid format, is used to save the tile image as a unique blob entry in the AppEngine datastore so the values must be exact. If you upload tiles with matching names, the last tile to be saved will be the only tile at that location. For maximum efficiency, upload files in groups of 20 tiles with up to 10 concurrent loaders.

You can also use the Arc2Earth Command Line tools (A2EExporter.exe) to upload any existing tile cache that has a standard folder layout (level\x\y). For more information, see the Command Line documentation

POST http://yourInstance.appspot.com/a2e/data/datasources/tileset_name/upload
Cookie: ACSID=yourAuthToken
File:Content-Type: multipart/form-data; 

example:
Content-Disposition: form-data; name="file"; filename="1dd5b1c7-3c14-41c4-a7bb-ee2948e525c7.zip"
Content-Type: application/octet-stream

 
Response: 200
{
{"status": 200}
}

Errors:
401 - Forbidden
404 - Tileset doesn't exist

Static Map API

Static Maps are single images that are composed of several map tiles in one call to the server. They are good for simple websites where youwould like to show just an image of a parcel or from mobile applications where you need to display map overlays but cannot use multiple tiles (ex: Google Maps V3 api)

Example Usage

Example 1: Zoning Map at specific lat/lng value, no opacity
http://demos-arc2earth.appspot.com/a2e/data/tilesets/Westfield_Parcels/staticmap?&f=image¢er=40.6556387401,%20-74.35546875&dl=true&zoom=16&size=300,300&transparent=true&opacity=1&bl=

Example 2: Same Zoning Map with 0.7 opacity and Google Streets as the background layer
http://demos-arc2earth.appspot.com/a2e/data/tilesets/Westfield_Parcels/staticmap?&f=image¢er=40.6556387401,%20-74.35546875&dl=true&zoom=16&size=300,300&transparent=true&opacity=0.7&bl=gs

Example 3: Property Class Map with specific parcel selected
http://demos-arc2earth.appspot.com/a2e/data/tilesets/Westfield_Parcels_PCC/staticmap?&f=image¢er=Westfield_Parcels:3009&dl=true&zoom=17&size=300,300&transparent=true&opacity=0.7&bl=gs

Example 4: Property Class Map in Json format
http://demos-arc2earth.appspot.com/a2e/data/tilesets/Westfield_Parcels/staticmap?&f=json¢er=40.6556387401,%20-74.35546875&dl=true&zoom=17&size=300,300&transparent=true&opacity=0.7&bl=bs