Overview  |  API  |  Data Structures  |  Parameters  |  Example Map

MSR Maps Service API

MSR Maps Service Appliction Programming Interface methods are grouped into the following categories:

The following table lists all the MSR Maps Service methods by functional category. Click on a method name to see a full description:

Search Methods Projection Methods Tile Information Methods
GetPlaceFacts ConvertLonLatPtToNearestPlace GetAreaFromPt
GetPlaceList ConvertLonLatPtToUtmPt GetAreaFromRect
GetPlaceListInRect ConvertUtmPtToLonLatPt GetAreaFromTileId
CountPlacesInRect GetTheme GetTileMetaFromLonLatPt
GetLatLonMetrics GetTileMetaFromTileId
GetTile

Tile Methods

The following methods are used to obtain meta-data or image-data about one or more tiles in the Microsoft Research Maps database. All methods except the GetTile() method return meta-data. GetTile() is the only method that returns compressed image data.

The Microsoft Research Maps database is a repository of high resolution imagery captured by satellite, aerial photography, or scanned from large paper products. Normally these data-sets are stored as large graphics data files ranging from 15 MB to 5 GB. Often, imagery in one graphics file may overlap with data in two or more other data files. These data files are very hard to work with standard "shrink wrap" software such as Microsoft PhotoDraw, Adobe Photoshop, PaintShop Pro, etc. Usually, sophisticated GIS and image editing software, e.g. ERDAS' Imagine, are required to manipulate and view the files. The files are impossible to work with over the internet.

The storage scheme within the Microsoft Research Maps system is to create small, 200 pixel by 200 pixel, compressed image "tiles". The tiles are aligned to specific, predictable coordinates on the globe. An image pyramid is pre-computed at predictable image resolutions and also stored as 200 pixel by 200 pixel, compressed image tiles. The Microsoft Research Maps data-loading system "does the right thing" and merges pixels from overlapping source data files into individual tiles. Depending on the data theme being processed, up to four source files might contribute pixels to a single tile. Conceptually, the load system lays the input imagery "on the floor" and aligns each input image to the correct ground coordinate. Then the loading program "cookie cutters" 200 pixel by 200 pixel tiles aligned on grid. The standard Microsoft Research Maps web application displays two, six, or twelve tiles adjacent tiles. HTML tags are used to re-position the HTML web page with a different center Microsoft Research Maps tile, or zoom in or out to a different layer in the image pyramid.

The benefit of this design is that users can quickly navigate and browse a huge database, 3.0 Terabytes of compressed image tiles created from 12 Terabytes of uncompressed image data files, over slow speed lines with a standard web browser. No special software or high-speed connection is required to view this vast amount of imagery.

The down-side of this design is that users must always view imagery as some number of adjacent tiles. It is not easy to create a single image from a set of Microsoft Research Maps image tiles and crop the image to the specification provided by an end user. The Microsoft Research Maps web application built a java applet to "stitch together" a set of Microsoft Research Maps image tiles into a single JPEG file. But cropping the image was more that we felt a generic java applet could handle on the vast majority of browsers. As it is, our java applet only runs on Windows and Unix machines, and does not work on Mac computers.

The MSR Maps Service Tile functions are designed to help application developers replicate the existing functionality available within the Microsoft Research Maps web application - locate Microsoft Research Maps tiles of interest by place name, locate tiles by longitude & latitude, navigate to adjacent tiles, and navigate to tiles in other image resolutions. The Tile methods also help application developers stitch together, crop, and draw on top of images on either the client computer or within server applications.

Go to top of document

GetAreaFromPt
public AreaBoundingBox GetAreaFromPt(LonLatPt center, int theme, Scale scale, int displayPixWidth, int displayPixHeight) 

The GetAreaFromPt method returns the tile meta-data for a Geographic rectangle. Use this call to identify the tiles required to construct an image of a specific size and resolution with a known center point. The GetAreaFromPt is typically called in applications that want to control the size of the display area. Using GetAreaFromPt, the caller controls the specific Longitude and Latitude point to be displayed in the center. The LonLatPt point parameter identifies the Geographic center of the rectangle of interest. The theme and Scale input parameters identify the type imagery and resolution of interest. The displayPixWidth and displayPixHeight parameters identify the size of image the caller intends to create. The GetAreaFromPt method computes the Microsoft Research Maps tiles that overlap the corners of your image area in the resolution specified in the Scale parameter.

Sample Call:

	TerraService ts = new TerraService();
	LonLatPt center;
	center.Lon = -122.5;
	center.Lat = 37.5;
	int theme = 1;  // Fetch an aerial photo, previously Theme.Photo in version 1.0
	try {
	     AreaBoundingBox abb = ts.GetAreaFromPt(center, theme, Scale.Scale16m, 600, 400);
	}
	catch {		// Catch exceptions thrown by GetAreaFromPt, e.g. bad theme, bad scale, etc.
	}
	

Go to top of document

GetAreaFromRect
public AreaBoundingBox GetAreaFromRect(LonLatPt upperLeft, LonLatPt lowerRight, int theme, Scale scale) {

The GetAreaFromRect method returns the tile meta-data for a Geographic rectangle. The LonLatPt upperLeft and LonLatPt lowerRight parameter identify the corners of the rectangle of interest in Geographic coordinates. The theme and Scale input parameters identify the type imagery and resolution of interest. The LonLatPt upperLeft and LonLatPt lowerRight parameters define the geographic rectangle. The GetAreaFromRect method computes the image tile address of the tile that overlaps the upperLeft point in the image Theme and Scale requested. The data is fetched and the NorthWest AreaCoordinate structure of the AreaBoundingBox structure is filled in. The method repeats the computation using the lowerRight parameter and fills in the SouthEast AreaCoordinate structure of the AreaBoundingBox structure. The upperLeft Latitude and lowerRight Longitude values are used to compute the tile address and fill in the NorthEast AreaCoordinate structure of the AreaBoundingBox structure. The lowerLeft Longitude and lowerRight Latitude value are used to compute the tile address and fill in the SouthWest AreaCoordinate structure of the AreaBoundingBox structure.

Sample Call:

	TerraService ts = new TerraService();
	LonLatPt upperLeft= new LonLatPt(), lowerRight= new LonLatPt();
	upperLeft.Lon = -122.4276;
	upperLeft.Lat = 37.7875671;
	lowerRight.Lon = -122.1532;
	lowerRight.Lat = 37.654394;
	int theme = 2; // theme=2 requests a topographic map, Theme.Topo in Version 1.0
	try{
	     AreaBoundingBox abb = ts.GetAreaFromRect(upperLeft, lowerRight, theme, Scale.Scale16m);
	}
	catch { }

Go to top of document

GetAreaFromTileId
public AreaBoundingBox GetAreaFromTileId(TileId id, int displayPixWidth, int displayPixHeight)

The GetAreaFromTileId method is similar to the GetAreaFromPt method except that input parameter is a TileId structure. The method returns an AreaBoundingBox structure using the TileMeta Center point of the specified in the TileId parameter. The GetAreaFromTileId method is typically used when panning from a given longitude and latitude point. Applications may find it more convenient to use GetAreaFromTileId than using GetAreaFromPt during panning operations.

Sample Call:

	TerraService ts = new TerraService();
	TileId id = new TileId();
	id.Theme = 2;   // Fetch a topographic map, previously Theme.Topo in version 1.0
	id.Scale = Scale.Scale16m;
	id.Scene = 10;
	id.X = 172;
	id.Y = 1306;
	try{
	     AreaBoundingBox abb = ts.GetAreaFromTileId(id, 600, 400);
	}
	catch { }

Go to top of document

GetTileMetaFromLonLatPt
public TileMeta GetTileMetaFromLonLatPt(LonLatPt point, int theme, Scale scale)

The GetTileMetaFromLonLatPt method returns a TileMeta structure containing the meta-data for a single Microsoft Research Maps image tile. The meta-data contains the geographic corner points of the image, the capture date (date photographed or printed), etc. The LonLatPt parameter identifies the geographic point of interest. The theme and Scale parameters are required.

Sample Call:

	TerraService ts = new TerraService();
	LonLatPt p = new LonLatPt();
	p.Lon = -122.4276;
	p.Lat = 37.7875671;
	int theme = 2;	// Fetch a topographic map, previously Theme.Topo in version 1.0
	DumpObject("GetTileMetaFromLonLatPt", ts.GetTileMetaFromLonLatPt(p, theme, Scale.Scale16m));

Go to top of document

GetTileMetaFromTileId
public TileMeta GetTileMetaFromTileId(TileId id)

The GetTileMetaFromTileId is similar to the GetTileMetaFromLonLatPt method call. GetTileMetaFromTileId returns a TileMeta structure containing the meta-data for a single Microsoft Research Maps image tile. The TileId parameter identifies the geographic point of interest. The Theme and Scale parameters are required.

Sample Call:

	TerraService ts = new TerraService();
	TileId id = new TileId();
	id.Theme = 2;  // fetch a topographic map, previously Theme.Topo in version 1.0
	id.Scale = Scale.Scale16m;
	id.Scene = 10;
	id.X = 172;
	id.Y = 1306;
	TileMeta tm = ts.GetTileMetaFromTileId(id);

Go to top of document

GetTile
public Byte[] GetTile(TileId id)

The GetTile method returns a Byte array containing the compressed image data for the requested tile. The TileId input parameter identifies the specific data row in the Microsoft Research Maps database to be returned. WebForm applications typically call this method within HTTP handlers that will use GDI functions to de-compress, manipulate, and re-compress the image data. Most image tiles in Microsoft Research Maps are JPEG format. There are three tile resolutions in the USGS Topographic Map theme that return GIF image tiles - 2 meter resolution (Scale.Scale2m), 8 meter (Scale.Scale8m), and 32 meter (Scale.Scale32m).

Sample Call:

	TerraService ts = new TerraService();
	TileId id = new TileId();
	id.Theme = 2;  // fetch a topographic map tile, previously Theme.Topo in version 1.0
	id.Scale = Scale.Scale16m;
	id.Scene = 10;
	id.X = 172;
	id.Y = 1306;
	Byte[] image = ts.GetTile(id);

Go to top of document

Search Methods

The TerraService offers a number of methods for locating imagery within the Microsoft Research Maps database by something other than longitude and latitude. The Tile Information Methods search the database by TileId or LonLatPt. Most end users have no clue what their longitude or latitude is except for those armed with a GPS unit. Most users know locations by a familiar name like Seattle Washington, Statue of Liberty, or Washington, D.C. Thus, the Microsoft Research Maps database maintains a "place name gazetteer" that translates popular place names to a longitude and latitude value.

The TerraService methods in this section provide a programmatic interface to the Microsoft Research Maps place name data. The place name data is referred to as the "Gazetteer" throughout this document and the Microsoft Research Maps application.

Go to top of document

GetPlaceFacts
public PlaceFacts GetPlaceFacts(Place place)

The GetPlaceFacts method returns a PlaceFacts structure for a specific Place (City, State, and Country). Unfortunately, there maybe several rows in the Microsoft Research Maps Gazetteer that match the same City, State, and Country. Microsoft Research Maps returns the first match, which may not be what you want. We recommend the GetPlaceList or GetPlaceListInRect methods.

Sample Call:

	TerraService ts = new TerraService();
	Place place = new Place();
	place.City = args[0];
	place.State = args[1];
	place.Country = args[2];
	DumpObject("PlaceFacts", ts.GetPlaceFacts(place));

Go to top of document

GetPlaceList

public PlaceFacts[] GetPlaceList(string placeName, int MaxItems, Boolean imagePresence)

The GetPlaceList method calls the Microsoft Research Maps methods and returns an array of PlaceFacts data for all names that match the placeName parameter. The placeName parameter is expected to be a single string containing the city or well known place name, state name, and country name separated by comma characters, e.g. "San Franicisco, CA, USA". Any of the three values may be missing. Thus the following are all valid placeName parameter values:

The MaxItems parameter limits the number of elements returned in the PlaceFacts array. It is recommended that MaxItems not exceed 100.

The imagePresence flag tells the method how to factor in imagery into the search. Typically, applications call GetPlaceFacts method to locate imagery for the named places. Thus passing true as the imagePresence parameter will return array elements only when the named locations have imagery associated with them. Passing false will return array elements whether are associated with imagery or not.

Sample Call:

	TerraService ts = new TerraService();
	PlaceFacts[] pfs = ts.GetPlaceList((args.Length == 0) ? "San Francisco" : args[0], 100, false);
	if (pfs == null) Console.WriteLine("NULL");

	foreach (PlaceFacts pf in pfs) {
		if (pf == null) break;
		DumpObject("GetPlaceList", pf);
		Console.WriteLine();
	}

Go to top of document

GetPlaceListInRect
public PlaceFacts[] GetPlaceListInRect(LonLatPt upperleft, LonLatPt lowerright, PlaceType ptype, int MaxItems)

The GetPlaceListInRect method retrieves Microsoft Research Maps Gazetteer data for specific geographic rectangle. This method is typcially used to locate all the place names that overlap an geographic rectangle passed to the GetAreaFromPt, GetAreaFromRect, or GetAreaFromTileId. The PlaceType parameter can be used to limit the PlaceFacts array to places of a specific type, e.g. towns, rivers, points of interest, etc. The MaxItems parameter limits the number of PlaceFacts array elements to a specific number.

Sample Call:

	TerraService ts = new TerraService();
	LonLatPt upperLeft  = new LonLatPt();
	LonLatPt lowerRight = new LonLatPt();
	upperLeft.Lon = -122.4276;
	upperLeft.Lat = 37.7875671;
	lowerRight.Lon = -122.1532;
	lowerRight.Lat = 37.654394;

	PlaceFacts[] pfs = ts.GetPlaceListInRect(upperLeft, lowerRight, PlaceType.UnknownPlaceType, 10);
	// PlaceType: UnknownPlaceType, AirRailStation, BayGulf, CapePeninsula, CityTown, HillMountain, 
	// Island, Lake, OtherLandFeature, OtherWaterFeature, ParkBeach, PointOfInterest, River
	if (pfs == null) Console.WriteLine("NULL");
	else {
		foreach (PlaceFacts pf in pfs) {
			if (pf == null) break;
			DumpObject("GetPlaceListInRect", pf);
			Console.WriteLine();
		}
	}

Go to top of document

CountPlacesInRect

public int CountPlacesInRect(LonLatPt upperleft, LonLatPt lowerright, PlaceType ptype)

The CountPlacesInRect method is similar to the GetPlaceListInRect method except that it returns the count of matching places rather than the list of matching places. This method is useful for applications that don't want to guess at the number of MaxItems to pass to the GetPlaceListInRect method. The CountPlacesInRect method can be used to compute the exact number.

Sample Call:

	TerraService ts = new TerraService();
	LonLatPt upperLeft  = new LonLatPt();
	LonLatPt lowerRight = new LonLatPt();
	upperLeft.Lon = -122.4276;
	upperLeft.Lat = 37.7875671;
	lowerRight.Lon = -122.1532;
	lowerRight.Lat = 37.654394;
	Int32 CountOfPlaces = ts.CountPlacesInRect(upperLeft, lowerRight, PlaceType.CityTown);

Go to top of document

Projection Methods

You are dealing with "Projection Systems" anytime you are dealing with a map or a globe. For our purposes within the TerraService, the earth is a sphere. Points on it are referenced by Longitude and Latitude "lines". They are not lines really, but complex curves. Maps are flat drawing of earth. Satellite or aerial imagery, in its raw state, is more-flat-than-its round. It is mathematically impossible to present a sphere on a flat surface without distorting something. Cartographers have dealt with this issue for centuries by developing different methods, known as map projections, for representing portions of earth with minimal, or at least predictable, distortions.

The USGS Cartographers selected the Universal Transverse Mercator (UTM) projection system for many of their high resolution map products, for example the USGS Topographic Map theme. The USGS chose to project the USGS Digital Orthoquadrangle aerial imagery into the UTM. There are several variants of the UTM projection system, the USGS aerial imagery and USGS topographic map data within Microsoft Research Maps are in the UTM NAD 83 projection. (NAD 83 stands for North American Datum of 1983).

The TerraService provides a set of methods to convert between "Geographic" projection and UTM. That is, convert between longitude and latitude points and UTM NAD 83 points and vice-versa. Microsoft Research Maps image tiles carry meta-data fields of the longitude and latitude of the corner points and center point of the tile. The TileId mate-data fields can be used to compute the UTM coordinates of any point in a tile. The Scale, Scene, X, and Y fields can be used to compute the UTM NAD 83 coordinates for the lower left hand pixel in the Microsoft Research Maps tile (XOffset=0 and YOffset=200). The following formulas are required to compute the UTM NAD 83 for the lower left hand pixel:

Int32 UtmZone = Scene;
Int32 metersPerPixel = (1 << ((Int32) Scale - 10));
Int32 UtmEasting = X * 200 * metersPerPixel;
Int32 UtmNorthing = Y * 200 * metersPerPixel;

Go to top of document

ConvertLonLatPtToNearestPlace

Returns a String describing the Place name and direction to the closest place to the LonLatPt passed to the method. In the Microsoft Research Maps web site, the closest place name string is displayed over the image to give users a textual reference point for the image.

public String ConvertLonLatPtToNearestPlace(LonLatPt point) {

Go to top of document

ConvertLonLatPtToUtmPt
public UtmPt ConvertLonLatPtToUtmPt(LonLatPt point)

Converts a Geographic, LonLatPt point to a UtmPt point.

Sample Call:

	TerraService ts = new TerraService();
	LonLatPt l = new LonLatPt();
	l.Lon = -122.4276;
	l.Lat = 37.7875671;
	DumpObject("ConvertLonLatPtToUtmPt", ts.ConvertLonLatPtToUtmPt(l));

Go to top of document

ConvertUtmPtToLonLatPt
public LonLatPt ConvertUtmPtToLonLatPt(UtmPt utm)

Converts a UtmPt point to a Geographic, LonLatPt point.

Sample Call:

	TerraService ts = new TerraService();
	UtmPt utmpt = new UtmPt();
	utmpt.Zone = 10;
	utmpt.X = 500000;
	utmpt.Y = 4323434;
	DumpObject("ConvertUtmPtToLonLatPt", ts.ConvertUtmPtToLonLatPt(utmpt));

Go to top of document

ConvertPlaceToLonLatPt
public LonLatPt ConvertPlaceToLonLatPt(Place place)

Obtains the Geographic LonLatPt for a specific Place (City, State, and Country).

Sample Call:

	TerraService ts = new TerraService();
	Place place = new Place();
	place.City  = "San Francisco";
	place.State = "CA";
	place.Country = "USA";
	LonLatPt point = ts.ConvertPlaceToLonLatPt(place);

Go to top of document

GetLatLonMetrics
public ThemeBoundingBox[] GetLatLonMetrics(LonLatPt point) 

The GetLatLonMetrics method describes the extent of available imagery for the LonLatPt passed to the function. In the Microsoft Research Maps system, there is a concept of a navigable "Scene". The expance of a Scene is dependent on the source of the imagery and the imagery's projection system. For data in the Geographic projection system, the expanse is the entire globe. Effectively there is one Scene.

For UTM data, there are sixty Scenes, each covering approximately six longitude degrees. The GetLatLonMetrics method describes this fact in a ThemeBoundingBox structure.

Sample Call:

	TerraService ts = new TerraService();
	LonLatPt point = new LonLatPt();
	point.Lon = -122.4276;
	point.Lat = 37.7875671;
	DumpObject("GetLatLonMetrics", ts.GetLatLonMetrics(point));

Go to top of document

GetTheme
public ThemeInfo GetTheme(int theme)

The GetTheme method returns attributes that apply to all tiles belonging to a specific theme. The theme parameter identifies the theme to return the ThemeInfo attributes for. The GetTheme method should be called by applications as part of the initialization process. The ThemeInfo identifies the projection system of the theme and the copyright notice that should be displayed when presenting the theme's imagery.

Sample Call:

	TerraService ts = new TerraService();
	DumpObject("Photo ThemeInfo", ts.GetTheme(1));
	DumpObject("Topo ThemeInfo", ts.GetTheme(2));
	DumpObject("Relief ThemeInfo", ts.GetTheme(3));

back buttonhome page buttonnext page button