Overview  |  API  |  Data Structures  |  Parameters  |  Example Map

MSRMapsService Data Structures

Return Structures

A few return a simple scalar integer or string value. Most MSRMapsService methods return a data structure containing several fields or nested structures to the calling method. Often multiple methods return the same data structure but accept different input parameters. This document describes the fields and nested structures in each data structure that is returned by a Microsoft Research Maps web method. The following table is the directory of all MSRMapsService structures returned by web methods:

AreaBoundingBox AreaCoordinate LonLatPt LonLatPtOffset
OverlappingThemeInfo Place PlaceFacts ThemeBoundingBox
ThemeInfo TileId TileMeta UtmPt

Go to top of document

AreaBoundingBox

Area Bounding Box example An AreaBoundingBox structure contains the meta-data describing a rectangular area on earth. The structure describes the Microsoft Research Maps image tile that covers each corner of the rectangle requested by the caller to functions which return an AreaBoundingBox structure.

The diagram on the right shows an image constructed from information returned in an AreaBoundingBox structure. The red grid lines identfy the pixels contributed by each Microsoft Research Maps image tiles used to construct the image. The AreaBoundingBox structure returned the AreaCoordinate data for NorthWest tile, labeled 1, the NorthEast tile, labeled 2, the SouthWest tile, labeled 3, the SouthEast tile, labeled 4, and the center tile, labeled 5.

The NearestPlace String in the AreaBoundingBox structure is the distance to the neareast place from the longitude and latitude described in the center AreaCoordinate's LonLatPtOffset structure. This is the same string that would be returned by a call to ConvertLonLatPtToNearestPlace method using the longitude and latitude in the center AreaCoordinate's LonLatPtOffset structure. This example returned the string "San Francisco, California, United States" which indicates the image is centered over San Francisco, California.

The array OverlappingThemeInfo structures identify the other imagery theme's in the Microsoft Research Maps database that overlap the center AreaCoordinate image tile. This information is designed to help applications, particularly web applications, to generate links to switch the display to other imagery types.

    public struct AreaBoundingBox {
        public AreaCoordinate         NorthWest;
        public AreaCoordinate         NorthEast;
        public AreaCoordinate         SouthWest;
        public AreaCoordinate         SouthEast;
        public AreaCoordinate         Center;
        public String                 NearestPlace;
        public OverlappingThemeInfo[] OverlappingThemeInfos;
	}

Returned by: GetAreaFromPt, GetAreaByRect, and GetAreaByTileId.

Go to top of document

AreaCoordinate

The AreaCoordinate contains the TileMeta and LonLatPtOffset data for a single corner point found in the AreaBoundingBox structure. The LonLatPtOffset data identifies the pixel offset and the offset's longtiude and latitude coordinates. For a corner point, the pixel offset is used to crop the Microsoft Research Maps image tile to give the appearance of the image produced from a AreaBoundingBox structure. The center tile's LonLatPtOffset identifies the pixel offset of a specific longitude and latitude value. The GetAreaFromPt method sets center tile's offset to be the longitude and latitude passed to the method.

    public struct AreaCoordinate {
        public TileMeta TileMeta;
        public LonLatPtOffset Offset;
    }

Contained in: AreaBoundingBox structure

Go to top of document

LonLatPt

LonLatPt identifies a point on the surface of the earth in the Geographic projection — a Longitude and Latitude point. A valid Longitude value ranges from -180.0 to 180.0. Negative numbers identify the western hemisphere. Positive numbers identify the eastern hemisphere. A valid Latitude value ranges from -90.0 to 90.0. Negative numbers identify the southern hemisphere. Positive number identify the northern hemisphere.

    public struct LonLatPt {
        public Double   Lon;
        public Double   Lat;
    }

Returned By: ConvertUtmPtToLonLatPt, ConvertPlaceToLonLatPt

Contained in: LonLatPtOffset, TileMeta structure

Go to top of document

LonLatPtOffset

The LonLatPtOffset structure describes the pixel location of a specific longitude and latitude value within a Microsoft Research Maps image tile. The LonLatPtOffset structure is contained within an AreaCoordinate structure. The XOffset and YOffset fields identify the offset to the LonLatPt Point field's within the tile described by the TileMeta structure in the AreaCoordinate structure that contains the LonLatPtOffset. The LonLatPtOffset data is typically used to determine how to crop Microsoft Research Maps image tiles or where to overlay a graphic indicating the location of a center point.

    public struct LonLatPtOffset {
        public LonLatPt Point;
        public Int32    XOffset;
        public Int32    YOffset;
	}

Contained in: AreaCoordinate structure

OverlappingThemeInfo

The OverLappingThemeInfo structure identifies the presence of other image theme's that overlay the center LonLatPt point of an AreaBoundingBox structure. An array of OverlappingThemeInfo structures is returned in the AreaBoundingBox structure.

	public struct OverlappingThemeInfo {	// The other Theme's that overlap 
		public Boolean    LocalTheme;
		public int	      Theme;	// MSRMapsService change
		public LonLatPt   Point;
		public String     ThemeName;
		public DateTime   Capture;	// Time the photo was captured, or topo was printed
		public Projection Projection;
		public Scale      LoScale;
		public Scale      HiScale;
		public String     Url;		// Link to the remote web server
	}

Contained in: AreaBoundingBox

Go to top of document

Place

The Place structure identifies the City, State, and Country of interest. The Place structure is typically passed to Place Name Search methods.

    public struct Place {
        public String City;
        public String State;
        public String Country;
    }

Contained in: PlaceFacts

Go to top of document

PlaceFacts
    public struct PlaceFacts {
        public Place     Place;
        public LonLatPt  Center;
        public Themes    AvailableThemeMask;
        public PlaceType PlaceTypeId;
        public Int32     Population;
	}

Go to top of document

PlaceType enum

The PlaceType enum identifies the Gazetteer category a Place name belongs to in the Microsoft Research Maps database.

    public enum PlaceType {
        UnknownPlaceType	=  0,
        AirRailStation		=  1,
        BayGulf				=  2,
        CapePeninsula		=  3,
        CityTown			=  4,
        HillMountain		=  5,
        Island				=  6,
        Lake				=  7,
        OtherLandFeature	=  8,
        OtherWaterFeature	=  9,
        ParkBeach			= 10,
        PointOfInterest		= 11,
        River				= 12
    }

Contained in: PlaceFacts

Go to top of document

Scale enum

Scale identifies the ground resolution of the imagery. The base resolution in the Microsoft Research Maps system is 1 meter on a side. That is, each pixel covers one square meter of earth. All Microsoft Research Maps imagery is in a power of 2 relative to 1 meter per pixel. Scale maps internal integer values used within the Microsoft Research Maps database to a enum name.

    public enum Scale {
        Scale1mm   =  0,
        Scale2mm   =  1,
        Scale4mm   =  2,
        Scale8mm   =  3,
        Scale16mm  =  4,
        Scale32mm  =  5,
        Scale63mm  =  6,
        Scale125mm =  7,
        Scale250mm =  8,
        Scale500mm =  9,
        Scale1m    = 10,
        Scale2m    = 11,
        Scale4m    = 12,
        Scale8m    = 13,
        Scale16m   = 14,
        Scale32m   = 15,
        Scale64m   = 16,
        Scale128m  = 17,
        Scale256m  = 18,
        Scale512m  = 19,
        Scale1km   = 20,
        Scale2km   = 21,
        Scale4km   = 22,
        Scale8km   = 23,
        Scale16km  = 24
    }

Go to top of document

Theme

Currently, the Microsoft Research Maps system supports four types of imagery — aerial imagery (photograph), scanned topographic map, natural color high-resolution imagery (urban area), and shaded relief (digital elevation). In MSRMapsService, the Theme field is an Int32. In version 1.0, the Theme field was an enum type. The following table associates the MSRMapsService integer values with the version 1.0 enum values:

Data Theme Name MSRMapsService Integer Version 1.0 Enum
Aerial Photograph (USGS DOQ) 1 Theme.Photo
Topographic Map (USGS DRG) 2 Theme.Topo
Shaded Relief 3 Theme.Relief
High-Resolution, Natural Color Ortho-Image (USGS Urban Area) 4 n/a

Go to top of document

ThemeBoundingBox
    public struct ThemeBoundingBox {
        public int	      Theme;	// MSRMapsService change
        public String     ThemeName;
        public Int32      Sparseness;
        public Scale      LoScale;
        public Scale      HiScale;
        public Projection Projection;
        public String     ProjectionName;
        public Double     WestLongitude;
        public Double     NorthLatitude;
        public Double     EastLongitude;
        public Double     SouthLatitude;
	}

Go to top of document

ThemeInfo
    public struct ThemeInfo {
        public int	  Theme;	// MSRMapsService change
        public String Name;
        public String Description;
        public String Supplier;
        public Scale  LoScale;
        public Scale  HiScale;
        public Projection Projection;
        public String ProjectionName;
        public String CopyrightNotice;
	}

Go to top of document

Themes

An enum that doubles as a bit mask. It indicates the tile Themes

    [Flags]
    public enum Themes {
        Photo = 1,
        Topo = 2,
        Relief = 4
    }

Go to top of document

TileId

TileId identifies a unique image tile in the Microsoft Research Maps database.

    public struct TileId {
        public Int32 Theme;
        public Scale Scale;
        public Int32 Scene;
        public Int32 X;
        public Int32 Y;
    }

Contained In: TileMeta

Most Microsoft Research Maps image tiles are in the UTM NAD 83 projection system. 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

TileMeta

The TileMeta structure contains the meta-data describing a single image tile in the Microsoft Research Maps database. All image tiles in Microsoft Research Maps are 200 by 200 pixels. The TileId structure identifies the unique address of the tile within the Microsoft Research Maps database. The TileExists Boolean field indicates whether the tile actually exists in the Microsoft Research Maps database. There are MSRMapsService methods than return TileMeta meta-data where the tile does not actually exist. The NorthWest, NorthEast, SouthWest, SouthEast, and Center LonLatPt structures identify the longitude and latitude of the four corners and the center of the tile. The Capture DateTime field identifies when the image tile was photographed or produced (in the case of topographical map tile).

    public struct TileMeta {
        public TileId   Id;
        public Boolean  TileExists;
        public LonLatPt NorthWest;
        public LonLatPt NorthEast;
        public LonLatPt SouthWest;
        public LonLatPt SouthEast;
        public LonLatPt Center;
        public DateTime Capture;
	}

Contained In: AreaCoordinate

Go to top of document

UtmPt

The UtmPt structure contains a UTM coordinate point. The X field is the UTM Easting value. The Y field is the UTM northing. The Zone field identifies the UTM zone number. Valid Zone values range from 1 thru 60. The Zone field can be used as the Scene field in a TileId structure.

	public struct UtmPt {
		public int Zone;
		public double X;
		public double Y;
	}

Returned by: ConvertLonLatPtToUtmPt

Go to top of document

back buttonhome page buttonnext page button