Overview | API | Data Structures | Parameters | Example Map
Version 2.0 of the TerraService is now available! Version 2.0 supports the Urban Area data theme. Click on Version 2.0 changes to learn the specific changes required in your application to use Version 2.0.
A few return a simple scalar integer or string value. Most TerraService 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 TerraServer web method. The following table is the directory of all TerraService structures returned by web methods:
| AreaBoundingBox | AreaCoordinate | LonLatPt | LonLatPtOffset |
| OverlappingThemeInfo | Place | PlaceFacts | ThemeBoundingBox |
| ThemeInfo | TileId | TileMeta | UtmPt |
An AreaBoundingBox structure contains the meta-data describing a rectangular
area on earth. The structure describes the TerraServer 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 TerraServer 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 TerraServer 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.
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 TerraServer 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
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
The LonLatPtOffset structure describes the pixel location of a specific longitude and latitude value within a TerraServer 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 TerraServer 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
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; // Version 2.0 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
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
public struct PlaceFacts {
public Place Place;
public LonLatPt Center;
public Themes AvailableThemeMask;
public PlaceType PlaceTypeId;
public Int32 Population;
}
The PlaceType enum identifies the Gazetteer category a Place name belongs to in the TerraServer 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
Scale identifies the ground resolution of the imagery. The base resolution in the TerraServer-USA system is 1 meter on a side. That is, each pixel covers one square meter of earth. All TerraServer imagery is in a power of 2 relative to 1 meter per pixel. Scale maps internal integer values used within the TerraServer 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
}
Currently, the TerraServer 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 version 2.0 of the TerraService, the Theme field is an Int32. In version 1.0, the Theme field was an enum type. The following table associates the Version 2.0 integer values with the version 1.0 enum values:
| Data Theme Name | Version 2.0 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 |
public struct ThemeBoundingBox {
public int Theme; // Version 2.0 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;
}
public struct ThemeInfo {
public int Theme; // Version 2.0 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;
}
An enum that doubles as a bit mask. It indicates the tile Themes
[Flags]
public enum Themes {
Photo = 1,
Topo = 2,
Relief = 4
}
TileId identifies a unique image tile in the TerraServer database.
public struct TileId {
public Int32 Theme;
public Scale Scale;
public Int32 Scene;
public Int32 X;
public Int32 Y;
}
Contained In: TileMeta
Most TerraServer 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 TerraServer 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;
The TileMeta structure contains the meta-data describing a single image tile in the TerraServer database. All image tiles in TerraServer are 200 by 200 pixels. The TileId structure identifies the unique address of the tile within the TerraServer database. The TileExists Boolean field indicates whether the tile actually exists in the TerraServer database. There are TerraService 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
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
