Core Calculations
Note
Bing Maps Web Control SDK retirement
Bing Maps Web Control SDK is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Web Control SDK until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Web Control SDK until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Web Control SDK will need to be updated to use Azure Maps Web SDK by the retirement date that applies to your Bing Maps for Enterprise account type. For detailed migration guidance, see Migrate from Bing Maps Web Control SDK and Migrate Bing Maps Enterprise applications to Azure Maps with GitHub Copilot.
Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.
The core calculations in the Spatial Math Module provide a set of commonly used spatial calculations, such as the ability to calculate distances between locations, or perform unit conversions. These calculations are exposed as static methods on the Microsoft.Maps.SpatialMath namespace.
Static Methods
| Name | Return Type | Description |
|---|---|---|
| convertArea(area: number, fromUnits: AreaUnits, toUnits: AreaUnits) | number | Converts an area from one area unit to another. |
| convertDistance(distance: number, fromUnits: DistanceUnits, toUnits: DistanceUnits) | number | Converts a distance from one distance unit to another. |
| getCardinalSpline(locations: Location[], tension ?: number, nodeSize ?: number, close ?: boolean) | Location[] | Calculates an array of locations that form a cardinal spline between the specified array of locations. • tension - A number that indicates the tightness of the curve. Can be any number, although a value between 0 and 1 is usually used. Default: 0.5 • nodeSize - Number of nodes to insert between each Location. Default: 15 • close - A boolean indicating if the spline should be a closed ring or not. Default: false |
| getDestination(origin: Location, bearing: number, distance: number, units?: DistanceUnits) | Location | Calculates a destination coordinate based on a starting coordinate, a heading, a distance, and an optional distance unit type. The bearing angle is between 0 - 360 degrees, where 0 - North, 90 - East, 180 - South, 270 - West. |
| getDistanceTo(origin: Location, destination: Location, units?: DistanceUnits, highAccuracy?: boolean) | number | Calculate the distance between two locations on the surface of the earth using the Haversine formula. If highAccuracy value is set to true, the slower but more accurate Vincenty formula is used instead. |
| getEarthRadius(units?: DistanceUnits) | number | Returns the approximate radius of the earth in the specified distance units for a WGS84 spheroid. |
| getGeodesicPath(path: Location[], nodeSize?: number) | Location[] | Takes an array of Locations and fills in the space between them with accurately positioned coordinates to form an approximated Geodesic path (appears as a curved line on map). The nodeSize parameter is the number of Location objects to insert between each location to approximate a geodesic path. |
| getHeading(origin: Location, destination: Location) | number | Calculates the heading from one Location to another. |
| getLengthOfPath(path: Location[], units?: DistanceUnits, highAccuracy?: boolean) | number | Calculates the distance between all Location objects in an array. |
| getLocationAlongPath(path: Polyline or Location[], distance: number, units?: DistanceUnits) | Location | Calculates the Location on a path that is a specified distance away from the start of the path. If the specified distance is longer than the length of the path, the last coordinate of the path will be returned. |
| getRegularPolygon(origin: Location, radius: number, numberOfPoints: number, units?: DistanceUnits, offset?: number) | Location[] | Calculates an array of locations that are an equal distance away from a central point to create a regular polygon. • origin – center of the polygon. • radius – the distance from the origin to each point on the polygon. • numberOfPoints – the number of points the polygon should have. • units – The distance units of the radius. • offset – An angle between 0 and 360 to rotate the polygon clockwise. When 0 the first Location in the polygon will be North of the origin. Tip: The larger the numberOfPoints property, the more the generated array of locations will look like a circle. |
| interpolate(origin: Location, destination: Location, fraction?: number) | Location | Calculates a Location that is a fraction of the distance between two points, relative to the first Location object. Default fraction is 0.5, which is the midpoint between the coordinates. |
| locationRectToPolygon(bounds: LocationRect) | Polygon | Takes a LocationRect object and converts it to a Polygon. |
| toDegMinSec(loc: Location) | string | Takes a Location object and converts it into a Degree Minute Seconds string in the format. For example: 40° 26′ 46″ N 79° 58′ 56″ W |
tryParseDegMinSec(input: string) |
number or Location | Tries to parse the given string that is in Degree Minute Seconds format. For Example: 35° 26′ 31″ E or 40° 26′ 46″ N 79° 58′ 56″ W Returns a decimal degree value if only a single angle is provided. If two angles provided in the string, then a Location object is returned. If string is in an i |