ArcGIS Server Link for Google Maps API: Concepts

Examples | Class References

This library provides access to ESRI's ArcGIS Server via it's REST API from Google Maps API. The main concepts of this library are:

• Broader Spatial Reference Support. It works with ALL ArcGIS Server services (v9.3 with REST enabled, square tiles if cached), not just those published in "Web Mercator".
• Two tier object model. It contains a set of classes that strictly follow the class design style and convention of the core GMap API, plus a set of classes that modeled closely to the REST Service resources and operations.

Google Maps API Extension Classes

For developers who are familiar with the core Google Maps API classes, this library can be considered as a collection of custom/extension classes to the core API that facilitates access to ArcGIS Server. You can accomplish many tasks by using only those subclasses. Several principles are used in the design:

• Use object literals in constructors as options.
• Use callback function in methods, not in constructors
• Use events to identify key steps in operations

The following table describes the classes in the core Google Maps API and their corresponding sub classes in this library.

Core Google Maps API Class	ArcGIS Link Class
GOverlay, GGroundOverlay	ArcGISMapOverlay
GTileLayer	ArcGISTileLayer
GTileLayerOverlay	ArcGISTileLayerOverlay
GMapType	ArcGISMapType
GProjection	ArcGISProjection

REST API Classes

The GMap extension classes are built on top of a number of classes that communicates with ArcGIS Server. Developers who want to get lower level access can use those classes by calling the ArcGISTileLayer.getMapService() or ArcGISMapOverlay.getMapService(). Those classes are designed to closely reflect the actual REST API. Several principles are used in the design:

• Each service/resource is a class with constructor
• Operations performed on resource are methods of the resource classes.
• Use object literals whenever possible such as parameters and results

The following is a table that describes the REST resource and their corresponding classes:

REST Resource	Library Class
Map Service	ArcGISMapService
Layer	ArcGISLayer
Geocode Service	ArcGISGeocodeService
GP Service	TBD
Geometry Service	ArcGISGeometryService
Image Service	TBD

The load Event

ArcGIS services may be published with different spatial reference systems. If they are pre-rendered as map tiles, they will use a certain "tiling scheme". Some of them may use the exact same tile scheme as Google maps, some may not. In order to let the core Google Maps API know how to load tiles correctly, it is necessary to get information about how the tiles are constructed from the server first. This is an asynchronous process. For this reason, it's often necessary to wait for the "load" event before using an ArcGIS Link class. It is not necessary to wait if...

• The resource is added as an ArcGISMapOverlay
• The tiles are created with the same tile system as Google Maps, in ArcGIS's terms, "cached with Web-Mercator scheme";
• You pass in an ArcGISProjection to the constructor of ArcGISTileLayer so the API immediately knows how to request tiles;

Rule of thumb: when in doubt, always use 'load' event.

var tileLayer=new ArcGISTileLayer(url);
GEvent.addListener(tileLayer,'load', function(){
  // start use the tile Layer.
});

Spatial Reference Support

This library provides additional spatial reference support by implementing interface ArcGISSpatialReference, which converts between Lat/Lng and map coordinates, then using an intermediate class ArcGISProjection to bridge Google's coordinate system to ArcGIS's system. This library includes a few built-in spatial references: WGS84 (4326) and WebMercator (102113). It also has two of the most widely used projections: LambertConformalConic and Transverse Mercator. Spatial references based on these two projections can be used by calling ArcGISSpatialReferences.addSpatialReference(wkid, wkt). A developer can also implement their own projection class and plug it in. If the system fails to find an implemented spatial reference, it will use ArcGISFlatSpatialReference for somewhat less accurate coordinates transformation. Here is a summary of options:

• If you use map service as ArcGISMapOverlay and add on top of backgrounds, no special action is necessary. You can simply use

  gmap.addOverlay(new ArcGISMapOverlay(url));
       

• If you use a tiled map service, and you know it was created using the same coordinate system Google Maps uses (WebMercator in ArcGIS), no special action is necessary. You can simply use

  gmap.addMapType(new ArcGISMapType(url));
        

  .
• If you use a tiled map service, and you know it was created using ArcGIS Online tiling scheme, or it's real spatial reference code is 4326(WGS84) or 4269 (NAD83), you should use it after the "load" event.

  var maptype=new ArcGISMapType(url);
  GEvent.addListener(maptype, 'load', function(){
    gmap.addMapType(maptype);
  });
        

  .
• If you use a tiled map service, and you know it's spatial reference was based on Lambert Conformal Conic or Transverse Mercator projection (as most State Plane Coordinate System do), you should find it's Well-known-Text value from ESRI documentation and add it into the application, then use it after the "load" event.

  ArcGISSpatialReferences.addSpatialReference(2264, 'PROJCS["NAD_1983_StatePlane_North_Carolina_FIPS_3200_Feet",......');
  var maptype=new ArcGISMapType(url);
  GEvent.addListener(maptype, 'load', function(){
    gmap.addMapType(maptype);
  });
        

  .
• If you use a tiled map service, but you just want to quickly use the service, and you do not need a precise Lat Lng to real coordinate transformation, you can simply use it after the "load" event. The API will use ArcGISFlatSpatialReference.

  var maptype=new ArcGISMapType(url);
    GEvent.addListener(maptype, 'load', function(){
    gmap.addMapType(maptype);
  });
        

  .
• Finally, if you use a tiled map service, but it's spatial reference was not based on LCC or Transverse Mercator, and you DO need a precise Lat Lng to real coordinate transformation, you can implement your own ArcGISSpatialReference class, add it to application, then use it after the "load" event.

  function MySpatialReference=function(params){...}
  MySpatialReference.prototype.reverse=function(coordsArray){...return [lng,lat]};
  MySpatialReference.prototype.forward=function(lnglatArray){...return [x,y]};
  MySpatialReference.prototype.getWrapWidth=function(){...};
  ArcGISSpatialReferences.addSpatialReference(myWkid,new MySpatialReference({...}));
  var maptype=new ArcGISMapType(url);
  GEvent.addListener(maptype, 'load', function(){
    gmap.addMapType(maptype);
  });
        

  .

Layer Orders/z-Index

ArcGIS Maps can be added with one of the following types: ArcGISMapOverlay, ArcGISTileLayerOverlay, or ArcGISMapType.

• ArcGISMapOverlay is best suited for dynamic map service in which sub layers can be turned on/off and map images will be generated on the fly. They should be on top of map resources. They are added to the G_MAP_OVERLAY_LAYER_PANE.
• ArcGISTileLayerOverlay is best suited for some common shared service that maybe used in different background context. They are below ArcGISMapOverlay but on top of the ArcGISTileLayers inside the MapTypes. They are in G_MAP_OVERLAY_LAYER_PANE.
• The order of ArcGISMapOverlay and ArcGISTileLayerOverlay depends on the order they were added to Map. The one added later will be on top of the one added earlier.
• ArcGISMapType is best suited for specialized background map. It consists of one or more ArcGISTileLayer and should stay at the bottom of the stack. They are in G_MAP_MAP_PANE.