Bing Maps Ajax Controls DK 70

Contents
Bing Maps AJAX Control, Version 7.0 ........................................................................................... 14

In This Section ............................................................................................................................ 14
See Also ..................................................................................................................................... 14
Getting Started with the 7.0 Map Control ...................................................................................... 15
Create a Bing Maps Account and Get a Key ............................................................................. 15
Get Familiar with the Bing Maps AJAX 7.0 Control ................................................................... 15
What's New in the AJAX Map Control ........................................................................................... 15
New Features ............................................................................................................................. 15
Developing with the 7.0 Map Control............................................................................................. 17
In This Section ............................................................................................................................ 17
Loading the AJAX Map Control ..................................................................................................... 18
Displaying the Default Map ........................................................................................................ 18
Customizing the Map When Loading ......................................................................................... 21
Disposing of the Map when you navigate to another page ........................................................ 21
Example ..................................................................................................................................... 21
Setting Map Control Parameters ................................................................................................... 22
Parameters ................................................................................................................................. 22
Setting Parameters..................................................................................................................... 23
See Also ..................................................................................................................................... 23
Changing the Map View ................................................................................................................ 23
Setting the Initial Map View ........................................................................................................ 23
Changing the Map View ............................................................................................................. 24
Adding Entities to the Map ............................................................................................................. 27
Adding Single Entities to the Map .............................................................................................. 27
Adding a Pushpin .................................................................................................................... 27
Adding a Shape ...................................................................................................................... 29
Adding Multiple Entities to the Map ............................................................................................ 30
Changing Entities on the Map .................................................................................................... 32
Customizing Your Pushpins .......................................................................................................... 34
Customizing Your Pushpin Icon ................................................................................................. 35
Creating a Pushpin Infobox ........................................................................................................ 36
Displaying Location Search Results Using the REST Services .................................................... 38
Initialize the Map ........................................................................................................................ 38

Add Controls ............................................................................................................................... 39
Make a Geocode REST Request ............................................................................................... 40
Display the Results..................................................................................................................... 41
Getting Route Directions Using the REST Services ...................................................................... 43
Initialize the Map ........................................................................................................................ 43
Construct the Route Request ..................................................................................................... 44
Display the Results..................................................................................................................... 45
Working with Tile Layers ............................................................................................................... 48
Adding a Tile Layer .................................................................................................................... 48
Using Events in the AJAX Control ................................................................................................. 49
Example ..................................................................................................................................... 49
Localizing the Map ......................................................................................................................... 53
Setting the Language ................................................................................................................. 53
[Feature preview] Show map labels in two languages on the same map .................................. 54
[Feature Preview] Display map labels in the local language using the ngt option ................... 56
Examples .................................................................................................................................... 57
Supported Cultures .................................................................................................................... 57
Localization of Error Messages .................................................................................................. 59
Building Your Own Module ............................................................................................................ 59
Develop Your Module ................................................................................................................. 59
Register and Load Your Module ................................................................................................ 60
Use Your Module........................................................................................................................ 60
See Also ..................................................................................................................................... 62
Developing a Windows Store app ................................................................................................. 62
Adding a map to your Windows Store app ................................................................................. 62
Requirements .......................................................................................................................... 62
Create a Visual Studio project and reference the Bing Maps SDK ........................................ 63
Additional Notes ......................................................................................................................... 64
Example ..................................................................................................................................... 65
See Also ................................................................................................................................... 109
Microsoft.Maps API Reference .................................................................................................... 110
In This Section .......................................................................................................................... 110
Data Structures ..................................................................................................................... 110
Mapping ................................................................................................................................ 110
Entities .................................................................................................................................. 110
User Location ........................................................................................................................ 111
Dynamic Module Loading ..................................................................................................... 111
AltitudeReference Enumeration ................................................................................................... 111

Constants ................................................................................................................................. 111
Methods .................................................................................................................................... 111
Example ................................................................................................................................... 112
AnimationVisibility Enumeration .................................................................................................. 113
Constants ................................................................................................................................. 113
Color Class .................................................................................................................................. 113
Constructor ............................................................................................................................... 114
Properties ................................................................................................................................. 114
Static Methods .......................................................................................................................... 114
Methods .................................................................................................................................... 114
Example ................................................................................................................................... 115
Coordinates Class ....................................................................................................................... 118
Properties ................................................................................................................................. 118
See Also ................................................................................................................................... 118
EntityCollection Class .................................................................................................................. 118
Constructor ............................................................................................................................... 118
Methods .................................................................................................................................... 119
Events ...................................................................................................................................... 120
Example ................................................................................................................................... 122
EntityCollectionOptions Object .................................................................................................... 124
Properties ................................................................................................................................. 124
Example ................................................................................................................................... 124
EntityState Enumeration .............................................................................................................. 126
Constants ................................................................................................................................. 126
Remarks ................................................................................................................................... 127
Example ................................................................................................................................... 127
See Also ................................................................................................................................... 128
Events Object .............................................................................................................................. 128
Methods .................................................................................................................................... 128
Example ................................................................................................................................... 129
GeoLocationProvider Class ......................................................................................................... 131
Constructor ............................................................................................................................... 131
Methods .................................................................................................................................... 131
Example ................................................................................................................................... 134
See Also ................................................................................................................................... 135
Infobox Class ............................................................................................................................... 135
Constructor ............................................................................................................................... 135

Methods .................................................................................................................................... 135
Events ...................................................................................................................................... 138
Remarks ................................................................................................................................... 139
Example ................................................................................................................................... 139
InfoboxOptions Object ................................................................................................................. 141
Properties ................................................................................................................................. 141
Example ................................................................................................................................... 143
See Also ................................................................................................................................... 145
InfoboxType Enumeration ........................................................................................................... 145
Constants ................................................................................................................................. 145
Example ................................................................................................................................... 145
KeyEventArgs Object .................................................................................................................. 147
Properties ................................................................................................................................. 147
Example ................................................................................................................................... 148
LabelOverlay Enumeration .......................................................................................................... 149
Constants ................................................................................................................................. 149
Methods .................................................................................................................................... 150
Example ................................................................................................................................... 150
Location Class ............................................................................................................................. 151
Constructor ............................................................................................................................... 151
Properties ................................................................................................................................. 151
Static Methods .......................................................................................................................... 152
Methods .................................................................................................................................... 152
Example ................................................................................................................................... 153
LocationRect Class ...................................................................................................................... 154
Constructor ............................................................................................................................... 154
Properties ................................................................................................................................. 154
Static Methods .......................................................................................................................... 155
Methods .................................................................................................................................... 155
Example ................................................................................................................................... 157
Map Class .................................................................................................................................... 158
Constructor ............................................................................................................................... 158
Properties ................................................................................................................................. 158
Static Methods .......................................................................................................................... 158
Methods .................................................................................................................................... 159
Events ...................................................................................................................................... 163
Example ................................................................................................................................... 165
MapMode Class ........................................................................................................................... 166

Mercator Map Mode Methods .................................................................................................. 166
MapModeOptions Object ............................................................................................................. 167
Properties ................................................................................................................................. 167
MapOptions Object ...................................................................................................................... 168
Properties ................................................................................................................................. 168
Example ................................................................................................................................... 172
MapTypeId Enumeration ............................................................................................................. 173
Constants ................................................................................................................................. 173
Example ................................................................................................................................... 174
See Also ................................................................................................................................... 174
Module Loading Methods ............................................................................................................ 175
Methods .................................................................................................................................... 175
Example ................................................................................................................................... 176
See Also ................................................................................................................................... 178
MouseEventArgs Object .............................................................................................................. 178
Properties ................................................................................................................................. 178
Methods .................................................................................................................................... 179
Example ................................................................................................................................... 179
PixelReference Enumeration ....................................................................................................... 181
Constants ................................................................................................................................. 181
Methods .................................................................................................................................... 181
Example ................................................................................................................................... 182
Point Class ................................................................................................................................... 183
Constructor ............................................................................................................................... 183
Properties ................................................................................................................................. 184
Static Methods .......................................................................................................................... 184
Methods .................................................................................................................................... 184
Example ................................................................................................................................... 184
Polygon Class .............................................................................................................................. 186
Constructor ............................................................................................................................... 186
Methods .................................................................................................................................... 186
Events ...................................................................................................................................... 188
Example ................................................................................................................................... 188
PolygonOptions Object ................................................................................................................ 190
Properties ................................................................................................................................. 190
Example ................................................................................................................................... 191

Polyline Class .............................................................................................................................. 192
Constructor ............................................................................................................................... 192
Methods .................................................................................................................................... 193
Events ...................................................................................................................................... 194
Example ................................................................................................................................... 195
PolylineOptions Object ................................................................................................................ 196
Properties ................................................................................................................................. 196
Example ................................................................................................................................... 197
Position Class .............................................................................................................................. 198
Properties ................................................................................................................................. 198
See Also ................................................................................................................................... 199
PositionCircleOptions Object ....................................................................................................... 199
Properties ................................................................................................................................. 199
Example ................................................................................................................................... 199
PositionError Class ...................................................................................................................... 201
Properties ................................................................................................................................. 201
See Also ................................................................................................................................... 202
PositionOptions Object ................................................................................................................ 202
Properties ................................................................................................................................. 202
Example ................................................................................................................................... 204
Pushpin Class .............................................................................................................................. 205
Constructor ............................................................................................................................... 205
Methods .................................................................................................................................... 205
Events ...................................................................................................................................... 207
Example ................................................................................................................................... 208
PushpinOptions Object ................................................................................................................ 210
Properties ................................................................................................................................. 210
Example ................................................................................................................................... 211
TileLayer Class ............................................................................................................................ 212
Constructor ............................................................................................................................... 213
Methods .................................................................................................................................... 213
Events ...................................................................................................................................... 214
Example ................................................................................................................................... 214
See Also ................................................................................................................................... 215
TileLayerOptions Object .............................................................................................................. 215
Properties ................................................................................................................................. 215
Example ................................................................................................................................... 216

See Also ................................................................................................................................... 219
TileSource Class.......................................................................................................................... 219
Constructor ............................................................................................................................... 219
Methods .................................................................................................................................... 219
Example ................................................................................................................................... 219
See Also ................................................................................................................................... 221
TileSourceOptions Object ............................................................................................................ 221
Properties ................................................................................................................................. 221
Example ................................................................................................................................... 222
See Also ................................................................................................................................... 224
ViewOptions Object ..................................................................................................................... 224
Properties ................................................................................................................................. 224
Remarks ................................................................................................................................... 226
Example ................................................................................................................................... 226
Microsoft.Maps.AdvancedShapes API Reference ...................................................................... 228
In This Section .......................................................................................................................... 228
EntityCollection Class (AdvancedShapes) .................................................................................. 228
Constructor ............................................................................................................................... 228
Methods .................................................................................................................................... 228
Events ...................................................................................................................................... 230
Remarks ................................................................................................................................... 231
Polygon Class (AdvancedShapes) .............................................................................................. 232
Constructor ............................................................................................................................... 232
Methods .................................................................................................................................... 232
Events ...................................................................................................................................... 234
Example ................................................................................................................................... 235
Microsoft.Maps.Directions API Reference ................................................................................... 237
In This Section .......................................................................................................................... 237
BusinessDetails Class ................................................................................................................. 238
Properties ................................................................................................................................. 238
See Also ................................................................................................................................... 239
BusinessDisambiguationSuggestion Class ................................................................................. 239
Properties ................................................................................................................................. 239
Example ................................................................................................................................... 240
See Also ................................................................................................................................... 243
DirectionsErrorEventArgs Object ................................................................................................. 243

Properties ................................................................................................................................. 243
Example ................................................................................................................................... 244
DirectionsEventArgs Object ......................................................................................................... 246
Properties ................................................................................................................................. 246
Example ................................................................................................................................... 246
DirectionsManager Class ............................................................................................................ 248
Constructor ............................................................................................................................... 249
Methods .................................................................................................................................... 249
Events ...................................................................................................................................... 253
Example ................................................................................................................................... 255
DirectionsRenderOptions Object ................................................................................................. 257
Properties ................................................................................................................................. 257
Example ................................................................................................................................... 259
DirectionsRequestOptions Object ............................................................................................... 262
Properties ................................................................................................................................. 262
Example ................................................................................................................................... 263
DirectionsStep Class ................................................................................................................... 265
Properties ................................................................................................................................. 265
Example ................................................................................................................................... 267
DirectionsStepEventArgs Object ................................................................................................. 270
Properties ................................................................................................................................. 270
Example ................................................................................................................................... 271
DirectionsStepRenderEventArgs Object ..................................................................................... 273
Properties ................................................................................................................................. 273
Example ................................................................................................................................... 274
DirectionsStepWarning Class ...................................................................................................... 276
Properties ................................................................................................................................. 276
Example ................................................................................................................................... 277
Disambiguation Class .................................................................................................................. 280
Properties ................................................................................................................................. 280
Example ................................................................................................................................... 280
See Also ................................................................................................................................... 284
DisambiguationRenderEventArgs Object .................................................................................... 284
Properties ................................................................................................................................. 284
DistanceUnit Enumeration ........................................................................................................... 285
Constants ................................................................................................................................. 285

Example ................................................................................................................................... 285
IconType Enumeration ................................................................................................................ 287
Constants ................................................................................................................................. 287
Example ................................................................................................................................... 288
LocationDisambiguationSuggestion Class .................................................................................. 291
Properties ................................................................................................................................. 291
Example ................................................................................................................................... 291
See Also ................................................................................................................................... 295
Maneuver Enumeration ............................................................................................................... 295
Constants ................................................................................................................................. 295
Example ................................................................................................................................... 299
ResetDirectionsOptions Object ................................................................................................... 302
Properties ................................................................................................................................. 302
Route Class ................................................................................................................................. 303
Properties ................................................................................................................................. 303
RouteAvoidance Enumeration ..................................................................................................... 303
Constants ................................................................................................................................. 303
RouteLeg Class ........................................................................................................................... 304
Properties ................................................................................................................................. 304
Example ................................................................................................................................... 305
RouteMode Enumeration ............................................................................................................. 307
Constants ................................................................................................................................. 307
RouteOptimization Enumeration.................................................................................................. 307
Constants ................................................................................................................................. 307
RoutePath Class .......................................................................................................................... 308
Properties ................................................................................................................................. 308
RouteResponseCode Enumeration ............................................................................................. 309
Constants ................................................................................................................................. 309
Example ................................................................................................................................... 311
RouteSelectorEventArgs Object .................................................................................................. 313
Properties ................................................................................................................................. 313
RouteSelectorRenderEventArgs Object ...................................................................................... 313
Properties ................................................................................................................................. 313
RouteSubLeg Class ..................................................................................................................... 314

Properties ................................................................................................................................. 314
RouteSummary Class .................................................................................................................. 315
Properties ................................................................................................................................. 315
Example ................................................................................................................................... 315
RouteSummaryRenderEventArgs Object .................................................................................... 318
Properties ................................................................................................................................. 318
StepWarningStyle Enumeration .................................................................................................. 318
Constants ................................................................................................................................. 318
Example ................................................................................................................................... 319
TimeType Enumeration ............................................................................................................... 322
Constants ................................................................................................................................. 322
Example ................................................................................................................................... 323
See Also ................................................................................................................................... 325
TransitLine Class ......................................................................................................................... 325
Properties ................................................................................................................................. 325
Example ................................................................................................................................... 326
TransitOptions Object .................................................................................................................. 329
Properties ................................................................................................................................. 329
Example ................................................................................................................................... 329
Waypoint Class ............................................................................................................................ 331
Constructor ............................................................................................................................... 331
Methods .................................................................................................................................... 332
Events ...................................................................................................................................... 334
Example ................................................................................................................................... 334
WaypointEventArgs Object .......................................................................................................... 338
Properties ................................................................................................................................. 338
WaypointOptions Object .............................................................................................................. 338
Properties ................................................................................................................................. 338
Example ................................................................................................................................... 339
WaypointRenderEventArgs Object .............................................................................................. 342
Properties ................................................................................................................................. 342
Microsoft.Maps.Overlays.Style Reference .................................................................................. 342
Navigation Bar Style ................................................................................................................. 342
Microsoft.Maps.Search API Reference ....................................................................................... 343
In This Section .......................................................................................................................... 344

Address Class (AJAX) ................................................................................................................. 344
Properties ................................................................................................................................. 344
GeocodeLocation Class (AJAX) .................................................................................................. 345
Properties ................................................................................................................................. 345
GeocodeRequestOptions Object ................................................................................................. 346
Properties ................................................................................................................................. 346
Example ................................................................................................................................... 347
See Also ................................................................................................................................... 349
GeocodeResult Class (AJAX) ..................................................................................................... 349
Properties ................................................................................................................................. 349
LocationPrecision Enumeration ................................................................................................... 349
Constants ................................................................................................................................. 349
MatchCode Enumeration ............................................................................................................. 350
Constants ................................................................................................................................. 350
MatchConfidence Enumeration ................................................................................................... 350
Constants ................................................................................................................................. 350
PlaceResult Class........................................................................................................................ 350
Properties ................................................................................................................................. 351
ReverseGeocodeRequestOptions Object ................................................................................... 351
Properties ................................................................................................................................. 351
Example ................................................................................................................................... 352
See Also ................................................................................................................................... 353
SearchManager Class ................................................................................................................. 354
Constructor ............................................................................................................................... 354
Methods .................................................................................................................................... 354
Example ................................................................................................................................... 355
SearchParseResult Class ............................................................................................................ 357
Properties ................................................................................................................................. 357
SearchRegion Class (AJAX) ....................................................................................................... 357
Properties ................................................................................................................................. 357
SearchRequestOptions Object .................................................................................................... 358
Properties ................................................................................................................................. 358
Example ................................................................................................................................... 360
See Also ................................................................................................................................... 361
SearchResponse Class (AJAX) ................................................................................................... 361

Properties ................................................................................................................................. 361
See Also ................................................................................................................................... 362
SearchResponseSummary Class ................................................................................................ 362
Properties ................................................................................................................................. 362
SearchResult Class ..................................................................................................................... 363
Properties ................................................................................................................................. 363
Microsoft.Maps.Themes.BingTheme API Reference .................................................................. 364
BingTheme Features ................................................................................................................ 364
Example ................................................................................................................................... 364
Microsoft.Maps.Traffic API Reference ......................................................................................... 366
In This Section .......................................................................................................................... 366
TrafficLayer Class (deprecated) .................................................................................................. 366
Constructor ............................................................................................................................... 366
Methods .................................................................................................................................... 366
Example ................................................................................................................................... 367
TrafficManager Class .................................................................................................................. 368
Constructor ............................................................................................................................... 368
Methods .................................................................................................................................... 368
Example ................................................................................................................................... 369
Microsoft.Maps.VenueMaps API Reference ............................................................................... 370
In This Section .......................................................................................................................... 370
Directory Class ............................................................................................................................ 371
Methods .................................................................................................................................... 371
Events ...................................................................................................................................... 373
Example ................................................................................................................................... 374
DirectoryGrouping Enumeration .................................................................................................. 378
Constants ................................................................................................................................. 378
DirectorySortOrder Enumeration ................................................................................................. 378
Constants ................................................................................................................................. 379
Floor Class ................................................................................................................................... 379
Properties ................................................................................................................................. 379
Example ................................................................................................................................... 379
Footprint Class ............................................................................................................................. 382
Properties ................................................................................................................................. 382
Example ................................................................................................................................... 382

Metadata Class ............................................................................................................................ 384
Properties ................................................................................................................................. 384
Example ................................................................................................................................... 385
NearbyVenue Class ..................................................................................................................... 387
Properties ................................................................................................................................. 387
Example ................................................................................................................................... 387
NearbyVenueOptions Object ....................................................................................................... 389
Properties ................................................................................................................................. 389
Example ................................................................................................................................... 389
Polygon Class (Venue Map) ........................................................................................................ 391
Properties ................................................................................................................................. 391
Primitive Class ............................................................................................................................. 391
Properties ................................................................................................................................. 392
Methods .................................................................................................................................... 392
Example ................................................................................................................................... 393
VenueMap Class ......................................................................................................................... 395
Properties ................................................................................................................................. 395
Methods .................................................................................................................................... 396
Events ...................................................................................................................................... 396
Example ................................................................................................................................... 397
VenueMapCreationOptions Object .............................................................................................. 399
Properties ................................................................................................................................. 399
Example ................................................................................................................................... 400
VenueMapFactory Class ............................................................................................................. 401
Constructor ............................................................................................................................... 401
Methods .................................................................................................................................... 402
Example ................................................................................................................................... 402
Bing Maps AJAX Control 7.0 Supported Browsers ..................................................................... 404
Supported Browsers ................................................................................................................. 404
Release History for Bing Maps AJAX Control, Version 7.0 ......................................................... 405
Bing Maps AJAX Control 7.0 Developer Resources ................................................................... 405
Developer Resources ............................................................................................................... 405
Account Issues ......................................................................................................................... 406
Licensing Questions ................................................................................................................. 406

14
Bing Maps AJAX Control, Version 7.0
Bing Maps is an online mapping service that enables users to search, discover, explore, plan,
and share information about specific locations. By using enhanced road maps, labeled aerial
photo views, and low-angle high-resolution aerial photos, Bing Maps AJAX Control 7.0, in
conjunction with the Bing Maps REST Services, provides unique opportunities for developers to
incorporate both location and local search features into their web applications, as well as into
Windows Store apps (see Developing a Windows Store app).
The Bing Maps AJAX Control 7.0 software development kit (SDK) consists of a complete set of
reference topics that cover the Bing Maps AJAX Control 7.0 application programming interface
(API). For extra code snippets and feature samples, see Bing Maps AJAX Control 7.0 Interactive
SDK and Samples on MSDN.
Download this documentation: CHM | PDF
In This Section
Getting Started with the 7.0 Map Control
What's New in the AJAX Map Control
Developing with the 7.0 Map Control
Microsoft.Maps API Reference
Microsoft.Maps.AdvancedShapes API Reference
Microsoft.Maps.Directions API Reference
Microsoft.Maps.Overlays.Style Reference
Microsoft.Maps.Search API Reference
Microsoft.Maps.Themes.BingTheme API Reference
Microsoft.Maps.Traffic API Reference
Microsoft.Maps.VenueMaps API Reference
Supported Browsers
Developer Resources
See Also
Terms and Conditions

15
Getting Started with the 7.0 Map Control
The Bing Maps AJAX Control 7.0 is a JavaScript control that contains the objects, methods, and
events that allow you to display maps powered by Bing Maps on your Web site. The sections in
this topic describe the steps you need to take to start using the Bing Maps AJAX Control 7.0.
Create a Bing Maps Account and Get a Key
Before you begin developing your application, you need to create a developer account on the
Bing Maps Account Center. A Bing Maps Developer Account allows you to create a Bing Maps
Key to use in your map application. Getting a key is described in Getting a Bing Maps Key.
When the Bing Maps AJAX Control 7.0 is loaded with a valid Bing Maps Key, Bing Maps
counts sessions. A session begins with the load of the Bing Maps AJAX Control 7.0 into a
users browser and includes all Bing Maps AJAX Control 7.0 interactions until the
browser is closed or the user moves to a different page. Detailed information about Bing
Maps usage reports is found in Viewing Bing Maps Usage Reports.
Get Familiar with the Bing Maps AJAX 7.0 Control
The Developing with the 7.0 Map Control section of this SDK contains topics that describe how to
use the features provided by the AJAX map control.
What's New in the AJAX Map Control
Heres a list of the latest features:
New Features
February, 2014
[FEATURE PREVIEW] Display map labels in two languages + new option for displaying
labels in the local language of each country or region of the map
This feature is being released as a preview and is subject to change.
You now have the option to specify a primary and secondary language for map labels when you
set the mkt parameter in the map reference. The languages you choose are both displayed on
the map in the order you specify them. You can also display map labels for each country or
region on the map in the local language of that country or region by specifying the custom
language option ngt. For details, see Localizing the Map.

16
Examples
This map reference example shows how to specify two languages for the map.
<script type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=ru-ru,en-
us"></script>
The following screenshot shows how the map labels will appear for this example.

This example specifies the custom language option ngt as the secondary language.
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=ru-
ru,ngt"></script>

17

Developing with the 7.0 Map Control
The topics in this section will help you to start using the Bing Maps AJAX Control 7.0.
In This Section
Loading the AJAX Map Control
Setting Map Control Parameters
Changing the Map View
Adding Entities to the Map
Customizing Your Pushpins
Displaying Location Search Results Using the REST Services
Calculating Directions Using the Directions Module
Working with Tile Layers
Using Events in the AJAX Control
Localizing the Map
Building Your Own Module
Developing a Windows Store app

18
This topic describes how to load the Bing Maps AJAX Control 7.0 into your Web page to display a
map. This is the first step you need to take for any page that uses the map control.
Displaying the Default Map
Displaying the default map, which includes all of the navigation functionality, consists of the
following steps:
1. At the top of the HTML page add the following DOCTYPE declaration.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2. In the header section of an HTML page, add a META element with the charset attribute set
to "utf-8", as follows.
<meta http-equiv="Content-Type" content="text/html; charset=utf-
8"/>
It is recommended that you use UTF-8 encoding in your web page.
3. Also in the header section, add a reference to the map control, as follows.
<script charset="UTF-8" type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?
v=7.0">
</script>
To use SSL, add the s parameter to the reference as shown below.
src="https://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx
?v=7.0&s=1">
</script>
To display your map in another language that the default en-us (United States English), set
the mkt parameter to a supported language as shown below. For a list of supported
languages, see Localizing the Map.
src="https://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx
?v=7.0&mkt=fr-fr">
</script>

19
With new features currently in preview, you can show map labels in two languages
and show the local language for each location. These preview features are described
in Localizing the Map.
4. In the body of the page, add a DIV element to the page to contain the map. The size of the
map is defined by the height and width of the DIV element. The position of the map is set by
using the "position", "top", and "left" properties. You can set these values either inline or by
defining the values in a style class and then referencing that class, as follows.
<div id='mapDiv' style="position:absolute; width:400px;
height:400px;"></div>
or
.map {
position: absolute;
top: 20;
left: 10;
width: 400px;
height: 400px;
border:#555555 2px solid;
}
...
<div id="mapDiv" class="map"></div>
If you do not specify a width/height, the width/height of the div is used. For cross-
browser compatibility, you should always specify the position attribute (both
"absolute" and "relative" are valid values). If you use a percentage width and or
height in the map DIV, it is the percentage of the parent width or height, respectively.
The navigation control, map type selector, and breadcrumb may not work properly if
you use margin to position the map. Use CSS absolute or relative positioning instead.
5. Next, within a new script tag, create a function that can be called when your web page loads.
<script type="text/javascript">
function GetMap()
{
}
</script>
Modify the body tag so that the GetMap function is called onload.
<body onload="GetMap();">

20
6. Finally, create an instance of the Map Class in the GetMap function. You also need to include
a map options object to contain your credentials, which is your Bing Maps Key. See the
Getting a Bing Maps Key topic.
var map = new
Microsoft.Maps.Map(document.getElementById("mapDiv"),
{credentials:"Your Bing Maps Key"});
</script>

The full code is below.
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>


function GetMap()
{
var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),
}

</script>
</head>
<div id='mapDiv' style="position:absolute; width:400px; height:400px;"></div>
</body>
</html>

21
Customizing the Map When Loading
You can also specify other options when the map is first loaded, such as the location, zoom level,
and the imagery of the map. To do this, pass in MapOptions or ViewOptions to the Map
constructor. The code below sets the imagery to Aerial.
var mapOptions = {
credentials: "Your Bing Maps Key",
mapTypeId: Microsoft.Maps.MapTypeId.aerial
}

var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);
Disposing of the Map when you navigate to
another page
If you are displaying a Map on your web page and then navigate to another web page in your
application, you must use the dispose() method to dispose of the map.

Example
The following code shows a complete Web page that loads a map. Valid map types are found in
the MapTypeId Enumeration topic.
<html>
<head>
<title></title>


function GetMap()
{

22
{credentials: "Your Bing Maps Key",
center: new Microsoft.Maps.Location(45.5, -122.5),
mapTypeId: Microsoft.Maps.MapTypeId.road,
zoom: 7});
}
</script>
</head>
<div id='mapDiv' style="position:relative; width:400px; height:400px;"></div>
</body>
</html>
Setting Map Control Parameters
This topic describes map control parameters.
Parameters
The following table contains available parameters for the map control reference.

Parameter Values Description
v 7.0 Specifies a major API version.
The default value is the latest
version, which is 7.0.
s 0, 1 Specifies whether to use SSL.
Set this value equal to 1 to use
SSL. The default value is 0.
mkt See the Localizing the Map
topic for a list of values.
Specifies the language to use for
the map. The default value is "en-
US" (English). See Localizing the
Map for more details.

With new features
currently in preview, you
can show map labels in

23
Parameter Values Description
two languages and show
the local language for
each location. These
preview features are
described in Localizing
the Map.

Setting Parameters
To add a parameter to the map control src URL, add a "?", the parameter, and set it "=" to one of
the allowable values. Use "&" to separate parameters.
The following example sets the map control version to 7.0 and the market to Italian.
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=it-IT">
</script>
See Also
Localizing the Map
This topic describes how to change the map that is displayed.
Setting the Initial Map View
You can set the map view when you first load the map you can use any of the options available in
the MapOptions Object or ViewOptions Object.
The code below initializes the map with a specific view. The imagery displayed is set to Birds eye
using the mapTypeId option. Valid map type IDs are listed in the MapTypeId Enumeration topic.
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

24


function GetMap()
{
var mapOptions = {
credentials: "Your Bing Maps Key",
mapTypeId: Microsoft.Maps.MapTypeId.birdseye,
zoom: 17,
showScalebar: false
}

}
</script>
</head>
</body>
</html>
If you want to change the map after it has loaded, use the setView method of the Map Class. The
ViewOptions Object contains available options that can be set.
The example below sets the map view to the specified zoom level.
<html>
<head>
<title></title>

25



var map = null;

function GetMap()
{
map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:
"Your Bing Maps Key", mapTypeId: Microsoft.Maps.MapTypeId.road});
}

function SetZoom()
{
var zoomLevel = parseInt(document.getElementById('txtZoom').value);
map.setView({zoom:zoomLevel});
}

</script>
</head>
Zoom Level:
<input id="txtZoom" type="text" value="1"/>
<input id="btnZoom" type="button" value="Click to set the zoom level"
onclick="SetZoom();"/>

</body>
</html>

To set the boundaries of the view instead of centering on a point, use the bounds option as shown
in the code below.

26
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

"Your Bing Maps Key"});

var viewBoundaries = Microsoft.Maps.LocationRect.fromLocations(new
Microsoft.Maps.Location(47.618594, -122.347618), new Microsoft.Maps.Location(47.620700, -
122.347584), new Microsoft.Maps.Location(47.622052, -122.345869));

map.setView({ bounds: viewBoundaries});

}

</script>
</head>
</body>
</html>

27
Adding Entities to the Map
This topic describes how to add entities to the map. An Entity can be any one of the following
types: Polygon, Polyline, Pushpin, TileLayer, or EntityCollection. Information about working with
tile layers is in the Working with Tile Layers topic.
Adding Single Entities to the Map
To add a pushpin, polygon, or polyline to the map, simply create your object then add the entity to
the entities property of the map.
Adding a Pushpin
The following code adds a pushpin to the center of the map with the label 1.
<html>
<head>
<title></title>

src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>


function GetMap()
{
// Initialize the map

// Retrieve the location of the map center
var center = map.getCenter();

// Add a pin to the center of the map
var pin = new Microsoft.Maps.Pushpin(center, {text: '1'});

28
map.entities.push(pin);
}

</script>
</head>
</body>
</html>
To add a pushpin to a custom latitude and longitude coordinate, pass the Location object to the
Pushpin constructor, then set the view based on the location as shown below.
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new Microsoft.Maps.Map(document.getElementById("myMap"),
{credentials:"Bing Maps Key"});

// Define the pushpin location
var loc = new Microsoft.Maps.Location(47.592, -122.332);

29
// Add a pin to the map
var pin = new Microsoft.Maps.Pushpin(loc);

// Center the map on the location
map.setView({center: loc, zoom: 10});

}

</script>
</head>
<div id='myMap' style="position:relative; width:400px; height:400px;"></div>
</body>
</html>
Adding a Shape
To add a polyline or a polygon, use the same method used to add a pushpin. First, create your
shape then add it to the entities property of the map. The following code adds a purple polygon to
the map.
<html>
<head>
<title></title>



function GetMap()

30
{
var map = new
Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key"});

// Create a polygon
var vertices = new Array(new Microsoft.Maps.Location(20,-20), new
Microsoft.Maps.Location(20,20), new Microsoft.Maps.Location(-20,20), new
Microsoft.Maps.Location(-20,-20), new Microsoft.Maps.Location(20,-20));
var polygoncolor = new Microsoft.Maps.Color(100,100,0,100);
var polygon = new Microsoft.Maps.Polygon(vertices,{fillColor: polygoncolor,
strokeColor: polygoncolor});

// Add the polygon to the map
map.entities.push(polygon);
}

</script>
</head>
</body>
</html>
Adding Multiple Entities to the Map
If you want to add multiple entities to the map at one time, first create an EntityCollection then
add this collection to the map. The code below adds a polygon with pushpins at its corners.
<html>
<head>
<title></title>

31


function GetMap()
{

// Create the locations
var location1 = new Microsoft.Maps.Location(20,-20);
var location2 = new Microsoft.Maps.Location(20,20);
var location3 = new Microsoft.Maps.Location(-20,20);
var location4 = new Microsoft.Maps.Location(-20,-20);

// Create a polygon
var vertices = new Array(location1, location2, location3, location4,
location1);

// Create the entity collection with the polygon and pushpins at each corner
var polygonWithPins = new Microsoft.Maps.EntityCollection();
polygonWithPins.push(polygon);
polygonWithPins.push(new Microsoft.Maps.Pushpin(location1));

// Add the shape to the map
map.entities.push(polygonWithPins)

32

}

</script>
</head>
</body>
</html>
Changing Entities on the Map
Once entities have been added to the map, you can use the methods of the map entities
collection to change and manipulate those entities. The code implements a button to change the
color of a shape on the map.
<html>
<head>
<title></title>



var map = null;

// Define colors
var blue = new Microsoft.Maps.Color(100, 0, 0, 200);
var green = new Microsoft.Maps.Color(100, 0, 100, 100);
var purple = new Microsoft.Maps.Color(100, 100, 0, 100);

33
function GetMap()
{
map = new

var location4 = new Microsoft.Maps.Location(-20, -20);
var location5 = new Microsoft.Maps.Location(40, 0);

// Create some shapes
var triangleVertices = new Array(location1, location2, location5, location1);
var triangle = new Microsoft.Maps.Polygon(triangleVertices, { fillColor:
blue, strokeColor: blue });

var squareVertices = new Array(location1, location2, location3, location4,
location1);
var square = new Microsoft.Maps.Polygon(squareVertices,{fillColor: purple,
strokeColor:purple});

// Add the shapes to the map
map.entities.push(triangle);
map.entities.push(square);
}

function ChangePolygonColor()
{
// Get the map square entity. We know square was the last entity added,
// so we can calculate the index.
var mapSquare = map.entities.get(map.entities.getLength()-1);

34

// Get the current color
var currentColor = mapSquare.getFillColor();

if((currentColor.toString()) == (purple.toString()))
{
// Change it to green
mapSquare.setOptions({fillColor: green, strokeColor:green});
}
else
{
// Change it back to purple
mapSquare.setOptions({fillColor:purple, strokeColor:purple});
}
}
</script>
</head>
<input id="btnChangeColor" type="button" value="Change Polygon Color"
onclick="ChangePolygonColor();"/>
</body>
</html>

Customizing Your Pushpins
The Bing Maps AJAX Control, Version 7.0 provides flexible pushpin functionality. Use options
provided in the PushpinOptions Object to customize your pushpins.
This topic describes how to customize your pushpin icon as well as how to create a pushpin info
box.

35
Customizing Your Pushpin Icon
If you do not want to use the default pushpin icon, you can set the icon property of the
PushpinOptions to the image you want to use instead.
This example uses the image below, named BluePushpin.png, as the pushpin icon.

<html>
<head>
<title></title>



var map = null;

function GetMap()
{


// Add a pin to the center of the map, using a custom icon
var pin = new Microsoft.Maps.Pushpin(center, {icon: 'BluePushpin.png', width:
50, height: 50, draggable: true});

36

}

</script>
</head>
</body>
</html>

Creating a Pushpin Infobox
The Bing Maps AJAX Control, Version 7.0 has built-in pushpin info box functionality which you
can customize to suit the needs of your application. To create an info box, use the Infobox and
InfoboxOptions types.
The example below shows how to display an info box when a pushpin is clicked.
<html>
<head>
<title></title>



var map = null;
var pinInfobox = null;

function GetMap()

37
{



// Create the infobox for the pushpin
pinInfobox = new Microsoft.Maps.Infobox(pin.getLocation(),
{title: 'My Pushpin',
description: 'This pushpin is located at (0,0).',
visible: false,
offset: new Microsoft.Maps.Point(0,15)});

// Add handler for the pushpin click event.
Microsoft.Maps.Events.addHandler(pin, 'click', displayInfobox);

// Hide the infobox when the map is moved.
Microsoft.Maps.Events.addHandler(map, 'viewchange', hideInfobox);

// Add the pushpin and infobox to the map
map.entities.push(pinInfobox);

}

function displayInfobox(e)
{
pinInfobox.setOptions({ visible:true });

38
}

function hideInfobox(e)
{
pinInfobox.setOptions({ visible: false });
}
</script>
</head>
</body>
</html>
Displaying Location Search Results Using
the REST Services
The Bing Maps AJAX Control, version 7.0 does not have built in functionality to return find results,
but you can easily use the Bing Maps REST Services to geocode locations that you can then
display on the map.
Initialize the Map
Before you add geocoding functionality, initialize the map using the following code.
<html>
<head>
<title></title>



39
var map = null;

function GetMap()
{
map = new
Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key",
mapTypeId:Microsoft.Maps.MapTypeId.road});

}

</script>
</head>
</body>
</html>
Add Controls
For this sample, add a text box and a Geocode button. In your script, create a ClickGeocode
function that is called when the button is clicked.
<input id="txtQuery" type="text" value="Portland"/>
<input type="button" value="Geocode" onclick="ClickGeocode()"/>

Since the Bing Maps REST Services also require a Bing Maps Key, you need to first retrieve the
key from the map object to ensure the session is valid. Use the getCredentials method of the
Map Class to do this. The getCredentials method takes a function to call when the credentials
are retrieved.
function ClickGeocode(credentials)
{
map.getCredentials(MakeGeocodeRequest);
}

40
Make a Geocode REST Request
Next, make a geocode request to the Bing Maps REST Services using the value in the txtQuery
input box and the credentials.
The Bing Maps REST Services can return an XML or JSON response object. For JavaScript
code, JSON is more appropriate, so set output=JSON. This means that you need to also set a
jsonp callback function name. In this sample the callback function is named GeocodeCallback.
Finally, since you do not know if the text provided is a place name or an address, supply the
locationQuery parameter and set it to the value of the txtQuery text box. Your REST geocode
request looks like this:
var geocodeRequest = "http://dev.virtualearth.net/REST/v1/Locations?query=" +
encodeURI(document.getElementById('txtQuery').value) +
"&output=json&jsonp=GeocodeCallback&key=" + credentials;
Now add script to make the REST request.
function MakeGeocodeRequest(credentials)
{

CallRestService(geocodeRequest);
}

function CallRestService(request)
{
var script = document.createElement("script");
script.setAttribute("type", "text/javascript");
script.setAttribute("src", request);
document.body.appendChild(script);
}
function GeocodeCallback(result)
{
// Do something with the result
}

41
Display the Results
Finally, add code to the GeocodeCallback function to set the map view to the found location and
add a pushpin at that location. The final code is shown below.
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new
mapTypeId:Microsoft.Maps.MapTypeId.road});

}

function ClickGeocode(credentials)
{
map.getCredentials(MakeGeocodeRequest);
}

function MakeGeocodeRequest(credentials)
{

42

CallRestService(geocodeRequest);
}

function GeocodeCallback(result)
{
alert("Found location: " + result.resourceSets[0].resources[0].name);

if (result &&
result.resourceSets &&
result.resourceSets.length > 0 &&
result.resourceSets[0].resources &&
result.resourceSets[0].resources.length > 0)
{
// Set the map view using the returned bounding box
var bbox = result.resourceSets[0].resources[0].bbox;
Microsoft.Maps.Location(bbox[0], bbox[1]), new Microsoft.Maps.Location(bbox[2],
bbox[3]));

// Add a pushpin at the found location
var location = new
Microsoft.Maps.Location(result.resourceSets[0].resources[0].point.coordinates[0],
result.resourceSets[0].resources[0].point.coordinates[1]);
var pushpin = new Microsoft.Maps.Pushpin(location);
map.entities.push(pushpin);
}
}

{

43
}

</script>
</head>
<input id="txtQuery" type="text" value="Portland"/>
<input type="button" value="Geocode" onclick="ClickGeocode()"/>
</body>
</html>
Getting Route Directions Using the REST
Services
The latest release of the Bing Maps AJAX Control 7.0 provides directions functionality in
the Microsoft.Maps.Directions module. This module allows you to easily customize,
calculate, and display directions and a route on your web site without needing to use
REST services. Get started by going to the DirectionsManager Class topic, which
contains information about the calculateDirections method and sample code.
This topic describes how to use the Bing Maps REST Services to calculate and display a route on
the map.
Initialize the Map
Before you add route functionality, initialize the map using the following code.
<html>
<head>
<title></title>

44



var map = null;

function GetMap()
{
map = new
mapTypeId: Microsoft.Maps.MapTypeId.road });

}

</script>
</head>
</body>
</html>
Construct the Route Request
Next, add input controls and construct the Bing Maps REST Services Route request.
In this example, a route is calculated between a specified start and end point. Add two text boxes
and a button to initiate the route calculation.
<input id="txtStart" type="text" value="Seattle"/>
<input id="txtEnd" type="text" value="Portland"/>
<input type="button" value="Calculate Route" onclick="ClickRoute()"/>

Then, construct the REST route request using the input values.

45
var routeRequest = "http://dev.virtualearth.net/REST/v1/Routes?wp.0=" +
document.getElementById('txtStart').value + "&wp.1=" +
document.getElementById('txtEnd').value +
"&routePathOutput=Points&output=json&jsonp=RouteCallback&key=" + credentials;

Display the Results
Finally, add code to make the route request when the button is clicked, and add code to the
RouteCallback function to set the map view and draw the route. The final code is shown below.
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

function ClickRoute(credentials)
{

46

map.getCredentials(MakeRouteRequest);
}

function MakeRouteRequest(credentials)
{
var routeRequest = "http://dev.virtualearth.net/REST/v1/Routes?wp.0=" +
document.getElementById('txtStart').value + "&wp.1=" +
document.getElementById('txtEnd').value +
"&routePathOutput=Points&output=json&jsonp=RouteCallback&key=" + credentials;

CallRestService(routeRequest);

}

function RouteCallback(result) {

if (result &&
result.resourceSets &&
result.resourceSets.length > 0 &&
result.resourceSets[0].resources &&
result.resourceSets[0].resources.length > 0) {

// Set the map view
Microsoft.Maps.Location(bbox[0], bbox[1]), new Microsoft.Maps.Location(bbox[2],
bbox[3]));

// Draw the route

47
var routeline = result.resourceSets[0].resources[0].routePath.line;
var routepoints = new Array();

for (var i = 0; i < routeline.coordinates.length; i++) {

routepoints[i]=new
Microsoft.Maps.Location(routeline.coordinates[i][0], routeline.coordinates[i][1]);
}

// Draw the route on the map
var routeshape = new Microsoft.Maps.Polyline(routepoints,
{strokeColor:new Microsoft.Maps.Color(200,0,0,200)});
map.entities.push(routeshape);

}
}

{
}

</script>
</head>
<input id="txtStart" type="text" value="Seattle"/>
<input id="txtEnd" type="text" value="Portland"/>
<input type="button" value="Calculate Route" onclick="ClickRoute()"/>

48
</body>
</html>
This topic describes how to add a custom tile layer to the map.
Adding a Tile Layer
A tile layer is a valid map entity, so after you construct your layer, you can add it to the map using
the push method of the map entities collection. The code below adds a custom tile layer to the
map.
<html>
<head>
<title></title>



function GetMap()
{
var map = new
center:new Microsoft.Maps.Location(48.03,-122.4), zoom:12, mapTypeId:
Microsoft.Maps.MapTypeId.road });

try
{
// Create the tile layer source

49
var tileSource = new Microsoft.Maps.TileSource({uriConstructor:
'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png'});

// Construct the layer using the tile source
var tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource,
opacity: .7 });

// Push the tile layer to the map
map.entities.push(tilelayer);

}
catch(err)
{
alert( 'Error Message:' + err.message);
}
}

</script>
</head>
</body>
</html>
Using Events in the AJAX Control
The Bing Maps AJAX Control 7.0 provides many events to allow your application to respond to
user actions. The EntityCollection, Map, Pushpin, Polyline, and Polygon classes all have event
members. The code examples in this topic show how to use the Map click event and the
EntityCollection entityadded event.
Example
The example below shows how to use the Map click event to display the coordinate values of
the clicked point in a text box.

50
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

//Add handler for the map click event.
Microsoft.Maps.Events.addHandler(map, 'click', displayLatLong);

}

function displayLatLong(e) {
if (e.targetType == "map") {
var point = new Microsoft.Maps.Point(e.getX(), e.getY());
var loc = e.target.tryPixelToLocation(point);
document.getElementById("textBox").value= loc.latitude + ", " +
loc.longitude;

}

51
}

</script>
</head>
<div id='myMap' style="position:relative; width:400px; height:400px;"></div><br>
<b>Click the map to display the coordinate values at that point.</b><br>
Latitude, Longitude:
<input id='textBox' type="text" style="width:250px;"/>
</body>
</html>
You can expand the example above and add a pushpin wherever the user clicks. The code below
also greys out the other pushpins in the entities collection when a new one is added.
<html>
<head>
<title></title>



var map = null;
var noPins = true;

function GetMap()
{

52
// Add a handler for the map click event.
Microsoft.Maps.Events.addHandler(map, 'click', addPin);

// Add a handler to function that will grey out
// other pins in the collection when a new one is added
Microsoft.Maps.Events.addHandler(map.entities, 'entityadded', shadePins);

}

function addPin(e) {

}
}

function shadePins(e) {

if (noPins) {

// If there aren't yet any pins on the map, do not grey the pin out.
noPins = false;

}
else
{
var pin = null;

// Loop through the collection of pushpins on the map and grey out

53
// all but the last one added (which is at the end of the array).
var i = 0;
for (i = 0; i < e.collection.getLength() - 1; i++)
{
pin = e.collection.get(i);
pin.setOptions({ icon: "GreyPin.png" });
}
}
}

</script>
</head>
<b>Click the map to add a pushpin at that point.</b><br>
</body>
</html>
Localizing the Map
The Bing Maps AJAX Control 7.0 provides the ability to return a localized map and route
directions.
Setting the Language
By default, the map labels, navigation control text and directions are provided in the United States
English (en-US). You can localize the map for other languages by setting the mkt parameter in
the map control reference. For example, the following map control reference sets the mkt
parameter to the culture fr-fr.
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=fr-
fr"></script>
The culture code fr-fr stands for French-France and specifies that the version of French spoken in
France be used as the language for the map. For more language options, see the Supported
Cultures table below.

54
[Feature preview] Show map labels in two
languages on the same map
The following preliminary documentation is for a feature that displays two
languages on a map. This feature is released as a preview and is subject to
change. You cannot use this feature in Windows Store apps.
You can display map labels in two languages when you specify a primary language and a
secondary language in the map control reference.
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=primary,seconda
ry"></script>
When you specify a primary and a secondary language and both languages are supported for
map labels, then localized map labels are displayed for both languages when they are available.
The primary language is used for map labels, the navigation control and directions when
supported.
The following example displays both Russian-Russia (ru-ru) and English-United States (en-US)
map labels, and will provide navigation control text and directions using Russian (ru-ru).
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=ru-ru,en-
us"></script>
The following screenshots show how the map labels will appear for this example.

55

56

[Feature Preview] Display map labels in the local
language using the ngt option
The following preliminary documentation is for a feature that shows map labels in
the local language. This feature is released as a preview and is subject to change.
You cannot use this feature in Windows Store apps.
You can display map labels in the local language of each country or region on the map by
specifying the custom value ngt as the language value. Ngt stands for neutral ground truth.
When you specify this value, you can view map labels that you would see on the ground. For
example, if you want to display the navigation control text in Russian-Russia and show map
labels in both French and Russian when viewing a map of France, set the mkt parameter to
mkt=ru-ru,ngt. Note that the ngt option does not apply to directions or to the navigation control.
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=ru-
ru,ngt"></script>

57
Examples
Examples that show more than one language or that use the 'ngt' parameter are
examples of preview features. Preview features are subject to change.
The following examples show how various mkt settings affect the localization of the map.

mkt parameter Navigation Control Map Labels Directions
default (mkt not
specified)
en-US en-US en-US
mkt=ngt en-US local language en-US
mkt=fr-FR fr-FR fr-FR fr-FR
mkt=fr-FR,ngt fr-FR fr-FR, local language fr-FR
mkt=ngt,fr-FR
Note that fr-FR is used
for the navigation
control and directions
because ngt only
applies to map labels.
fr-FR local language, fr-FR fr-FR
mkt=es-ES,fr-FR es-ES es-ES,fr-FR es-ES

Supported Cultures
The following table lists supported cultures for map labels, the navigation control and the
Microsoft.Maps.Directions module. The Culture column lists values to specify for the mkt
parameter.

Language -
Country/Region
Culture Map Labels Navigation
Control
Microsoft.Maps.Directions
module
All ngt X
Czech Czech
Republic
cs-CZ X X
Danish Denmark da-DK X X
Dutch - Belgium nl-BE X X
Dutch
Netherlands
nl-NL X X X

58
Language -
Country/Region
Control
module
English - Australia en-AU X X
English Canada en-CA X X X
English - India en-IN X X X
English - United
Kingdom
en-GB X X X
English - United
States
en-US X X X
Finnish Finland fi-FI X X
French-Belgium fr-BE X X
French Canada fr-CA X X X
French-Switzerland fr-CH X X
French France fr-FR X X X
German
Germany
de-DE X X X
Italian Italy it-IT X X X
Japanese - Japan ja-JP X X X
Korean-Korea Kr-KO X X
Norwegian
(Bokmal) - Norway
nb-NO X X X
Polish - Poland pl-PL X X X
Portuguese - Brazil pt-BR X X
Portuguese -
Portugal
pt-PT X X
Russian - Russia ru-RU X X X
Spanish - Mexico es-MX X X X
Spanish - Spain es-ES X X X
Spanish United
States
es-US X X X
Swedish - Sweden sv-SE X X X

59
Language -
Country/Region
Control
module
Chinese - China zh - CH X X X
Chinese - Taiwan zh - TW X X X

Localization of Error Messages
Error messages are always displayed in English - United States.
The Bing Maps AJAX Control 7.0 allows you to easily register and load your own script modules.
This topic describes how to create a simple module.
Develop Your Module
Begin by developing your module. The sample module below takes a map object as its
constructor and exposes a method to draw a red arrow pointing to a given location.
// arrowmodule.js

function ArrowModule(map)
{
// Use the given location to draw an arrow pointing to that spot
this.drawRedArrow = function(location)
{
// Initialize the polygon locations
var points = new Array(8);
points[0] = location;
points[1] = new Microsoft.Maps.Location(location.latitude+10,
location.longitude);
location.longitude-5);

60
points[6] = new Microsoft.Maps.Location(location.latitude, location.longitude-
10);
points[7] = location;

// Create the arrow
var red = new Microsoft.Maps.Color(200, 200, 0, 0);
var arrow = new Microsoft.Maps.Polygon(points, {strokeColor:red,
fillColor:red});

map.entities.push(arrow);

}

}
Microsoft.Maps.moduleLoaded('ArrowModule');

Note that the last line of the module calls the Microsoft.Maps.moduleLoaded method, which
calls the main code callback function.
After you have finished implementing your module, host your module script file on a web server.
Register and Load Your Module
After you have created your module and hosted it, register it within your map control application
using the Microsoft.Maps.registerModule method.
Microsoft.Maps.registerModule("ArrowModule", "http://example.com/arrowmodule.js");
Next, load your module using the Microsoft.Maps.loadModule method, specifying the function
to call when the module is loaded.
Microsoft.Maps.loadModule("ArrowModule", { callback: myModuleLoaded });
Use Your Module
Finally, use the functions provided by your module in your map control code. The sample code
below uses the drawRedArrow method of the ArrowModule to draw an arrow pointing to the
center of the map.

61
<html>
<head>
<title></title>



var map;

function myModuleLoaded()
{
// When the module is fully loaded, then this function is called.
// Now you can initialize a module object and use the module function to
// draw an arrow pointing to the center of the map.
var arrowModule = new ArrowModule(map);
arrowModule.drawRedArrow(map.getCenter());
}

function GetMap()
{
var options = {credentials: "Bing Maps Key"};
map = new Microsoft.Maps.Map(document.getElementById('mapDiv'), options);

// Register and load the arrow module
Microsoft.Maps.registerModule("ArrowModule",
"http://example.com/arrowmodule.js");
Microsoft.Maps.loadModule("ArrowModule", { callback: myModuleLoaded });

62
}

</script>
</head>
<div id='mapDiv' style="position:relative; width:400px;
</body>
</html>

See Also
Module Loading Methods
Developing a Windows Store app
This topic outlines how to use the Bing Maps AJAX Control 7.0 to develop a Windows Store app
using JavaScript. Note that the instructions for developing a Windows Store app using AJAX v7
are different than for other applications.
If you are interested in developing a Windows Store app using C#/C++/VB, see Getting
Started with Bing Maps in Windows Store Apps.
Adding a map to your Windows Store app
Requirements
Windows 8.1 and Visual Studio 2013 The recommended environment for developing a
Windows Store app includes Windows 8.1, Visual Studio 2013 and the Bing Maps SDK for
Windows Store apps (for Windows 8.1). Other options are available. For information, see the
Windows Platform Compatibility. For the latest release information, see Release History for
Bing Maps for Windows Store Apps.
Bing Maps Key A Bing Maps Key is required to create a Windows Store app. To view
licensing options, see the Licensing Tool. If you determine you qualify for free use or if you

63
want to try out the API, you can create a Basic key. For the steps to create a key, see Getting
a Bing Maps Key.
Supported languages: For a list of supported languages, see Localizing the Map. The method
for setting the language in JavaScript is shown below.
Create a Visual Studio project and reference the Bing Maps SDK
The following steps show you how to create Windows Store app project and then add the map
control.
1. Make sure you have downloaded and installed the Bing Maps SDK for Windows Store apps
(for Windows 8.1) with Windows 8.1 and Visual Studio 2013.
2. Start Microsoft Visual Studio. From the main menu, select File, New, then Project. In the
New Project dialog, choose JavaScript as the language, select Windows Store, and then
choose Blank App. Type a name for your application, and click OK to create the project.
3. In Solution Explorer, right-click References for your project and select Add Reference.
Expand Windows and then select Extensions. Select Bing Maps for JavaScript, and then
click OK to add the reference. The default installation path for the Bing Maps SDK for
Windows Store apps is C:\Users\<username>\AppData\Local\Microsoft
SDKs\Windows\v8.0\ExtensionSDKs\Bing.Maps.JavaScript
4. Open the default.html file and insert a reference to veapicore.js.

<script type="text/javascript" src="ms-
appx:///Bing.Maps.JavaScript//js/veapicore.js"></script>
5. Add the following JavaScript code to load a module that downloads a necessary configuration
file. Make sure to insert your Bing Maps Key.
Microsoft.Maps.loadModule('Microsoft.Maps.Map', { callback:
initMap, culture: "en-us", homeRegion: "US"});
function initMap() {
var map;

var mapOptions =
{
credentials: "INSERT_YOUR_BING_MAPS_KEY"
};

map = new
Microsoft.Maps.Map(document.getElementById("mapDiv"),
mapOptions);
}

64
6. Replace the placeholder content with the following JavaScript code.
<div id="mapDiv"> </div>
When you load the module, you can specify the callback function that loads the map as well as
the culture parameter that determines the localized language and the homeRegion parameter that
specifies the user region using the ISO 3166-1 Alpha-2 country code for the region. For a list of
language codes that you can use, see Localizing the Map.
Now you can use the Bing Maps AJAX Control 7.0 API to create your Windows Store app.
Additional Notes and a code Example are found below.
Additional Notes
All of the APIs available for the standard Bing Maps AJAX Control are supported for Windows
Store apps.
When your application leaves a web page that contains the map control to go to another web
page, you must use the dispose() function on the map object (map.dispose()) before leaving
the page with the map.
The Bing Maps AJAX Control 7.0 modules are all supported, including
Microsoft.Maps.AdvancedShapes, Microsoft.Maps.Directions, Microsoft.Maps.Search,
Microsoft.Maps.Themes.BingTheme, Microsoft.Maps.Traffic, and
Microsoft.Maps.VenueMaps. To use a module, you must include a reference to
veapimodules.js, as shown below.

appx:///Bing.Maps.JavaScript//js/veapimodules.js"></script>
To use a custom module, register the module before referencing the module *.js file:
<script>Microsoft.Maps.registerModule('myCustomModule');</script
>
src="/js/myCustomModule.js"></script>
You can then load the module and invoke the callback function anywhere within your code:
Microsoft.Maps.loadModule('myCustomModule', { callback:
customModuleLoaded });
To make a REST service request, use the Windows 8 xhr handler:
// Use the Bing Maps REST Service to return driving directions
function restDirections()
{
map.getCredentials( function(credentials)

65
{
var start= 'Boston, MA'; var end= 'NY, NY';
var routeRequest =
'http://dev.virtualearth.net/REST/v1/Routes?wp.0=' + start +
'&wp.1=' + end + '&routePathOutput=Points&output=json&key=' +
credentials;
WinJS.xhr({ url: routeRequest }).then(routeCallback);
});
}

// Route service callback function
function routeCallback(result)
{
result = JSON.parse(result.responseText);
}
Windows 8 provides enhanced Web content security that may affect some JavaScript
functionality. For more information, see the topic HTML, CSS, and JavaScript features and
differences (Windows Store apps).
Example
The following code demonstrates a variety of functionality in a Windows Store app.
//default.html
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=1024, height=768" />
<title>BingMaps-JavaScript-SDK</title>

<script src="//Microsoft.WinJS.1.0/js/base.js"></script>
<script src="//Microsoft.WinJS.1.0/js/ui.js"></script>
<link href="//Microsoft.WinJS.1.0/css/ui-dark.css" rel="stylesheet" />


66
appx:///Bing.Maps.JavaScript//js/veapiModules.js"></script>

<link href="/css/default.css" rel="stylesheet">
<script type="text/javascript" src="/js/default.js"></script>

<script>Microsoft.Maps.registerModule('clusterModule');</script>
<script type="text/javascript" src="js/V7ClientSideClustering.js"></script>

</head>
<body>
<div id="content">
<div id="header"> </div>
<div id="directionsItinerary"> </div>
<div id="mapdiv"> </div>
<button id="setView">BirdsEye Mode</button>
<button id="panRight">Pan right</button>
<button id="pushpin">Pushpin</button>
<button id="customPushpin">Custom pin</button>
<button id="polygon">Polygon</button>
<button id="infobox">Infobox</button>
<button id="tilelayer">Tilelayer</button>
<button id="vm">Venue Map</button>
<button id="cm">Custom Module</button>
<button id="restDirections">Rest Directions</button>
<button id="traffic">Traffic</button>
<button id="bingTheme">Bing Theme</button>
<button id="complexShapes">Shape w/ Hole</button>
<button id="directions">Directions</button>
<button id="geocode">Geocode</button>
<button id="revGeocode">Rev GeoCode</button>
<button id="search">Search</button>
<button id="clear">Clear Map</button>

67
<button id="close">Close App</button>
</div>
</body>
</html>

//default.js
//default.js
(function () {
var app = WinJS.Application;

// This function responds to all application activations.
app.onactivated = function (eventObject) {
if (eventObject.detail.kind ===
Windows.ApplicationModel.Activation.ActivationKind.launch) {

WinJS.UI.processAll();
}
};

app.start();

// set view api to show Birdseye view
function setView()
{
resetMapDiv();
map.setView({ center: new Microsoft.Maps.Location(47.6215, -122.349329),
mapTypeId: Microsoft.Maps.MapTypeId.auto, zoom: 18 });
}
// set view api to pan map
function pan(x, y)
{
resetMapDiv();
var mapCenter = map.getCenter();

68
var pos = map.tryPixelToLocation(new Microsoft.Maps.Point(map.getWidth() / 2 + x,
map.getHeight() / 2 - (y - 1)),
Microsoft.Maps.PixelReference.control);
mapCenter.latitude += pos.latitude - mapCenter.latitude;
mapCenter.longitude += pos.longitude - mapCenter.longitude;
map.setView({ center: mapCenter });
}
// api to add pin on map
function addPushpin()
{
resetMapDiv();
var pushpin = new Microsoft.Maps.Pushpin(map.getCenter(), null);
}

// api to add custom pin on map
function addCustomPushpin() {
resetMapDiv();
var pushpinOptions = {width: null, height: null, htmlContent:
"<div style='font-size:12px;font-weight:bold;border:solid
2px;background-color:Blue;width:100px;'>Custom Pushpin</div>"};
var pushpin = new Microsoft.Maps.Pushpin(map.getCenter(), pushpinOptions);
}

// api to add polygon on map
function addPolygon()
{
resetMapDiv();
addCircle(center.latitude, center.longitude);
}
// add circle on map
function addCircle(latitude, longitude)

69
{
resetMapDiv();
var radius;
var zoom = map.getZoom();
// calculate radius in KMs based on zoom level so that circle is displayed in
current bounds
switch (Math.floor(zoom / 4)) {
case 0:
radius = 500;
break;
case 1:
radius = 100;
break;
case 2:
radius = 50;
break;
case 3:
radius = 5;
break;
default:
radius = 0.1;
break;

}

var R = 6371; // earth's mean radius in km
var lat = (latitude * Math.PI) / 180;
var lon = (longitude * Math.PI) / 180;
var d = parseFloat(radius) / R;
var circle= new Array();
for (var x = 0; x <= 360; x++) {
var r = x * Math.PI / 180; //rad
var cirLat = Math.asin(Math.sin(lat) * Math.cos(d) + Math.cos(lat) *
Math.sin(d) * Math.cos(r));

70
var cirLong = ((lon + Math.atan2(Math.sin(r) * Math.sin(d) * Math.cos(lat),
Math.cos(d) - Math.sin(lat) * Math.sin(cirLat))) *
180) / Math.PI;
cirLat = (cirLat * 180) / Math.PI;
circle.push(new Microsoft.Maps.Location(cirLat, cirLong));
}
var polygoncolor = new Microsoft.Maps.Color(Math.round(255 * Math.random()),
Math.round(255 * Math.random()), Math.round(255 *
Math.random()), Math.round(255 * Math.random()));
var polygon = new Microsoft.Maps.Polygon(circle, { fillColor: polygoncolor,
strokeColor: polygoncolor });
}
// api to add infobox on map
function addInfobox()
{
resetMapDiv();
map.entities.clear();
var pushpin = new Microsoft.Maps.Pushpin(map.getCenter(), { zIndex: 3 });
var infoboxOptions = { zIndex: 4 };
var defaultInfobox = new Microsoft.Maps.Infobox(map.getCenter(), infoboxOptions);
map.entities.push(defaultInfobox);
}
// api to add tilelayer on map
function addtilelayer()
{
resetMapDiv();
var options = { uriConstructor:
'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png', width: 256, height:
256 };

var tileSource = new Microsoft.Maps.TileSource(options);
var tilelayer = new Microsoft.Maps.TileLayer({ mercator: tileSource });

71

//center map to show tile layer
map.setView({ center: new Microsoft.Maps.Location(48.03, -
122.42), zoom: 11 });
}

function addtraffic()
{
resetMapDiv();
Microsoft.Maps.loadModule('Microsoft.Maps.Traffic', { callback:
trafficModuleLoaded });
}

function trafficModuleLoaded()
{
//set center
map.setView({ center: new Microsoft.Maps.Location(40.71, -74.00), zoom: 8 });
var trafficManager = new Microsoft.Maps.Traffic.TrafficManager(map);
// show the traffic Layer
trafficManager.show();
}
function addBingThemeMap()
{
resetMapDiv();
Microsoft.Maps.loadModule('Microsoft.Maps.Themes.BingTheme', {
callback: function () {
var id = 'Your Bing Maps Key';
map = new Microsoft.Maps.Map(document.getElementById('mapdiv'),
{
credentials: id,

72
zoom: 10,
theme: new Microsoft.Maps.Themes.BingTheme()
});
var pin1 = new Microsoft.Maps.Pushpin(map.getCenter(), null);
map.entities.push(pin1);
map.entities.push(new Microsoft.Maps.Infobox(map.getCenter(), { title:
'Seattle', description: 'description here', pushpin:
pin1 }));
var pin2 = new Microsoft.Maps.Pushpin(new Microsoft.Maps.Location(47.45,
-122.33), null);
map.entities.push(new Microsoft.Maps.Infobox(new
Microsoft.Maps.Location(47.45, -122.33), { title: 'Tacoma', description:
'description here', pushpin: pin2 }));
}
});
}

function addComplexShapes()
{
resetMapDiv();
Microsoft.Maps.loadModule('Microsoft.Maps.AdvancedShapes', {

var polygon = new Microsoft.Maps.Polygon([
[new Microsoft.Maps.Location(47.604, -121.940),
new Microsoft.Maps.Location(47.604, -121.540),
new Microsoft.Maps.Location(47.604, -121.940)],

73
new Microsoft.Maps.Location(47.744, -121.700)]]);
map.setView({ zoom: 11, center: new Microsoft.Maps.Location(47.704, -
121.740) });
}
});
}
// api to load custom module
function customModule()
{
resetMapDiv();
Microsoft.Maps.loadModule('clusterModule', { callback: customModuleLoaded });
map.setView({ zoom: 1, center: new Microsoft.Maps.Location(0, 0), mapTypeId:
}

// custom module callback
function customModuleLoaded()
{

testDataGenerator.generateData(100, dataCallback);
}
// api to load venue map module on map
function addVM()
{
resetMapDiv();
Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: vmCallback });
}

74
// venue map module callback
function vmCallback()
{
var venueMapFactory = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);
venueMapFactory.create({
venueMapId: 'hcl-timessquare',
success: success,
error: err
});
}
// error callback for venue map
function err(errorCode, args)
{
var message = 'Error while loading venue map. Errorcode : ' + errorCode;
var md = new Windows.UI.Popups.MessageDialog(message);
md.showAsync();
}

// success callback from venue map callback
function success(venueMap, args)
{
venueMap.show();
map.setView(venueMap.bestMapView);
}

var searchManager = null;
var currInfobox = null;
// callback function to create searchManager once search module is loaded
function createSearchManager()
{
if (!searchManager)
{
map.addComponent('searchManager', new
Microsoft.Maps.Search.SearchManager(map));

75
searchManager = map.getComponent('searchManager');
}
}

// business search api request
function search()
{
resetMapDiv();
if (searchManager)
{
searchRequest();
}
else
{
Microsoft.Maps.loadModule('Microsoft.Maps.Search', { callback: searchRequest
});
}
}

// business search api
function searchRequest()
{
createSearchManager();
var what = 'pizza';
var userData = { name: 'Maps Test User', id: 'XYZ' };
var where = 'boston, ma';
var query = '';
var request =
{
what: what,
where: where,
query: query,
count: 10,
startIndex: 0,

76
bounds: map.getBounds(),
callback: search_onSearchSuccess,
errorCallback: search_onSearchFailure,
userData: userData
};
searchManager.search(request);
}

// business search api success callback
function search_onSearchSuccess(result, userData)
{
var searchResults = result && result.searchResults;
if (searchResults)
{
for (var i = 0; i < searchResults.length; i++)
{
search_createMapPin(searchResults[i]);
}

if (result.searchRegion && result.searchRegion.mapBounds)
{
map.setView({ bounds: result.searchRegion.mapBounds.locationRect });
}
}
}
// business search api failure callback
function search_onSearchFailure(result, userData)
{
var md = new Windows.UI.Popups.MessageDialog("Search failed");
md.showAsync();
}

// business search api display search results

77
function search_createMapPin(result)
{
if (result)
{
var pin = new Microsoft.Maps.Pushpin(result.location, null);
Microsoft.Maps.Events.addHandler(pin, 'click', function () {
search_showInfoBox(result) });
}
}

// business search api infobox
function search_showInfoBox(result)
{
if (currInfobox)
{
currInfobox.setOptions({ visible: true });
map.entities.remove(currInfobox);
}
currInfobox = new Microsoft.Maps.Infobox(
result.location,
{
title: result.name,
description: [result.address, result.city, result.state, result.country,
result.phone].join(" "),
showPointer: true,
titleAction: null,
titleClickHandler: null
});

map.entities.push(currInfobox);
}

78
// reverse geocode api request
function reverseGeocode()
{
resetMapDiv();
if (searchManager)
{
reverseGeocodeRequest();
}

else
{
Microsoft.Maps.loadModule('Microsoft.Maps.Search', { callback:
reverseGeocodeRequest });
}
}

// reverse geocode api
function reverseGeocodeRequest()
{
var request =
{
location: map.getCenter(),
callback: onReverseGeocodeSuccess,
errorCallback: onReverseGeocodeFailed,
userData: userData
};
searchManager.reverseGeocode(request);
}

// reverse geocode api request success callback
function onReverseGeocodeSuccess(result, userData)
{

79
if (result)
{
var pushpin = new Microsoft.Maps.Pushpin(result.location, null);
map.setView({ center: result.location, zoom: 10 });
}
}

// reverse geocode api request failure callback
function onReverseGeocodeFailed(result, userData)
{
var md = new Windows.UI.Popups.MessageDialog("Reverse Geocode failed");
md.showAsync();
}

// geocode api request
function geocode()
{
resetMapDiv();
if (searchManager)
{
geocodeRequest();
}
else
{
Microsoft.Maps.loadModule('Microsoft.Maps.Search', { callback: geocodeRequest
});
}
}

function geocodeRequest()
{

80
var where = 'Denver, CO';
var request =
{
where: where,
count: 2,
callback: onGeocodeSuccess,
errorCallback: onGeocodeFailed,
userData: userData
};
searchManager.geocode(request);
}

// geocode api request success callback
function onGeocodeSuccess(result, userData)
{
if (result)
{
var MM = Microsoft.Maps;
var topResult = result.results && result.results[0];
if (topResult)
{
var pushpin = new MM.Pushpin(topResult.location, null);
map.setView({ center: topResult.location, zoom: 10 });
}
}
}

// geocode api request failure callback
function onGeocodeFailed(result, userData)

81
{
var md = new Windows.UI.Popups.MessageDialog("Geocode failed");
md.showAsync();
}

// api to use Rest direction service
function getDirections()
{
{
var start= 'Boston, MA'; var end= 'New York, NY';
var routeRequest = 'http://dev.virtualearth.net/REST/v1/Routes?wp.0=' + start
+ '&wp.1=' + end +
'&routePathOutput=Points&output=json&key=' + credentials;
});
}
// route callback
function routeCallback(result) {
result = JSON.parse(result.responseText);
if (result && result.resourceSets && result.resourceSets.length > 0
&& result.resourceSets[0].resources && result.resourceSets[0].resources.length >
0
&& result.resourceSets[0].resources[0].routeLegs.length > 0)
{
// instruction list can be displayed using the code below
var resultsListItem = null;
var resultsList = document.createElement("ol");
for (var i = 0; i <
result.resourceSets[0].resources[0].routeLegs[0].itineraryItems.length; ++i)
{
resultsListItem = document.createElement("li");
resultsList.appendChild(resultsListItem);

82
var resultStr =
result.resourceSets[0].resources[0].routeLegs[0].itineraryItems[i].instruction.text;
resultsListItem.innerHTML = resultStr;
}
Microsoft.Maps.Location(bbox[0],
bbox[1]), new
Microsoft.Maps.Location(bbox[2], bbox[3]));
var routeline = result.resourceSets[0].resources[0].routePath.line;
var routepoints = new Array();
for (var i = 0; i < routeline.coordinates.length; i++) {
routepoints[i]=new Microsoft.Maps.Location(routeline.coordinates[i][0],
routeline.coordinates[i][1]);
}
var routeshape = new Microsoft.Maps.Polyline(routepoints, {strokeColor:new
Microsoft.Maps.Color(200,0,0,200)});
var startPushpinOptions = { icon: '/images/start.png', anchor: new
Microsoft.Maps.Point(3, 28) };
var startPin= new Microsoft.Maps.Pushpin(new
Microsoft.Maps.Location(routeline.coordinates[0][0],
routeline.coordinates[0][1]), startPushpinOptions);
var endPushpinOptions = { icon: '/images/end.png', anchor: new
Microsoft.Maps.Point(3, 28)};
var endPin= new Microsoft.Maps.Pushpin(new
Microsoft.Maps.Location(routeline.coordinates[routeline.coordinates.length-1][0],
routeline.coordinates[routeline.coordinates.length-
1][1]), endPushpinOptions);
map.entities.push(startPin);
map.entities.push(endPin);
map.entities.push(routeshape); } }
function getDD() {
Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback:
createDrivingDirections });

83
}

function createDrivingDirections()
{
document.getElementById("directionsItinerary").style.display = "block";
document.getElementById("mapdiv").style.width = "75%";
var directionsManager;
directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);
// Set Route Mode to driving
directionsManager.setRequestOptions({ routeMode:
Microsoft.Maps.Directions.RouteMode.driving });
var seattleWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: 'Seattle,
WA' });
directionsManager.addWaypoint(seattleWaypoint);
var tacomaWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: 'Tacoma,
WA',
location: new Microsoft.Maps.Location(47.255134, -
122.441650) });
directionsManager.addWaypoint(tacomaWaypoint);
// Set the element in which the itinerary will be rendered
directionsManager.setRenderOptions({ itineraryContainer:
document.getElementById('directionsItinerary') });
directionsManager.calculateDirections();
}

// clear map entities
function clearMap()
{
resetMapDiv();
}
// close app
function close()
{
window.close();

84
}

function initialize()
{
Microsoft.Maps.loadModule('Microsoft.Maps.Map', { callback: initMap, culture: en-
us, homeRegion: US });
document.getElementById("directions").addEventListener("click", getDD, false);
document.getElementById("setView").addEventListener("click", setView, false);
document.getElementById("panRight").addEventListener("click", function () {
pan(16, 0) }, false);
document.getElementById("pushpin").addEventListener("click", addPushpin, false);
document.getElementById("customPushpin").addEventListener("click",
addCustomPushpin, false);
document.getElementById("polygon").addEventListener("click", addPolygon, false);
document.getElementById("clear").addEventListener("click", clearMap, false);
document.getElementById("close").addEventListener("click", close, false);
document.getElementById("infobox").addEventListener("click", addInfobox, false);
document.getElementById("vm").addEventListener("click", addVM, false);
document.getElementById("cm").addEventListener("click", customModule, false);
document.getElementById("restDirections").addEventListener("click",
getDirections, false);
document.getElementById("tilelayer").addEventListener("click", addtilelayer,
false);
document.getElementById("traffic").addEventListener("click", addtraffic, false);
document.getElementById("bingTheme").addEventListener("click", addBingThemeMap,
false);
document.getElementById("complexShapes").addEventListener("click",
addComplexShapes, false);
document.getElementById("geocode").addEventListener("click", geocode, false);
document.getElementById("revGeocode").addEventListener("click", reverseGeocode,
false);
document.getElementById("search").addEventListener("click", search, false);
}
document.addEventListener("DOMContentLoaded", initialize, false);

85
})();

var map;
function initMap()
{
try
{
var mapOptions =
{
// Add your Bing Maps key here
credentials: 'INSERT_YOUR_BING_MAPS_KEY',
zoom: 8
};
map = new Microsoft.Maps.Map(document.getElementById("mapdiv"), mapOptions);
}
catch (e)
{
var md = new Windows.UI.Popups.MessageDialog(e.message);
md.showAsync();
}
}

// help functions

function resetMapDiv()
{
if (document.getElementById("directionsItinerary").style.display == "block")
{
document.getElementById("directionsItinerary").style.display = "none";
}
}

86
function displayInfo(e)
{
if (e.targetType == "pushpin")
{
showInfobox(e.target);
}
}

function showInfobox(shape)
{
for (var i = map.entities.getLength() - 1; i >= 0; i--)
{
var pushpin = map.entities.get(i); if (pushpin.toString() == '[Infobox]')
{
map.entities.removeAt(i);
};
}
var infoboxOptions = { width: 170,height: 80,
showCloseButton: true,
zIndex: 10,
offset: new Microsoft.Maps.Point(10, 0),
showPointer: true,
title: shape.title,
description: shape.description
};
var defInfobox = new Microsoft.Maps.Infobox(shape.getLocation(), infoboxOptions);
map.entities.push(defInfobox);
}

function createClusteredpin(cluster, latlong)
{
var pin = new Microsoft.Maps.Pushpin(latlong, {
icon: '/images/clusteredpin.png',

87
anchor: new Microsoft.Maps.Point(8,
8)
});
pin.title = 'Cluster pin';
pin.description = 'Number of pins : ' + cluster.length;
Microsoft.Maps.Events.addHandler(pin, 'click', displayInfo);
return pin;
}

function createPin(data)
{
var pin = new Microsoft.Maps.Pushpin(data._LatLong, {
icon:
'/images/nonclusteredpin.png',
anchor: new
Microsoft.Maps.Point(8, 8)
});
pin.title = 'Single pin';
pin.description = 'GridKey: ' + data.GridKey;
return pin;
}
function dataCallback(response)
{
if (response != null)
{
var greenLayer = new ClusteredEntityCollection(map,
{
singlePinCallback: createPin,
clusteredPinCallback:
createClusteredpin
});
greenLayer.SetData(response);
}

88
} (function () {
var app = WinJS.Application;

// This function responds to all application activations.
app.onactivated = function (eventObject) {
if (eventObject.detail.kind ===
Windows.ApplicationModel.Activation.ActivationKind.launch) {

WinJS.UI.processAll();
}
};

app.start();

// set view api to show Birdseye view
function setView()
{
resetMapDiv();
map.setView({ center: new Microsoft.Maps.Location(47.6215, -122.349329),
mapTypeId: Microsoft.Maps.MapTypeId.auto, zoom: 18 });
}
// set view api to pan map
function pan(x, y)
{
resetMapDiv();
var mapCenter = map.getCenter();
var pos = map.tryPixelToLocation(new Microsoft.Maps.Point(map.getWidth() / 2 + x,
map.getHeight() / 2 - (y - 1)),
Microsoft.Maps.PixelReference.control);
mapCenter.latitude += pos.latitude - mapCenter.latitude;
mapCenter.longitude += pos.longitude - mapCenter.longitude;
map.setView({ center: mapCenter });
}
// api to add pin on map

89
function addPushpin()
{
resetMapDiv();
var pushpin = new Microsoft.Maps.Pushpin(map.getCenter(), null);
}

// api to add custom pin on map
function addCustomPushpin() {
resetMapDiv();
var pushpinOptions = {width: null, height: null, htmlContent: "<div style='font-
size:12px;font-weight:bold;border:solid
2px;background-color:Blue;width:100px;'>Custom Pushpin</div>"};
var pushpin = new Microsoft.Maps.Pushpin(map.getCenter(), pushpinOptions);
}

// api to add polygon on map
function addPolygon()
{
resetMapDiv();
addCircle(center.latitude, center.longitude);
}
// add circle on map
function addCircle(latitude, longitude)
{
resetMapDiv();
var radius;
var zoom = map.getZoom();
// calculate radius in KMs based on zoom level so that circle is displayed in
current bounds
switch (Math.floor(zoom / 4)) {
case 0:

90
radius = 500;
break;
case 1:
radius = 100;
break;
case 2:
radius = 50;
break;
case 3:
radius = 5;
break;
default:
radius = 0.1;
break;

}

var R = 6371; // earth's mean radius in km
var lat = (latitude * Math.PI) / 180;
var lon = (longitude * Math.PI) / 180;
var d = parseFloat(radius) / R;
var circle= new Array();
for (var x = 0; x <= 360; x++) {
var r = x * Math.PI / 180; //rad
var cirLat = Math.asin(Math.sin(lat) * Math.cos(d) + Math.cos(lat) *
Math.sin(d) * Math.cos(r));
var cirLong = ((lon + Math.atan2(Math.sin(r) * Math.sin(d) * Math.cos(lat),
Math.cos(d) - Math.sin(lat) * Math.sin(cirLat))) *
180) / Math.PI;
cirLat = (cirLat * 180) / Math.PI;
circle.push(new Microsoft.Maps.Location(cirLat, cirLong));
}
var polygoncolor = new Microsoft.Maps.Color(Math.round(255 * Math.random()),
Math.round(255 * Math.random()), Math.round(255 *

91
Math.random()), Math.round(255 * Math.random()));
var polygon = new Microsoft.Maps.Polygon(circle, { fillColor: polygoncolor,
strokeColor: polygoncolor });
}
// api to add infobox on map
function addInfobox()
{
resetMapDiv();
var pushpin = new Microsoft.Maps.Pushpin(map.getCenter(), { zIndex: 3 });
var infoboxOptions = { zIndex: 4 };
var defaultInfobox = new Microsoft.Maps.Infobox(map.getCenter(), infoboxOptions);
map.entities.push(defaultInfobox);
}
function addtilelayer()
{
resetMapDiv();
var options = { uriConstructor:
'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png', width: 256, height:
256 };

var tileSource = new Microsoft.Maps.TileSource(options);
var tilelayer = new Microsoft.Maps.TileLayer({ mercator: tileSource });

//center map to show tile layer
map.setView({ center: new Microsoft.Maps.Location(48.03, -
122.42), zoom: 11 });
}

92
function addtraffic()
{
resetMapDiv();
}

{
//set center
map.setView({ center: new Microsoft.Maps.Location(40.71, -74.00), zoom: 8 });
// show the traffic Layer
}
function addBingThemeMap()
{
resetMapDiv();
Microsoft.Maps.loadModule('Microsoft.Maps.Themes.BingTheme', {
var id = 'Your Bing Maps Key';
map = new Microsoft.Maps.Map(document.getElementById('mapdiv'),
{
credentials: id,
zoom: 10,
theme: new Microsoft.Maps.Themes.BingTheme()
});
var pin1 = new Microsoft.Maps.Pushpin(map.getCenter(), null);
map.entities.push(new Microsoft.Maps.Infobox(map.getCenter(), { title:
'Seattle', description: 'description here', pushpin:

93
pin1 }));
var pin2 = new Microsoft.Maps.Pushpin(new Microsoft.Maps.Location(47.45,
-122.33), null);
map.entities.push(new Microsoft.Maps.Infobox(new
Microsoft.Maps.Location(47.45, -122.33), { title: 'Tacoma', description:
'description here', pushpin: pin2 }));
}
});
}

function addComplexShapes()
{
resetMapDiv();
Microsoft.Maps.loadModule('Microsoft.Maps.AdvancedShapes', {

var polygon = new Microsoft.Maps.Polygon([

94
map.setView({ zoom: 11, center: new Microsoft.Maps.Location(47.704, -
121.740) });
}
});
}
// api to load custom module
function customModule()
{
resetMapDiv();
Microsoft.Maps.loadModule('clusterModule', { callback: customModuleLoaded });
map.setView({ zoom: 1, center: new Microsoft.Maps.Location(0, 0), mapTypeId:
}

// custom module callback
function customModuleLoaded()
{

testDataGenerator.generateData(100, dataCallback);
}
// api to load venue map module on map
function addVM()
{
resetMapDiv();
Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: vmCallback });
}
// venue map module callback
function vmCallback()
{
var venueMapFactory = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);
venueMapFactory.create({
venueMapId: 'hcl-timessquare',
success: success,

95
error: err
});
}
// error callback for venue map
function err(errorCode, args)
{
var message = 'Error while loading venue map. Errorcode : ' + errorCode;
var md = new Windows.UI.Popups.MessageDialog(message);
md.showAsync();
}

// success callback from venue map callback
function success(venueMap, args)
{
venueMap.show();
map.setView(venueMap.bestMapView);
}

var searchManager = null;
var currInfobox = null;
// callback function to create searchManager once search module is loaded
function createSearchManager()
{
if (!searchManager)
{
map.addComponent('searchManager', new
Microsoft.Maps.Search.SearchManager(map));
searchManager = map.getComponent('searchManager');
}
}

// business search api request
function search()
{

96
resetMapDiv();
if (searchManager)
{
searchRequest();
}
else
{
Microsoft.Maps.loadModule('Microsoft.Maps.Search', { callback: searchRequest
});
}
}

// business search api
function searchRequest()
{
var what = 'pizza';
var where = 'boston, ma';
var query = '';
var request =
{
what: what,
where: where,
query: query,
count: 10,
startIndex: 0,
callback: search_onSearchSuccess,
errorCallback: search_onSearchFailure,
userData: userData
};
searchManager.search(request);
}

97

// business search api success callback
function search_onSearchSuccess(result, userData)
{
var searchResults = result && result.searchResults;
if (searchResults)
{
for (var i = 0; i < searchResults.length; i++)
{
search_createMapPin(searchResults[i]);
}

if (result.searchRegion && result.searchRegion.mapBounds)
{
map.setView({ bounds: result.searchRegion.mapBounds.locationRect });
}
}
}
// business search api failure callback
function search_onSearchFailure(result, userData)
{
var md = new Windows.UI.Popups.MessageDialog("Search failed");
md.showAsync();
}

// business search api display search results
function search_createMapPin(result)
{
if (result)
{
var pin = new Microsoft.Maps.Pushpin(result.location, null);
Microsoft.Maps.Events.addHandler(pin, 'click', function () {
search_showInfoBox(result) });

98
}
}

// business search api infobox
function search_showInfoBox(result)
{
if (currInfobox)
{
map.entities.remove(currInfobox);
}
currInfobox = new Microsoft.Maps.Infobox(
result.location,
{
title: result.name,
description: [result.address, result.city, result.state, result.country,
result.phone].join(" "),
showPointer: true,
titleAction: null,
titleClickHandler: null
});

map.entities.push(currInfobox);
}

// reverse geocode api request
function reverseGeocode()
{
resetMapDiv();
if (searchManager)
{
reverseGeocodeRequest();

99
}

else
{
reverseGeocodeRequest });
}
}

// reverse geocode api
function reverseGeocodeRequest()
{
var request =
{
location: map.getCenter(),
callback: onReverseGeocodeSuccess,
errorCallback: onReverseGeocodeFailed,
userData: userData
};
searchManager.reverseGeocode(request);
}

// reverse geocode api request success callback
function onReverseGeocodeSuccess(result, userData)
{
if (result)
{
var pushpin = new Microsoft.Maps.Pushpin(result.location, null);
map.setView({ center: result.location, zoom: 10 });
}

100
}

// reverse geocode api request failure callback
function onReverseGeocodeFailed(result, userData)
{
var md = new Windows.UI.Popups.MessageDialog("Reverse Geocode failed");
md.showAsync();
}

function geocode()
{
resetMapDiv();
if (searchManager)
{
geocodeRequest();
}
else
{
Microsoft.Maps.loadModule('Microsoft.Maps.Search', { callback: geocodeRequest
});
}
}

function geocodeRequest()
{
var where = 'Denver, CO';
var request =
{
where: where,
count: 2,

101
callback: onGeocodeSuccess,
errorCallback: onGeocodeFailed,
userData: userData
};
searchManager.geocode(request);
}

// geocode api request success callback
function onGeocodeSuccess(result, userData)
{
if (result)
{
var MM = Microsoft.Maps;
var topResult = result.results && result.results[0];
if (topResult)
{
var pushpin = new MM.Pushpin(topResult.location, null);
map.setView({ center: topResult.location, zoom: 10 });
}
}
}

// geocode api request failure callback
function onGeocodeFailed(result, userData)
{
var md = new Windows.UI.Popups.MessageDialog("Geocode failed");
md.showAsync();
}

function getDirections()

102
{
{
var start= 'Boston, MA'; var end= 'New York, NY';
var routeRequest = 'http://dev.virtualearth.net/REST/v1/Routes?wp.0=' + start
+ '&wp.1=' + end +
'&routePathOutput=Points&output=json&key=' + credentials;
});
}
// route callback
function routeCallback(result) { result =
JSON.parse(result.responseText);
if (result && result.resourceSets && result.resourceSets.length > 0 &&
result.resourceSets[0].resources && result.resourceSets
[0].resources.length > 0 && result.resourceSets[0].resources[0].routeLegs.length > 0)
{ // instruction list can be
displayed using below code var resultsListItem = null; var
resultsList = document.createElement("ol");
for (var i = 0; i <
result.resourceSets[0].resources[0].routeLegs[0].itineraryItems.length; ++i)
{
resultsListItem = document.createElement("li");
resultsList.appendChild(resultsListItem); var resultStr
= result.resourceSets[0].resources[0].routeLegs[0].itineraryItems[i].instruction.text;
resultsListItem.innerHTML =
resultStr; } var bbox =
result.resourceSets[0].resources[0].bbox; var viewBoundaries =
Microsoft.Maps.LocationRect.fromLocations(new Microsoft.Maps.Location(bbox[0], bbox[1]),
new Microsoft.Maps.Location(bbox[2], bbox[3]));
map.setView({ bounds: viewBoundaries}); var routeline =
result.resourceSets[0].resources[0].routePath.line;
var routepoints = new Array(); for (var i = 0; i <
routeline.coordinates.length; i++) {
routepoints[i]=new Microsoft.Maps.Location(routeline.coordinates[i][0],
routeline.coordinates[i][1]); } var

103
routeshape = new Microsoft.Maps.Polyline(routepoints, {strokeColor:new
Microsoft.Maps.Color(200,0,0,200)}); var
startPushpinOptions = { icon: '/images/start.png', anchor: new Microsoft.Maps.Point(3,
28) }; var startPin= new
Microsoft.Maps.Pushpin(new Microsoft.Maps.Location(routeline.coordinates[0][0],
routeline.coordinates[0][1]), startPushpinOptions);
var endPushpinOptions = { icon: '/images/end.png', anchor: new
Microsoft.Maps.Point(3, 28)}; var endPin= new
Microsoft.Maps.Pushpin(new
Microsoft.Maps.Location(routeline.coordinates[routeline.coordinates.length-1][0],
routeline.coordinates
[routeline.coordinates.length-1][1]), endPushpinOptions);
map.entities.push(startPin); map.entities.push
(endPin); map.entities.push(routeshape); } }
function getDD() {
createDrivingDirections });
}

function createDrivingDirections()
{
document.getElementById("directionsItinerary").style.display = "block";
var directionsManager;
// Set Route Mode to driving
Microsoft.Maps.Directions.RouteMode.driving });
var seattleWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: 'Seattle,
WA' });
directionsManager.addWaypoint(seattleWaypoint);
var tacomaWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: 'Tacoma,
WA', location: new Microsoft.Maps.Location
(47.255134, -122.441650) });
directionsManager.addWaypoint(tacomaWaypoint);

104
// Set the element in which the itinerary will be rendered
document.getElementById('directionsItinerary') });
// alert('Calculating directions...');
}

// clear map entities
function clearMap()
{
resetMapDiv();
}
// close app
function close()
{
window.close();
}

function initialize()
{
Microsoft.Maps.loadModule('Microsoft.Maps.Map', { callback: initMap, culture: en-
us, homeRegion: US });
document.getElementById("directions").addEventListener("click", getDD, false);
document.getElementById("setView").addEventListener("click", setView, false);
document.getElementById("panRight").addEventListener("click", function () {
pan(16, 0) }, false);
document.getElementById("pushpin").addEventListener("click", addPushpin, false);
document.getElementById("customPushpin").addEventListener("click",
addCustomPushpin, false);
document.getElementById("polygon").addEventListener("click", addPolygon, false);
document.getElementById("clear").addEventListener("click", clearMap, false);
document.getElementById("close").addEventListener("click", close, false);
document.getElementById("infobox").addEventListener("click", addInfobox, false);

105
document.getElementById("vm").addEventListener("click", addVM, false);
document.getElementById("cm").addEventListener("click", customModule, false);
document.getElementById("restDirections").addEventListener("click",
getDirections, false);
document.getElementById("tilelayer").addEventListener("click", addtilelayer,
false);
document.getElementById("traffic").addEventListener("click", addtraffic, false);
document.getElementById("bingTheme").addEventListener("click", addBingThemeMap,
false);
document.getElementById("complexShapes").addEventListener("click",
addComplexShapes, false);
document.getElementById("geocode").addEventListener("click", geocode, false);
document.getElementById("revGeocode").addEventListener("click", reverseGeocode,
false);
document.getElementById("search").addEventListener("click", search, false);
}
document.addEventListener("DOMContentLoaded", initialize, false);

})();

var map;
function initMap()
{
try
{
var mapOptions =
{
// Add your Bing Maps key here
credentials: 'INSERT_YOUR_BING_MAPS_KEY',
zoom: 8
};
map = new Microsoft.Maps.Map(document.getElementById("mapdiv"), mapOptions);
}

106
catch (e)
{
var md = new Windows.UI.Popups.MessageDialog(e.message);
md.showAsync();
}
}

// help functions

function resetMapDiv()
{
if (document.getElementById("directionsItinerary").style.display == "block")
{
document.getElementById("directionsItinerary").style.display = "none";
}
}
function displayInfo(e)
{
if (e.targetType == "pushpin")
{
showInfobox(e.target);
}
}function showInfobox(shape)
{
for (var i = map.entities.getLength() - 1; i >= 0; i--)
{
var pushpin = map.entities.get(i); if (pushpin.toString() == '[Infobox]')
{
map.entities.removeAt(i);
};
}
var infoboxOptions = { width: 170, height: 80,
showCloseButton: true,

107
zIndex: 10, offset: new
Microsoft.Maps.Point(10, 0), showPointer:
true, title: shape.title,
description: shape.description };
var defInfobox = new Microsoft.Maps.Infobox(shape.getLocation(), infoboxOptions);
}

function createClusteredpin(cluster, latlong)
{
var pin = new Microsoft.Maps.Pushpin(latlong, {
icon: '/images/clusteredpin.png',
anchor: new Microsoft.Maps.Point(8,
8)
});
pin.title = 'Cluster pin';
pin.description = 'Number of pins : ' + cluster.length;
return pin;
}

function createPin(data)
{
var pin = new Microsoft.Maps.Pushpin(data._LatLong, {
icon:
'/images/nonclusteredpin.png',
anchor: new
Microsoft.Maps.Point(8, 8)
});
pin.title = 'Single pin';
pin.description = 'GridKey: ' + data.GridKey;
return pin;
}
function dataCallback(response)

108
{
if (response != null)
{
var greenLayer = new ClusteredEntityCollection(map,
{
singlePinCallback: createPin,
clusteredPinCallback:
createClusteredpin
});
//This method is part of dynamically downloaded clustering Module
V7ClientSideClustering.js.
greenLayer.SetData(response);
}
}
var testDataGenerator = new function ()
{
/*
* Example data model that may be returned from a custom web service.
*/
var

ExampleDataModel = function (name, latitude, longitude)
{
this.Name = name;
this.Latitude = latitude;

this.Longitude = longitude;
}; /*
* This function generates a bunch of random random data with
* coordinate information and

returns it to a callback function
* similar to what happens when calling a web service.

109
*/
this.generateData = function

(numPoints, callback)
{
var data = [], randomLatitude, randomLongitude;
for (var i = 0; i < numPoints; i++)
{

randomLatitude = Math.random() * 181 - 90;
randomLongitude = Math.random() * 361 - 180;
data.push(new

ExampleDataModel("Point: " + i, randomLatitude, randomLongitude));
}
if (callback)
{
callback(data);

}
};
};

See Also
Bing Maps SDK for Windows Store apps
Getting Started with Windows Store apps

110
Microsoft.Maps API Reference
This section contains reference documentation for the Microsoft.Maps API, which contains the
core types of the Bing Maps AJAX Control 7.0.
In This Section
Data Structures
AltitudeReference Enumeration
Location Class
LocationRect Class
Point Class
Mapping
Events Object
KeyEventArgs Object
LabelOverlay Enumeration
Map Class
MapMode Class
MapOptions Object
MapTypeId Enumeration
MouseEventArgs Object
PixelReference Enumeration
ViewOptions Object
Entities
Color Class
EntityCollection Class
EntityCollectionOptions Object
Events Object
Infobox Class
InfoboxOptions Object
InfoboxType Enumeration
Polyline Class
PolylineOptions Object
Polygon Class

111
PolygonOptions Object
Pushpin Class
PushpinOptions Object
TileLayer Class
TileLayerOptions Object
TileSource Class
TileSourceOptions Object
User Location
Coordinates Class
GeoLocationProvider Class
Position Class
PositionCircleOptions Object
PositionError Class
PositionOptions Object
Dynamic Module Loading
AltitudeReference Enumeration
Defines the reference point from which the altitude is measured.
Constants

Name Description
ground The altitude is measured from the ground level.
ellipsoid The altitude is measured from the WGS 84
ellipsoid of the Earth.

Methods

Name Definition Return Value Description
isValid isValid(reference:AltitudeReference) boolean Determines if the
specified reference is a

112
supported
AltitudeReference.

Example
<html>
<head>
<title></title>


function GetMap()
{
// Create two locations with different altitude references.
var groundLoc = new Microsoft.Maps.Location(47, -122, 100,
Microsoft.Maps.AltitudeReference.ground);
var ellipsoidLoc = new Microsoft.Maps.Location(47, -122, 100,
Microsoft.Maps.AltitudeReference.ellipsoid);

// Set the map view
var mapOptions = {credentials: "Bing Maps Key",
center: groundLoc,
zoom:16};


113
// Add two pushpins to demonstrate the difference when using different altitude
references
map.entities.push(new Microsoft.Maps.Pushpin(groundLoc, {text: "G"}));
map.entities.push(new Microsoft.Maps.Pushpin(ellipsoidLoc, {text: "E"}));

}
</script>
</head>
</body>
</html>
AnimationVisibility Enumeration
Defines a tile layers visibility during animation.
Constants

Name Description
auto The map control determines whether or not to
show a tile layer based on system capability. If
a browser can render a tile layer with
acceptable performance, it is displayed during
animations.
hide The tile layer is not displayed during animation.
show The tile layer is displayed during animations.
This option may impact performance on older
browsers.

Color Class
Represents a color.

114
Constructor

Name Definition Description
Color Color(a:number, r:number,
g:number, b:number)
Initializes a new instance of
the Color class. The a
parameter represents opacity.
The range of valid values for
all parameters is 0 to 255.

Properties

Name Type Description
a number The opacity of the color. The
range of valid values is 0 to 255.
r number The red value of the color. The
g number The green value of the color.
The range of valid values is 0 to
255.
b number The blue value of the color. The

Static Methods

clone clone(color:Color) Color Creates a copy of the
Color object.
fromHex fromHex(hex:string) Color Converts the specified
hex string to a Color.

Methods

115
clone clone() Color Returns a copy of the
Color object.
getOpacity getOpacity() number Returns the opacity of
the Color as a value
between 0 (a=0) and 1
(a=255).
toHex toHex() string Converts the Color into
a 6-digit hex string.
Opacity is ignored. For
example, a Color with
values (255,0,0,0) is
returned as hex string
#000000.
toString toString() string Converts the Color
object to a string.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

116
map = new


// Create a shape
var lineVertices = new Array(location1, location2, location3, location4,
location5);
var line = new Microsoft.Maps.Polyline(lineVertices,{strokeColor:new
Microsoft.Maps.Color(100, 100, 0, 100)});

map.entities.push(line);

}

function SetPolygonColor()
{
// Get the polyline entity.
var mapLine = map.entities.get(0);

// Set the option values
var opacity = document.getElementById('txtA').value;
var rValue = document.getElementById('txtR').value;
var gValue = document.getElementById('txtG').value;
var bValue = document.getElementById('txtB').value;
var lineWidth = document.getElementById('txtWidth').value;

117

// Verify input values and set the opacity, color,
// and width of the line.
if (((opacity < 0) || (opacity > 255)) ||
((rValue < 0) || (rValue > 255)) ||
((gValue < 0) || (gValue > 255)) ||
((bValue < 0) || (bValue > 255)) )
{
alert("Opacity and all color values must be between 0 and 255.");
}
else
{
mapLine.setOptions({strokeColor:new Microsoft.Maps.Color(opacity, rValue,
gValue, bValue), strokeThickness:lineWidth});
}

}

</script>
</head>
Line Opacity: <input id="txtA" type="text" value="100"/><br/>
Red Color Value: <input id="txtR" type="text" value="100"/><br/>
Green Color Value: <input id="txtG" type="text" value="100"/><br/>
Blue Color Value: <input id="txtB" type="text" value="100"/><br/>
Line Width: <input id="txtWidth" type="text" value="5"/><br/>
<input id="btnChangeColor" type="button" value="Set Polygon Color"
onclick="SetPolygonColor();"/>
</body>
</html>

118
Coordinates Class
Represents the coordinates of the position of the user.
Properties

accuracy number The accuracy, in meters, of
the latitude and longitude
values.
altitude number The altitude of the location.
altitudeAccuracy number The accuracy, in meters, of
the altitude value.
heading number The direction of travel of the
hosting device.
latitude number The latitude of the location.
longitude number The longitude of the location.
speed number The ground speed of the
hosting device, in meters per
second.

See Also
Contains a collection of entities. An Entity can be any one of the following types: Infobox,
Polygon, Polyline, Pushpin, TileLayer, or EntityCollection.
Constructor

EntityCollection EntityCollection(options?:EntityCollectionOptions) Initializes a new
instance of the

119
EntityCollection
class.

Methods

Name Definition Return
Value
Description
clear clear() None Removes all
entities from the
collection.
get get(index:number) Entity* Returns the entity
at the specified
index in the
collection.
getLength getLength() number Returns the
number of entities
in the collection.
getVisible getVisible() boolean Returns whether
the entity
collection is visible
on the map.
getZIndex getZIndex() number Gets the z-index
of the entity
collection with
respect to other
items on the map.
indexOf indexOf(entity:Entity*) number Returns the index
of the specified
entity in the
collection. If the
entity is not found
in the collection, -1
is returned.
insert insert(entity:Entity*, index:number) None Inserts the
specified entity
into the collection

120
Value
Description
at the given index.
pop pop() Entity* Removes the last
entity from the
collection and
returns it.
push push(entity:Entity*) None Adds the specified
entity to the last
position in the
collection.
remove remove(entity:Entity*) Entity* Removes the
specified entity
from the collection
and returns it.
removeAt removeAt(index:number) Entity* Removes the
entity at the
specified index
from the collection
and returns it.
setOptions setOptions(options:EntityCollectionOptions) None Sets the options
for the entity
collection.
toString toString() string Converts the
EntityCollection
object to a string.

* An Entity can be any one of the following types: Infobox, Polygon, Polyline, Pushpin, TileLayer,
or EntityCollection.
Events

Name Arguments Description
entityadded object: {collection:
EntityCollection, entity:Entity*}
Occurs when one of the
following happens:
An entity is added to the
collection.
One of the entities of the

121
collection (such as another
entity collection) fires the
entityadded event.
For example, if collection #1
contains an entity, which is
another collection #2, then
when an entity is added to
collection #2, two entityadded
events are fired.
entitychanged object: {collection:
following happens:
The collection changes.
An entity of the
collection changes.
entitychanged event.
when an entity of collection #2
changes, two entitychanged
events are fired.
entityremoved object: {collection:
following happens:
An entity of the
collection is removed.
entityremoved event.
is removed, two
entityremoved events are
fired.

122
Example
<html>
<head>
<title></title>



var map = null;
var pinTotal = 0;

function GetMap()
{
map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),

// Add handler for the map click event - add a pin to the click location.

}



123

// Return the location where the map was clicked and create the pin.

// Attach a handler to the pin so that it is removed when it is clicked
Microsoft.Maps.Events.addHandler(pin, 'click', removePin);

// Add the pushpin

}
}

function removePin(e)
{
var indexOfPinToRemove = map.entities.indexOf(e.target);

map.entities.removeAt(indexOfPinToRemove);

}

</script>
</head>
<b>Click the map to add a pin, or click a pin to remove it.<b/>
</body>
</html>

124
EntityCollectionOptions Object
Contains options for an entity collection.
Properties

bubble boolean A boolean indicating whether to set the
options of all entities when an option of an
entity within the collection is set. The default
value is true. For example, in an entity
collection composed of multiple polygons, if
this property is set to true setting one
polygons fill color to red changes the fill
color of all of the other polygons in the entity
collection to red.

This property is only available when
the
Microsoft.Maps.AdvancedShapes
module is loaded.
visible boolean A boolean indicating whether the entity
collection is visible on the map.
zIndex number The z-index of the entity collection with
respect to other items on the map.

Example
<html>
<head>
<title></title>


125

var map = null;

function GetMap()
{
map = new
Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});

// Add handler for the map click event - add a pin to the click location.

}


// Return the location where the map was clicked and create the pin.

// Add the pushpin

}
}

function hideAllPins(){
// Hide all the entities on the map
map.entities.setOptions({visible:false});

126
}

function showAllPins(){
// Show all the entities on the map
map.entities.setOptions({visible:true});
}

</script>
</head>
<input type="button" value="Hide all pins" onclick="hideAllPins();"/>
<input type="button" value="Show all pins" onclick="showAllPins();"/>
</body>
</html>
EntityState Enumeration
Defines the highlighted or selected state of an entity, such as a pushpin. To get the latest Bing
Maps entity state design, load the Microsoft.Maps.Themes.BingTheme module before creating
your entity.
Constants

Name Description
highlighted The entity is highlighted on the map.
none The entity is not highlighted or selected.
selected The entity is selected on the map.

127
Remarks
Two entity state values can be combined by using AND (&) or OR (|). For example, if a pin is
selected and you want it to remain selected after a hover action, but un-highlighted if it is
highlighted, then you can use myPin.setOptions({state:pin1.getState() &
~Microsoft.Maps.EntityState.highlighted});.
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

Microsoft.Maps.loadModule('Microsoft.Maps.Themes.BingTheme', { callback:
themesModuleLoaded });

}

function themesModuleLoaded()
{
map = new Microsoft.Maps.Map(document.getElementById('mapDiv'), { credentials:
'Bing Maps Key', theme: new Microsoft.Maps.Themes.BingTheme() });

128

var pin1 = new Microsoft.Maps.Pushpin(new Microsoft.Maps.Location(34.05, -
118.24), null);

map.entities.push(new Microsoft.Maps.Infobox(new Microsoft.Maps.Location(34.05,
-118.24), {title: 'Los Angeles', description: 'Description here', pushpin: pin1}));

pin1.setOptions({state:Microsoft.Maps.EntityState.selected});

}

</script>
</head>
</body>
</html>
See Also
Events Object
Provides event handling functionality for map and entity events.
The Events object does not need to be initialized. Call the Events methods directly.
Methods

Value
Description
addHandler addHandler(target:object, object Attaches the handler for the event

129
Value
Description
eventName:string,
handler:function)
that is thrown by the target. Use
the return object to remove the
handler using the removeHandler
method.
Microsoft.Maps.Events.addHandle
r(map, 'viewchangeend,
function(e){ //Handle the
event });
addThrottledHan
dler
addThrottledHandler(target:o
bject, eventName:string,
handler:function,
throttleInterval:number)
object Attaches the handler for the event
that is thrown by the target, where
the minimum interval between
events (in milliseconds) is
specified in the throttleInterval
parameter. The last occurrence of
the event is called after the
specified throttleInterval.
hasHandler hasHandler(target:object,
eventName:string)
boolea
n
Checks if the target has any
attached event handler.
invoke invoke(target:object,
eventName:string, args:object)
None Invokes an event on the target.
This causes all handlers for the
specified eventName to be called.
removeHandler removeHandler(handlerId:
object)
None Detaches the specified handler
from the event. The handlerId is
returned by the addHandler and
addThrottledHandler methods.

Example
<html>
<head>
<title></title>

130


var map = null;
var infobox = null;

function GetMap()
{


// Create a pin at the center of the map and its corresponding infobox
var pin = new Microsoft.Maps.Pushpin(center);
infobox = new Microsoft.Maps.Infobox(center, {title: 'Pushpin infobox',
visible:false, offset:new Microsoft.Maps.Point(0,35)});

// Add event handlers for hovering over the pushpin
Microsoft.Maps.Events.addHandler(pin, 'mouseover', showInfobox);
Microsoft.Maps.Events.addHandler(pin, 'mouseout', hideInfobox);

// Add the pushpin and hidden infobox to the map
map.entities.push(infobox);

}

function showInfobox()
{

131
infobox.setOptions({visible:true});

}

function hideInfobox()
{
infobox.setOptions({visible:false});

}

</script>
</head>
</body>
</html>
Contains methods for obtaining and displaying the users current location.
This functionality is only available on browsers that support the W3C GeoLocation API.
Constructor

GeoLocationProvider GeoLocationProvider(map:Map) Initializes a new instance of
the GeoLocationProvider
class.

Methods

132
Name Definition Retur
n
Value
Description
addAccuracyCircle addAccuracyCircle(center:Location,
radiusInMeters:number,
segments:number,
options:PositionCircleOptions)
None Renders a geo
location accuracy
circle on the map.
The accuracy
circle is created
with the center at
the specified
location, using the
given
radiusInMeters,
and with the
specified number
of segments for
the accuracy
circle polygon.
Additional options
are also available
to adjust the style
of the polygon.
cancelCurrentReque
st
cancelCurrentRequest() None Cancels the
processing of the
current
getCurrentPositio
n request. This
method prevents
the response from
being processed.
getCurrentPosition getCurrentPosition(options:PositionOptio
ns)
None Obtains the users
current location
and displays it on
the map.

The
accuracy
of the
user
location
obtained

133
n
Value
Description
using this
method
varies
widely
dependin
g on the
desktop
browser
or mobile
device of
the
requestin
g client.
Desktop
users
may
experienc
e low
user
location
accuracy
(an
accuracy
circle with
a large
radius),
while
mobile
user
location
accuracy
may be
much
greater (a
few
meters).
removeAccuracyCircl
e
removeAccuracyCircle() None Removes the
current geo
location accuracy

134
n
Value
Description
circle.

Example
<html>
<head>
<title></title>



function GetMap()
{

// Set the map options
var mapOptions = {credentials:"Bing Maps Key"};

mapOptions);

// Initialize the location provider
var geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);

// Get the user's current location
geoLocationProvider.getCurrentPosition();

135
}

</script>
</head>
</body>
</html>
See Also
Infobox Class
Represents an info box on the map. You can use this class to create pop-up balloons for
pushpins.
Constructor

Infobox Infobox(location:Location,
options?:InfoboxOptions)
the Infobox class.

Methods

Value
Description
getActions getActions() Object Returns a list of actions, where
each item is a name-value pair
indicating an action link name
and the event name for the
action that corresponds to that
action link.
getAnchor getAnchor() Point Returns the point on the infobox
which is anchored to the map.

136
Value
Description
An anchor of (0,0) is the top left
corner of the infobox.
getDescription getDescription() string Returns the string that is printed
inside the infobox.
getHeight getHeight() number Returns the height of the info
box.
getHtmlContent getHtmlContent() string Returns the info box as HTML.
getId getId() string Returns the ID of the info box.
getLocation getLocation() Location Returns the location on the map
where the infoboxs anchor is
attached.
getOffset getOffset() Point Returns the amount the infobox
pointer is shifted from the
location of the infobox, or if
showPointer is false, then it is
the amount the infobox bottom
left edge is shifted from the
location of the infobox. The
default value is (0,0), which
means there is no offset.
getOptions getOptions() InfoboxOpti
ons
Returns the info box options.
getShowCloseB
utton
getShowCloseButton() boolean Returns a boolean indicating
whether the infobox close button
is shown.
getShowPointer getShowPointer() boolean Returns a boolean indicating
whether the infobox is drawn
with a pointer.
getTitle getTitle() string Returns a string that is the title of
the info box.
getTitleAction getTitleAction() Object Returns an object containing a
name-value pair indicating the
link text to the right of an info
box title and the event name for
the action that corresponds to

137
Value
Description
that link.
getTitleClickHan
dler
getTitleClickHandler() function Returns the name of the function
to call when the title of the info
box is clicked.
getVisible getVisible() boolean Returns whether the infobox is
visible. A value of false indicates
that the infobox is hidden,
although it is still an entity on the
map.
getWidth getWidth() number Returns the width of the infobox.
getZIndex getZIndex() number Returns the z-index of the
infobox with respect to other
items on the map.
setHtmlContent setHtmlContent(content:stri
ng)
None Sets the HTML content of the
infobox. You can use this
method to change the look of the
infobox. Note that info box
options are ignored if custom
HTML is set. Also, when custom
HTML is used to represent the
info box, the info box is
anchored at the top-left corner.
var infoboxOptions = {width
:200, height :100,
showCloseButton: true, zIndex:
0, offset:new
Microsoft.Maps.Point(10,0),
showPointer: true};
var defInfobox = new
Microsoft.Maps.Infobox(map.get
Center(), infoboxOptions );
defInfobox.setHtmlContent('<di
v id="infoboxText"
style="background-color:White;
border-style:solid;border-
width:medium; border-
color:DarkOrange; min-

138
Value
Description
height:100px;
position:absolute;top:0px;
left:23px; width:240px;"><b
id="infoboxTitle"
style="position:absolute;
top:10px; left:10px;
width:220px;">myTitle</b><a
id="infoboxDescription"
style="position:absolute;
top:30px; left:10px;
width:220px;">lkjsl lkjdkl
lkajdlkj
klasdjfkl</a></div>');
setLocation setLocation(location:Locati
on)
None Sets the location on the map
where the anchor of the infobox
is attached.
setOptions setOptions(options:Infobox
Options)
None Sets options for the infobox.
toString toString() string Converts the Infobox object to a
string.

Events

click eventArgs:MouseEventArgs Occurs when the mouse is
used to click the infobox.
entitychanged object: {entity:Entity} Occurs when the location
of the infobox or any of the
infobox options change.
mouseenter eventArgs:MouseEventArgs Occurs when the mouse
cursor enters the area
covered by the infobox.
mouseleave eventArgs:MouseEventArgs Occurs when the mouse
cursor leaves the area
covered by the infobox.

139

Remarks
The Bing Maps AJAX Control default info box is designed for desktop browsers and may not
function properly on all mobile browsers.
For the best performance, it is recommended that you have only one info box on the map at a
time.
Example
<html>
<head>
<title></title>



var map = null;
var pinInfobox = null;

function GetMap()
{



140

// Create the info box for the pushpin
pinInfobox = new Microsoft.Maps.Infobox(new Microsoft.Maps.Location(0,0),
{title: 'My Pushpin', visible: true});

// Add a handler for the pushpin click event.
Microsoft.Maps.Events.addHandler(pin, 'click', displayInfobox);

// Hide the info box when the map is moved.
Microsoft.Maps.Events.addHandler(map, 'viewchange', hideInfobox);

// Add the pushpin and info box to the map
map.entities.push(pinInfobox);

}

function displayInfobox(e)
{
pinInfobox.setOptions({ visible:true });
}

function hideInfobox(e)
{
pinInfobox.setOptions({ visible: false });
}

</script>

141
</head>
</html>
InfoboxOptions Object
Represents the options for an info box.
Properties

actions Object A list of the info box actions, where
each item is a label (the link text) or
icon (the URL of the image to use as
the icon link) and eventHandler (name
of the function handling a click of the
action link).
var infoboxOptions = {title:'My
Infobox', description:'Testing
actions', actions:[{label: 'test1',
eventHandler: testEvent1}, {label:
'test2', eventHandler:
testEvent2},{label: 'test3',
eventHandler: testEvent3}] };
description string The string displayed inside the info box.
height number The height of the info box. The default
value is 126.
htmlContent string The HTML that represents the info box.
Note that info box options are ignored if
custom HTML is set. Also, if custom
HTML is used to represent the info box,
the info box is anchored at the top-left
corner.
var infoboxOptions = {width :200,
height :100, showCloseButton: true,
zIndex: 0, offset:new
Microsoft.Maps.Point(10,0),

142
showPointer: true,
htmlContent:'<b>Custom HTML</b>'};
id string The ID associated with the info box.
location Location The location on the map where the info
boxs anchor is attached.
offset Point The amount the info box pointer is
shifted from the location of the info box,
or if showPointer is false, then it is the
amount the info box bottom left edge is
shifted from the location of the info box.
If custom HTML is set, it is the amount
the top-left corner of the info box is
shifted from its location. The default
offset value is (0,0), which means there
is no offset.
showCloseButton boolean A boolean indicating whether to show
the close dialog button on the info box.
The default value is true. By default the
close button is displayed as an X in the
top right corner of the info box.
This property is ignored if custom HTML
is used to represent the info box.
showPointer boolean A boolean indicating whether to display
the info box with a pointer. The default
value is true. In this case the info box is
anchored at the bottom point of the
pointer. If this property is set to false,
the info box is anchored at the bottom
left corner.
This property is ignored if custom HTML
is used to represent the info box.
pushpin Pushpin The pushpin associated with this info
box. If the
Microsoft.Maps.Themes.BingTheme
module is loaded, then the info box
appears when the hover or click events
of the pushpin occur.
title string The title of the info box.

143
titleAction Object An action to take when the link to the
right of an info box title is clicked. The
specified object contains a label (the
link text) and an eventHandler (the
name of the function handling a click of
the link).
titleClickHandler function The name of the function to call when
the title of the info box is clicked. If this
property is set, the title of the info box is
displayed as a link.
typeName InfoboxType The style of the info box. The default
value is standard.
To get the latest Bing Maps design,
load the
module before creating your info box. In
addition, when the BingTheme module
is loaded, typeName can be set to mini
to use the mini info box type.
visible boolean A boolean indicating whether to show or
hide the info box. The default value is
true. A value of false indicates that the
info box is hidden, although it is still an
entity on the map.
width number The width of the info box. The default
value is 256.
zIndex number The z-index of the info box with respect
to other items on the map.

Example
<html>
<head>
<title></title>

144



var map = null;

function GetMap()
{


// Create an info box
var infoboxOptions = {width:300,
height: 100,
title: "Information Box Title",
description: "This is the map.",
showPointer: false,
titleClickHandler: InfoboxHandler,
offset: new Microsoft.Maps.Point(-100,0)};
var myInfobox = new Microsoft.Maps.Infobox(center, infoboxOptions);

// Add the info box to the map
map.entities.push(myInfobox);

145
}

function InfoboxHandler()
{
alert("Infobox title was clicked!");
}

</script>
</head>
</html>
See Also
Infobox Class
InfoboxType Enumeration
Contains info box styles. To get the latest Bing Maps design, load the
Microsoft.Maps.Themes.BingTheme module before creating your info box.
Constants

Name Description
mini A smaller info box with space for a title.
standard The default info box style. This standard info
box makes space for a title, title link,
description, and other links if they are specified.

Example

146
<html>
<head>
<title></title>



var map = null;

function GetMap()
{


}

{

var mapCenter = new Microsoft.Maps.Location(47.5, -122.3);

"Bing Maps Key", center: mapCenter, zoom: 9, theme: new Microsoft.Maps.Themes.BingTheme()
});

// Create an info box
var infoboxOptions = {width:300,
height: 100,

147
title: "Mini Info Box",
typeName: Microsoft.Maps.InfoboxType.mini,
showPointer: true,
offset: new Microsoft.Maps.Point(-100,0)};

var myInfobox = new Microsoft.Maps.Infobox(center, infoboxOptions);

// Add the info box to the map
map.entities.push(myInfobox);

}

</script>
</head>
</body>
</html>
KeyEventArgs Object
Contains the arguments for keyboard events.
Properties

altKey boolean A boolean indicating if the ALT
key was pressed.
ctrlKey boolean A boolean indicating if the
CTRL key was pressed.
eventName string The event that occurred.

148
handled boolean A boolean indicating whether
the event is handled. If this
property is set to true, the
default map control behavior
for the event is cancelled.
keyCode string The ASCII character code that
identifies the keyboard key that
was pressed.
originalEvent object The original browser event.
shiftKey boolean A boolean indicating if the
SHIFT key was pressed.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

149
Microsoft.Maps.Events.addHandler(map, 'keypress', addPin);

}


if (e.keyCode == "112") {

// If the 'p' key is pressed, add a pushpin to the center of the
// current map view.
var pin = new Microsoft.Maps.Pushpin(center);

}
}

</script>
</head>
<b>Click the 'p' key to add a pushpin to the map.</b>
</body>
</html>
LabelOverlay Enumeration
Defines how map labels are displayed.
Constants

150
Name Description
hidden Map labels are not shown on top of imagery.
visible Map labels are shown on top of imagery.

Methods

isValid isValid(labelOverlay:LabelOverlay) boolean Determines whether
the specified
labelOverlay is a
supported
LabelOverlay.

Example
<html>
<head>
<title></title>



function GetMap()
{
// Initialize the map options. In this case,
// turn the label overlay on a bird's eye map off.
var mapOptions =
{
credentials:"Your Bing Maps Key",

151
center: new Microsoft.Maps.Location(37.794973,-122.393542),
zoom: 17,
labelOverlay: Microsoft.Maps.LabelOverlay.hidden
}

//Load the map
mapOptions );

}

</script>
</head>
</body>
</html>
Location Class
Contains the altitude and coordinate values of a location on the map.
Constructor

Location Location(latitude:number,
longitude:number, altitude?:number,
altitudeReference?:AltitudeReference)
the Location class. The
altitude and
altitudeReference
parameters default to
undefined.

Properties

152
altitude number The altitude of the location.
altitudeReference AltitudeReference The reference from which
the altitude is measured.
latitude number The latitude of the location.
longitude number The longitude of the
location.

Static Methods

Value
Description
areEqual areEqual(location1:Location,
location2:Location)
boolean Determines if
the specified
Location
objects are
equal.
normalizeLongitude normalizeLongitude(longitude:number) number Normalizes
the specified
longitude so
that it is
between -180
and 180.

Methods

clone clone() Location Returns a copy of the
Location object.
toString toString() string Converts the Location
object to a string.

153
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

"Bing Maps Key"});

}

function SetLocation()
{
// Parse the input string
var latLongArray = (document.getElementById("txtlatlong").value).split(",");

// Retrieve the latitude and longitude values- normalize the longitude value
var latVal = parseInt(latLongArray[0]);
var longVal =
Microsoft.Maps.Location.normalizeLongitude(parseInt(latLongArray[1]));

// Set the map center

154
map.setView({center:new Microsoft.Maps.Location(latVal, longVal)});

}
</script>
</head>
Latitude, Longitude: <input id="txtlatlong" type="text" value="40, -120"/>
<input type="button" value="Set center location" onclick="SetLocation();"/>
</body>
</html>
LocationRect Class
Represents a rectangle on the map.
Constructor

LocationRect LocationRect(center:Location,
width:number, height:number)
Initializes a new instance
of the LocationRect class.

Properties

center Location The location that defines the
center of the rectangle.
height number The height, in degrees, of the
rectangle.
width number The width, in degrees, of the
rectangle.

155
Static Methods

Value
Description
fromCorn
ers
fromCorners(northwest:Loc
ation, southeast:Location)
Location
Rect
Returns a LocationRect using the
specified locations for the northwest and
southeast corners.
fromEdge
s
fromEdges(north:number,
west:number,
south:number,
east:number,
altitude:number,
altitudeReference:Altitude
Reference)
Location
Rect
Returns a LocationRect using the
specified northern and southern latitudes
and western and eastern longitudes for
the rectangle boundaries.
fromLocat
ions
fromLocations(list of
locations/array)
Location
Rect
Returns a LocationRect using a list of
locations or an array of locations.
To provide a list of locations:

Microsoft.Maps.LocationRect.fromLocati
ons(location1, location2, location3);
To provide an array of locations:
var locations = [location1, location2,
location3];
Microsoft.Maps.LocationRect.fromLocati
ons(locations);
fromStrin
g
fromString(string:string) Location
Rect
Creates a LocationRect from a string with
the following format:
"north,west,south,east". North, west,
south and east specify the coordinate
number values.

Methods

clone clone() LocationRect Returns a copy of
the LocationRect
object.

156
contains contains(location:Location) boolean Returns whether
the specified
Location is within
the LocationRect.
getEast getEast() number Returns the
longitude that
defines the
eastern edge of
the LocationRect.
getNorth getNorth() number Returns the
latitude that
defines the
northern edge of
the LocationRect.
getNorthwest getNorthwest() Location Returns the
Location that
defines the
northwest corner
of the
LocationRect.
getSouth getSouth() number Returns the
latitude that
defines the
southern edge of
the LocationRect.
getSoutheast getSoutheast() Location Returns the
Location that
defines the
southeast corner
of the
LocationRect.
getWest getWest() number Returns the
latitude that
defines the
western edge of
the LocationRect.
intersects intersects(rect:LocationRect) boolean Returns whether
the specified

157
LocationRect
intersects with this
LocationRect.
LocationRect
object to a string.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

"Bing Maps Key"});

var viewRect = Microsoft.Maps.LocationRect.fromCorners(new
Microsoft.Maps.Location(40,-120), new Microsoft.Maps.Location(35,-115));

map.setView({bounds: viewRect});

158
}

</script>
</head>
</body>
</html>
Map Class
Represents a map.
Constructor

Map Map(containerElement:node,
options?:MapOptions or
ViewOptions)
the Map class.

Properties

entities EntityCollection The maps entities. Use this
property to add or remove
entities from the map.

Static Methods

getVersion getVersion() string Returns the version of
the map control.

159
Methods

blur blur() None Removes focus from the map
control so that it does not
respond to keyboard events.
dispose dispose() None Deletes the Map object and
releases any associated
resources.
focus focus() None Applies focus to the map
control so that it responds to
keyboard events.
getBounds getBounds() LocationRect Returns the location rectangle
that defines the boundaries of
the current map view.
getCenter getCenter() Location Returns the location of the
center of the current map
view.
getCopyrights getCopyrights(callback:fu
nction)
string[] Returns to the specified
callback an array of strings
representing the attributions of
the imagery currently
displayed on the map.
getCredentials getCredentials(callback:f
unction)
None Gets the session ID. This
method calls the callback
function with the session ID as
the first parameter.
map.getCredentials(function(
credentials)
{
if(credentials !==
null) { /* Valid session
Id. Use it to call REST
service */ }
});
getHeading getHeading() number Returns the heading of the
current map view.
getHeight getHeight() number Returns the height of the map

160
control.
getImageryId getImageryId() string Returns the string that
represents the imagery
currently displayed on the
map.
getMapTypeId getMapTypeId() string Returns a string that
represents the current map
type displayed on the map.
Valid map types are listed in
the MapTypeId Enumeration
topic.
getMetersPerPix
el
getMetersPerPixel() number Returns the current scale in
meters per pixel of the center
of the map.
getMode getMode() MapMode Returns the current map
mode.
getModeLayer getModeLayer() Node Returns the maps mode node.
getOptions getOptions() MapOptions Returns the map options that
have been set. Note that if an
option is not set, then the
default value for that option is
assumed and getOptions
returns undefined for that
option.
getPageX getPageX() number Returns the x coordinate of the
top left corner of the map
control, relative to the page.
getPageY getPageY() number Returns the y coordinate of the
top left corner of the map
control, relative to the page.
getRootElement getRootElement() Node Returns the maps root node.
getTargetBounds getTargetBounds() LocationRect Returns the location rectangle
that defines the boundaries of
the view to which the map is
navigating.
getTargetCenter getTargetCenter() Location Returns the center location of

161
the view to which the map is
navigating.
getTargetHeadin
g
getTargetHeading() number Returns the heading of the
view to which the map is
navigating.
getTargetMeters
PerPixel
getTargetMetersPerPixel() number Returns the scale in meters
per pixel of the center of the
navigating.
getTargetZoom getTargetZoom() number Returns the zoom level of the
navigating.
getUserLayer getUserLayer() Node Returns the maps user node.
getViewportX getViewportX() number Returns the x coordinate of the
viewport origin (the center of
the map), relative to the page.
getViewportY getViewportY() number Returns the y coordinate of the
viewport origin (the center of
the map), relative to the page.
getWidth getWidth() number Returns the width of the map
control.
getZoom getZoom() number Returns the zoom level of the
current map view.
getZoomRange getZoomRange() object:{min:nu
mber, max:
number}
Returns the range of valid
zoom levels for the current
map view.
isDownloadingTil
es
isDownloadingTiles() boolean Returns a boolean indicating
whether map imagery tiles are
currently being downloaded.
isMercator isMercator() boolean Returns a boolean indicating
whether the map is in a
regular Mercator nadir mode.
isRotationEnable
d
isRotationEnabled() boolean Returns true if the current map
type allows the heading to
change; false if the display
heading is fixed.

162
setMapType setMapType(mapTypeId:strin
g)
None Sets the current map type.
The specified mapTypeId must
be a valid map type ID or a
registered map type ID. Valid
map type IDs are listed in the
MapTypeId Enumeration topic.
setOptions setOptions({height:numbe
r, width: number})
None Sets the height and width of
the map.
setView setView(options:ViewOptio
ns)
None Sets the map view based on
the specified options.
tryLocationToPix
el
tryLocationToPixel(locati
on:Location |Location[],
reference?:PixelReference
)
null, Point, or
Point[]
Converts a specified Location
to a Point on the map relative
to the specified
PixelReference. If reference is
not specified,
PixelReference.viewport is
used. If the map is not able to
convert the Location, null is
returned.
Alternatively, converts an
array of Locations and returns
an array of Points if all
locations were converted. If
any of the conversions fail, null
is returned.
tryPixelToLocati
on
tryPixelToLocation(point:
Point |Point[],
reference?:PixelReference
)
null, Location,
or Location[]
Converts a specified Point to a
Location on the map relative to
the specified PixelReference.
If reference is not specified,
PixelReference.viewport is
used. If the map is not able to
convert the Point, null is
returned.
Alternatively, converts an
array of Points and returns an
array of Locations if all points
were converted. If any of the
conversions fail, null is
returned.

163

Events

used to click the map.
copyrightchanged None Occurs when the copyright
of the map changes.
dblclick eventArgs:MouseEventArgs Occurs when the mouse is
used to double click the
map.
imagerychanged None Occurs when the underlying
imagery used by the map
changes. This is different
from the maptypechanged
event, which occurs when
the map type being used is
changed.
keydown eventArgs:KeyEventArgs Occurs when a keyboard
key is pressed down.
keypress eventArgs:KeyEventArgs Occurs when a keyboard
key is pressed.
keyup eventArgs:KeyEventArgs Occurs when a keyboard
key that is pressed down is
released.
maptypechanged None Occurs when the map type
changes.
mousedown eventArgs:MouseEventArgs Occurs when the left mouse
button is pressed when the
mouse cursor is over the
map.
mousemove eventArgs:MouseEventArgs Occurs when the mouse
cursor moves over the map.
mouseout eventArgs:MouseEventArgs Occurs when the mouse
cursor moves out of the area
covered by the map.

164
mouseover eventArgs:MouseEventArgs Occurs when the mouse is
over the map.
mouseup eventArgs:MouseEventArgs Occurs when the left mouse
button is lifted up when the
map.
mousewheel eventArgs:MouseEventArgs Occurs when the mouse
wheel is used when the
map.
rightclick eventArgs:MouseEventArgs Occurs when the right
mouse button is used to
click the map.
targetviewchanged None Occurs when the view
towards which the map is
navigating changes.
tiledownloadcomplete None Occurs when all the map
tiles of a map view have
loaded.
viewchange None Occurs for every frame of a
map view change.
viewchangeend None Occurs when the map view
is done changing.
This event occurs when a
view is the same for one
frame of a map view
change. For example, if the
mouse is used to drag the
map to change the view, but
pauses during the drag
(without releasing the
mouse button),
viewchangeend occurs
twice. You can use the
addThrottledHandler method
to customize the number of
events that occur.

165
viewchangestart None Occurs when the map view
starts changing.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

}

</script>
</head>
</body>
</html>

166
MapMode Class
Represents a map mode.
Mercator Map Mode Methods
The following methods are available for the MapTypeId values aerial, auto, birdseye,
collinsBart, mercator, ordnanceSurvey, and road.

Name Definition Retu
rn
Valu
e
Description
getDrawShapesIn
SingleLayer
getDrawShapesInSingleLayer() bool
ean
Gets whether the mode
should draw shapes
(polygons, polylines, or
pushpins) in a single layer,
independent of the
EntityCollection order.
getShouldClipPoly
gons
getShouldClipPolygons() bool
ean
Gets whether to clip
polygons if they are too large
for the map in the mode.
[Deprecated] Use
setOptions.
setDrawShapesInS
ingleLayer
[Deprecated] Use setOptions.
setDrawShapesInSingleLayer(drawInS
ingleLayer:boolean)
Non
e
[Deprecated] Use
setOptions.
Sets whether the mode
should draw shapes
(polygons, polylines, or
pushpins) in a single layer,
independent of the
EntityCollection order. A
shape is drawn by default in
its own layer, but if one
shape covers another shape,
then the top-layered shape
event is what is thrown. You
can prevent this issue by
calling
setDrawShapesInSingleLayer
(true).
setOptions setOptions(options:MapModeOptio Non Sets options for the current

167
Name Definition Retu
rn
Valu
e
Description
ns) e map mode.
setViewChangeEn
dDelay
setViewChangeEndDelay(delay:numb
er)
Non
e
Sets the specified number of
milliseconds after the last
viewchange event before
viewchangeend event is
fired. This allows you to
control how often the
viewchangeend event is
fired when the map is
panned.
For example, to set a 1
second delay before the
viewchangeend event fires,
do the following:

map.getMode().setViewChang
eEndDelay(1000);

MapModeOptions Object
Represents options to customize a map mode.
Properties

shouldClipPolygons boolean Sets whether the mode
should clip polygons if they
are too large for the map in
this mode.
drawShapesInSingleLayer boolean Sets whether the mode should
draw shapes (polygons,
polylines, or pushpins) in a
single layer, independent of
the EntityCollection order. A

168
shape is drawn by default in
its own layer, but if one shape
covers another shape, then
the top-layered shape event is
what is thrown. You can
prevent this issue by setting
this parameter to true.

MapOptions Object
Represents options to customize the map that is displayed.
Properties

backgroundColor Color Class The color to use for the map control
background. The default color is
#F4F2EE.
This property can only be set when
using the Map constructor.
credentials string The Bing Maps Key used to
authenticate the application.
customizeOverlays boolean A boolean indicating whether to load
the new Bing Maps overlay styles. The
default value is false.
This property setting only takes effect if
the Microsoft.Maps.Overlays.Style
module is loaded.
disableBirdseye boolean A boolean indicating whether to disable
the birds eye map type. The default
value is false. If this property is set to
true, birds eye will be removed from
the map navigation control and the
birdseye MapTypeId is disabled.
Additionally, the auto map type will only

169
display road or aerial.
disableKeyboardInput boolean A boolean value indicating whether to
disable the maps response to keyboard
input. The default value is false.
disableMouseInput boolean A boolean value indicating whether to
disable the maps response to mouse
disablePanning boolean A boolean value indicating whether to
disable the users ability to pan the
map. The default value is false.
disableTouchInput boolean A boolean value indicating whether to
disable the maps response to touch
disableUserInput boolean A boolean value indicating whether to
disable the maps response to any user
disableZooming boolean A boolean value indicating whether to
disable the users ability to zoom in or
out. The default value is false.
enableClickableLogo boolean A boolean value indicating whether the
Bing
TM
logo on the map is clickable. The
default value is true.
enableSearchLogo boolean A boolean value indicating whether to
enable the Bing
TM
hovering search logo
on the map. The default value is true.
fixedMapPosition boolean A boolean indicating whether the div
containing the map control is fixed on
the page and the browser will not be
resized. The default value is false. In
this case the map control redraws if
necessary based on any div or window

170
resize.
If this property is set to true, the map
control does not check the size of the
div containing it every time the map
view changes, thus increasing the
performance of the control.
height number The height of the map. The default
value is null. If no height is specified,
the height of the div is used. If height is
specified, then width must be specified
as well.
inertiaIntensity number A number between 0 and 1 specifying
the intensity of the inertia animation
effect. The inertia effect increases as
the intensity value gets larger. The
default value is .85. Setting this
property to 0 indicates no inertia effect.
The useInertia property must be set to
true for the inertiaIntensity value to
have an effect.
showBreadcrumb boolean A boolean value indicating whether to
display the breadcrumb control. The
breadcrumb control shows the current
center locations geography hierarchy.
For example, if the location center is
Seattle, the breadcrumb control
displays World . United States . WA.
The default value is false.
The breadcrumb control displays best
when the width of the map is at least
300 pixels.
showCopyright boolean A boolean value indicating whether or
not to show the map copyright. The

171

Bing Maps Platform API Terms
of Use requires copyright
information to be displayed.
Only set this option to false
when copyright information is
displayed through alternate
means.
showDashboard boolean A boolean value indicating whether to
show the map navigation control. The
showMapTypeSelector boolean A boolean value indicating whether to
show the map type selector in the map
navigation control. The default value is
true.
showScalebar boolean A boolean value indicating whether to
show the scale bar. The default value is
true.
theme Object A theme object specifying the theme to
use for the design of the map. To get
the latest Bing Maps design, load the
module and assign a BingTheme
object to this property.
tileBuffer number A number between 0 and 4 specifying
how many tiles to use as a buffer
around the map view. The default value
is 0.
useInertia boolean A boolean value indicating whether to

172
use the inertia animation effect during
map navigation. The default value is
true.
width number The width of the map. The default value
is null. If no width is specified, the width
of the div is used. If width is specified,
then height must be specified as well.

Example
<html>
<head>
<title></title>



function GetMap()
{

// Set the map and view options, setting the map style to Road and
// removing the user's ability to change the map style
var mapOptions = {credentials:"Bing Maps Key",
height: 400,
width: 400,
showMapTypeSelector: false};


173
mapOptions);

}

</script>
</head>
<div id='mapDiv' style="position:relative;"></div>
</body>
</html>
MapTypeId Enumeration
Contains identifiers for the imagery displayed on the map.
Constants

Name Description
a The aerial map type is being used.
auto The map is set to choose the best imagery for
the current view.
be The birds eye map type is being used.
cb Collins Bart (mkt=en-gb) map type is being
used.
m The Mercator map type is being used. This
setting removes the base map tiles.
os Ordnance Survey (mkt=en-gb) map type is
being used.
r The road map type is being used.

174
Example
This code sample sets the map imagery to Collins Bart (collinsBart). Since this imagery is only
supported for the en-gb culture, the mkt parameter of the control is set to this culture.
<html>
<head>
<title></title>

src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=en-
gb"></script>

function GetMap()
{

{credentials:"Bing Maps Key", center: new Microsoft.Maps.Location(51.5, -.1), zoom: 10,
mapTypeId:Microsoft.Maps.MapTypeId.collinsBart});
}
</script>
</head>
</body>
</html>
See Also
Localizing the Map

175
The following methods allow you to register and load your own modules for use by the map
control. More information about building your own module is in the Building Your Own Module
topic.
Methods

n
Value
Description
loadModule loadModule(moduleKey:string,
options:function)
None Loads the specified registered
module, making its functionality
available. An optional function can be
specified that is called when the
module is loaded.
To register a module, use the
registerModule method.
The following Bing Maps modules
are available:
Microsoft.Maps.AdvancedSh
apes
Microsoft.Maps.Overlays.Style
Microsoft.Maps.Search
Microsoft.Maps.Themes.Bing
Theme
Microsoft.Maps.Traffic
Microsoft.Maps.VenueMaps
moduleLoade
d
moduleLoaded(moduleKey:string) None Signals that the specified module has
been loaded and if specified, calls
the callback function in loadModule.
Call this method at the end of your
module script.
registerModul
e
registerModule(moduleKey:strin
g, scriptUrl:string,
options:{styleURLs})
None Registers a module with the map
control. The name of the module is
specified in moduleKey, the module

176
n
Value
Description
script is defined in scriptUrl, and the
options provides the location of a
*.css file to load with the module.

To minimize possible
conflicts with other custom
modules, choose a unique
module name (defined in
moduleKey). For example,
you can use your company
name in the name of the
module.
Once you have registered a module,
you can make its functionality
available by loading it using
loadModule.

Example
The code below shows how to register and load a module, named MyModule1. The code for
MyModule1 is found in the next code section.
<html>
<head>
<title></title>



var map;

177

function myModuleLoaded()
{
alert("myModule has loaded.");

// Use the function provided by the newly loaded module
var myModule = new MyModule(map);
myModule.HelloWorld();

}

function GetMap()
{
var options = {credentials: "Bing Maps Key"};
map = new Microsoft.Maps.Map(document.getElementById('mapDiv'), options);

// Register and load a new module
Microsoft.Maps.registerModule("MyModule1",
"http://example.com/mymodule.js");
Microsoft.Maps.loadModule("MyModule1", { callback: myModuleLoaded });

}

</script>
</head>
</body>
</html>

// mymodule.js

178
function MyModule(map)
{
this.HelloWorld = function()
{
alert("Hello World - map Center is " + map.getCenter().toString());
}
}
Microsoft.Maps.moduleLoaded('MyModule1');
See Also
Contains the arguments for mouse events.
Properties

eventName string The event that occurred.
the event is handled. If this
property is set to true, the
default map control behavior
for the event is cancelled.
isPrimary boolean A boolean indicating if the
primary button (such as the left
mouse button or a tap on a
touch screen) was used.
isSecondary boolean A boolean indicating if the
secondary mouse button (such
as the right mouse button) was
used.
isTouchEvent boolean A boolean indicating whether
the event that occurred was a

179
touch event.
originalEvent object The original browser event.
pageX number The x-value of the pixel
coordinate on the page of the
mouse cursor.
pageY number The y-value of the pixel
coordinate on the page of the
mouse cursor.
target object The object that fired the event.
targetType string The type of the object that fired
the event. Valid values include
the following: map, polygon,
polyline, or pushpin
wheelDelta number The number of units that the
mouse wheel has changed.

Methods

getX getX() number Returns the x-value of
the pixel coordinate,
relative to the map, of
the mouse.
getY getY() number Returns the y-value of
the pixel coordinate,
relative to the map, of
the mouse.

Example
<html>
<head>

180
<title></title>



var map = null;

function GetMap()
{

Microsoft.Maps.Events.addHandler(map, 'click', displayEventInfo);

}

function displayEventInfo(e) {
document.getElementById("textBox").value = loc.latitude + ", " +
loc.longitude;

}
}

</script>
</head>

181
Latitude, Longitude:
<input id='textBox' type="text" style="width:250px;"/>
</body>
</html>
PixelReference Enumeration
Contains constants used to show how pixels are defined.
Constants

Name Description
control The pixel is defined relative to the map controls
root element, where the top left corner of the
map control is (0, 0). Using this option might
cause a page reflow which may negatively
impact performance.
page The pixel is defined relative to the page, where
the top left corner of the HTML page is (0, 0).
This option is best used when working with
mouse or touch events. Using this option might
cause a page reflow which may negatively
impact performance.
viewport The pixel is defined in viewport coordinates,
relative to the center of the map, where the
center of the map is (0, 0). This option is best
used for positioning geo-aligned entities added
to the user layer.

Methods

isValid isValid(reference:PixelReference) boolean Determines whether
the specified

182
reference is a
supported
PixelReference.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

// Add handler for the map click event.

}


183

var point = new Microsoft.Maps.Point(e.pageX, e.pageY,
Microsoft.Maps.PixelReference.page);
var loc = e.target.tryPixelToLocation(point,
Microsoft.Maps.PixelReference.page);

if (loc!=null)
{
alert("The location " + loc.latitude + ", " + loc.longitude + " was
clicked.");
}

}
}

</script>
</head>
</body>
</html>
Point Class
Represents a point on the map.
Constructor

Point Point(x:number, y:number) Initializes a new instance of

184
the Point class.

Properties

x number The x value of the coordinate.
y number The y-value of the coordinate.

Static Methods

areEqual areEqual(point1:Point,
point2:Point)
boolean Determines if the
specified points are
equal.
clone clone(Point) Point Returns a copy of the
Point object.

Methods

clone clone() Point Returns a copy of the
Point object.
toString toString() string Converts the Point
object into a string.

Example
<html>
<head>

185
<title></title>



var map = null;

function GetMap()
{
{credentials:"Bing Maps Key "});

// Add handler for the map click event.

}



if (loc!=null)
{
alert("The location " + loc.latitude + ", " + loc.longitude + " was
clicked.");
}

186
}
}

</script>
</head>
</body>
</html>
Polygon Class
Represents a polygon on the map.
Constructor

Polygon Polygon(locations:Location[],
options?:PolygonOptions)
the Polygon class.

Methods

getFillColor getFillColor() Color Returns the
color of the
inside of the
polygon.
getLocations getLocations() Location[] Returns the
locations that
define the
corners of the
polygon.
getStrokeColor getStrokeColor() Color Returns the

187
color of the
outline of the
polygon.
getStrokeDashArray getStrokeDashArray() string Returns the
string that
represents the
stroke/gap
sequence
used to draw
the outline of
the polygon.
getStrokeThickness getStrokeThickness() number Returns the
thickness of
the outline of
the polygon.
getVisible getVisible() boolean Returns
whether the
polygon is
visible. A
value of false
indicates that
the polygon is
hidden,
although it is
still an entity
on the map.
setLocations setLocations(locations:Location[]) None Sets the
locations that
define the
corners of the
polygon.
setOptions setOptions(options:PolygonOptions) None Sets options
for the
polygon.
Polygon object
to a string.

188
Events

used to click the polygon.
polygon.
of the polygon or any of
the polygons options
change.
mousedown eventArgs:MouseEventArgs Occurs when the left
mouse button is pressed
when the mouse is over
the polygon.
cursor moves out of the
area covered by the
polygon.
over the polygon.
mouseup eventArgs:MouseEventArgs Occurs when the left
mouse button is lifted up
the polygon.
click the polygon.

Example
<html>
<head>
<title></title>

189



function GetMap()
{


// Create a polygon
location1);

map.entities.push(polygon)

// Set the view
map.setView({bounds: Microsoft.Maps.LocationRect.fromLocations(vertices)});

}

190

</script>
</head>
</body>
</html>
PolygonOptions Object
Represents the options for a polygon.
Properties

fillColor Color The color of the inside of the polygon.
infobox Infobox The info box associated with this
polygon. If an info box is assigned and
the Microsoft.Maps.Themes.BingTheme
of the polygon occur.
strokeColor Color The color of the outline of the polygon.
strokeDashArray string A string representing the stroke/gap
sequence to use to draw the outline of
the polygon. The string must be in the
format S, G, S*, G*, where S represents
the stroke length and G represents gap
length. Stroke lengths and gap lengths
can be separated by commas or spaces.
For example, a stroke dash string of 1 4
2 1 would draw the polygon outline with
a dash, four spaces, two dashes, one
space, and then repeated.
strokeThickness number The thickness of the outline of the
polygon.

191
hide the polygon. A value of false
indicates that the polygon is hidden,
although it is still an entity on the map.

Example
<html>
<head>
<title></title>



function GetMap()
{


// Create a polygon

192
location1);
var polygon = new Microsoft.Maps.Polygon(vertices,
{fillColor: new Microsoft.Maps.Color(100,100,0,100),
strokeColor: new Microsoft.Maps.Color(200,0,100,100),
strokeThickness: 5});

map.entities.push(polygon)

// Set the view
map.setView({bounds: Microsoft.Maps.LocationRect.fromLocations(vertices)});

}

</script>
</head>
</body>
</html>
Polyline Class
Represents a polyline on the map.
Constructor

Polyline Polyline(locations:Location[],
options?:PolylineOptions)
the Polyline class.

193
Methods

locations that
define the
polyline.
color of the
polyline.
string that
represents the
stroke/gap
sequence
used to draw
the polyline.
thickness of
the polyline.
whether the
polyline is
visible. A
value of false
indicates that
the polyline is
hidden,
although it is
still an entity
on the map.
locations that
define the
polyline.
setOptions setOptions(options:PolylineOptions) None Sets options
for the
polyline.

194
Polyline object
to a string.

Events

used to click the polyline.
polyline.
of the polyline or any of the
polylines options change.
the polyline.
area covered by the
polyline.
over the polyline.
the polyline.
click the polyline.

195
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new


// Create a polyline
location5);
var line = new Microsoft.Maps.Polyline(lineVertices);

196

// Add the polyline to the map

}

</script>
</head>
</body>
</html>
PolylineOptions Object
Represents the options for a polyline.
Properties

strokeColor Color The color of the polyline.
strokeDashArray string A string representing the
stroke/gap sequence to use to
draw the polyline. The string
must be in the format S, G, S*,
G*, where S represents the
stroke length and G represents
gap length. Stroke lengths and
gap lengths can be separated
by commas or spaces. For
example, a stroke dash string
of 1 4 2 1 would draw the
polyline with a dash, four
spaces, two dashes, one
space, and then repeated.

197
strokeThickness number The thickness of the polyline.
visible boolean A boolean indicating whether
to show or hide the polyline. A
value of false indicates that
the polyline is hidden, although
it is still an entity on the map.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new


198

// Create a polyline
location5);
var line = new Microsoft.Maps.Polyline(lineVertices,{strokeColor:new
Microsoft.Maps.Color(200, 100, 0, 100), strokeThickness:5, strokeDashArray:"5 2"});

// Add the polyline to the map

}

</script>
</head>
</body>
</html>
Position Class
Represents the position of a user on a map.
Properties

coords Coordinates The position as a W3C
Coordinates object.
timestamp string The time when the position was
determined, in the form of a

199
DOMTimeStamp.

See Also
PositionCircleOptions Object
Contains options for the addAccuracyCircle method of the GeoLocationProvider class.
Properties

polygonOptions PolygonOptions The polygon options for the
geo location accuracy circle.
showOnMap boolean A boolean indicating whether
to display the geo location
accuracy circle. The default
value is true. If this property
is set to false, a geo location
accuracy circle is not drawn
and any existing accuracy
circles are removed.

Example
<html>
<head>
<title></title>


200


var map;
var geoLocationProvider;

function GetMap()
{


map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);

geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);

geoLocationProvider.getCurrentPosition({successCallback:drawCircle,
showAccuracyCircle:false});

}

function drawCircle(args)
{
// Draw the accuracy circle using a different color
geoLocationProvider.addAccuracyCircle(args.center, 50000, 50000,
{polygonOptions:{fillColor:new Microsoft.Maps.Color(100,100,0,100), strokeColor:new
Microsoft.Maps.Color(100,100,0,100)}});
}

201

</script>
</head>
</body>
</html>
PositionError Class
Represents the error when a user position request does not succeed.
Properties

errorCode number The error code.
Any one of the following error
codes may be returned:
0 An error occurred that is
not covered by other error
codes.
1 The application does not
have permission to use the
GeoLocation API.
2 The position of the host
device could not be
determined.
3 The specified timeout
was exceeded.
internalError string The error message. This
message is for the developer
and is not intended to be
displayed to the end user.

202
See Also
Contains options for the getCurrentPosition method of the GeoLocationProvider class.
Properties

enableHighAccuracy boolean A boolean indicating whether
only a high accuracy result
should be retrieved. The
default value is false. Setting
this property to true may
result in a slower response
time.
errorCallback function The function to call when an
error occurs during the user
location request. The callback
function must accept one
argument. The argument
object contains two properties,
internalError, a PositionError
type, and errorCode, a
number.
Any one of the following
errorCode values may be
returned:
1 The application origin
does not have permission
to use the GeoLocation
API.
2 The position of the user
could not be determined
because of a device
failure.
3 The time specified in
timeout has been

203
exceeded.
4 A request is already in
process.
5 The users browser
does not support geo
location.
maximumAge number A number indicating the
acceptable age, in
milliseconds, of a cached geo
location result to return. The
default value is 0, which
indicates a new (not cached)
result will be retrieved.
showAccuracyCircle boolean A boolean indicating whether
to display the polygon on the
map that shows the accuracy
of the returned geo location.
The default value is true.
successCallback function The function to call when the
users location was
successfully retrieved. The
callback function must accept
one argument. The argument
object contains two properties,
center, a Location type, and
position, a Position type.
timeout number The length of time, in
milliseconds, to allow for the
geo location request to return.
By default there is no timeout.
updateMapView boolean A boolean indicating whether
to update the map view with
the best view of the users
location (if the request is
successful). The default value
is true.

204
Example
<html>
<head>
<title></title>



var map;

function GetMap()
{


map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);

var geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);

geoLocationProvider.getCurrentPosition({successCallback:displayCenter});

}

205
function displayCenter(args)
{
// Display the user location when the geo location request returns
alert("The user's location is " + args.center);
}

</script>
</head>
</body>
</html>
Pushpin Class
Defines a pushpin on the map.
Constructor

Pushpin Pushpin(location:Location,
options?:PushpinOptions)
the Pushpin class.

Methods

getAnchor getAnchor() Point Returns the
point on the
pushpin icon
which is
anchored to the
pushpin location.
An anchor of
(0,0) is the top

206
left corner of the
icon.
getIcon getIcon() string Returns the
pushpin icon.
getHeight getHeight() number Returns the
height of the
pushpin, which
is the height of
the pushpin icon.
getLocation getLocation() Location Returns the
location of the
pushpin.
getText getText() string Returns the text
associated with
the pushpin.
getTextOffset getTextOffset() Point Returns the
amount the text
is shifted from
the pushpin icon.
getTypeName getTypeName() string Returns the type
of the pushpin.
the pushpin is
visible. A value
of false
indicates that the
pushpin is
hidden, although
it is still an entity
on the map.
getWidth getWidth() number Returns the
width of the
pushpin, which
is the width of
the pushpin icon.
getZIndex getZIndex() number Returns the z-
index of the

207
pushpin with
respect to other
items on the
map.
setLocation setLocation(location:Location) None Sets the location
of the pushpin.
setOptions setOptions(options:PushpinOptions) None Sets options for
the pushpin.
Pushpin object
to a string.

Events

used to click the pushpin.
pushpin.
drag object: {entity:Pushpin} Occurs when the pushpin
is being dragged.
dragend eventArgs:MouseEventArgs Occurs when the pushpin
stops being dragged.
dragstart eventArgs:MouseEventArgs Occurs when the pushpin
starts being dragged.
of the pushpin or any of
the pushpins options
change.
the pushpin.

208
area covered by the
pushpin.
over the pushpin.
the pushpin.
click the pushpin.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

209


var pin = new Microsoft.Maps.Pushpin(center, {draggable: true});

// Add a handler to the pushpin drag
Microsoft.Maps.Events.addHandler(pin, 'mouseup', DisplayLoc);

}

function DisplayLoc(e){
if (e.targetType == 'pushpin'){

var pinLoc = e.target.getLocation();
alert("The location of the pushpin is now " + pinLoc.latitude + ", " +
pinLoc.longitude);

}
}

</script>
</head>
<b>Drag the pushpin to a new location.</b>
</body>
</html>

210
Represents the options for a pushpin.
Properties

anchor Point The point on the pushpin icon which is
anchored to the pushpin location. An
anchor of (0,0) is the top left corner of
the icon. The default anchor is the
bottom center of the icon.
draggable boolean A boolean indicating whether the
pushpin can be dragged to a new
position with the mouse.
height number The height of the pushpin, which is the
height of the pushpin icon. The default
value is 39.
htmlContent string The HTML that represents the pushpin.
icon string The path of the image to use as the
pushpin icon.
infobox Infobox The info box associated with this
pushpin. If the
of the pushpin occur.
state EntityState The state of the pushpin, such as
highlighted or selected. To get the latest
pushpin state design, load the
module before creating the pushpin.
text string The text associated with the pushpin.
textOffset Point The amount the text is shifted from the
pushpin icon. The default value is (0,5).
typeName string The type of the pushpin, as a string. The
pushpin DOM (document object model)

211
node created for the pushpin will have
the specified typeName. A standard
pushpin type is used unless the
module is loaded, in which case
typeName can be set to micro to use
the micro pushpin type.
hide the pushpin. The default value is
true. A value of false indicates that the
pushpin is hidden, although it is still an
entity on the map.
width number The width of the pushpin, which is the
width of the pushpin icon. The default
value is 25.
zIndex number The z-index of the pushpin with respect
to other items on the map.

Example
This example uses the image below, named BluePushpin.png, as the pushpin icon.

<html>
<head>
<title></title>



212

var map = null;

function GetMap()
{


var pin = new Microsoft.Maps.Pushpin(center, {icon:"BluePushpin.png",
height:50, width:50, anchor:new
Microsoft.Maps.Point(0,50), draggable: true});

}

</script>
</head>

</body>
</html>
TileLayer Class
Represents a tile layer.

213
Constructor

TileLayer TileLayer(options:TileLayerOptions) Initializes a new instance
of the TileLayer class.

Methods

Type
Description
getOpacity getOpacity() number Returns the opacity of the
tile layer, defined as a
double between 0 (not
visible) and 1.
getTileSourc
e
getTileSource(projection:string) TileSourc
e
Returns the tile source of
the tile layer.
The projection parameter
accepts the following
values: mercator,
enhancedBirdseyeNorthUp,
enhancedBirdseyeSouthUp
,
enhancedBirdseyeEastUp,
enhancedBirdseyeWestUp
getVisible getVisible( boolean Returns whether the tile
layer is visible. A value of
false indicates that the tile
layer is hidden.
getZIndex getZIndex() number Returns the z-index of the
tile layer with respect to
other items on the map.
setOptions setOptions(options:TileLayerOptions
)
None Sets options for the tile
layer.
toString toString() string Converts the TileLayer
object to a string.

214
Events

tiledownloadcomplete None Occurs when all the tiles of
the tile layer have loaded.

Example
<html>
<head>
<title></title>



function GetMap()
{
{credentials:"Bing Maps Key", center:new Microsoft.Maps.Location(48.03,-
122.4), zoom:12, mapTypeId: Microsoft.Maps.MapTypeId.road });

try
{


215
opacity: .7 });


}
catch(err)
{
}

}

</script>
</head>
</body>
</html>
See Also
TileLayerOptions Object
Defines the options for a tile layer.
Properties

216
animationDisplay AnimationVisibility The tile layers visibility
during animation. You can
use this property to prevent
overlays from displaying
during animations, which can
impact performance. The
default value is auto.
downloadTimeout number The number of milliseconds
allowed for the tile layer
image download. If the
timeout occurs before the
image is fully downloaded,
the map control considers
the download a failure. The
default value is 10000.
mercator TileSource The tile source for the tile
layer.
opacity number The opacity of the tile layer,
defined by a number
between 0 (not visible) and
1.
visible boolean A boolean indicating whether
to show or hide the tile layer.
The default value is true. A
value of false indicates that
the tile layer is hidden,
although it is still an entity on
the map.
zIndex number The z-index of the tile layer,
with respect to other items
on the map.

Example
<html>

217
<head>
<title></title>



var map = null;
var tilelayer = null;

function GetMap()
{
{credentials:"Bing Maps Key", center:new Microsoft.Maps.Location(48.03,-122.4), zoom:12,

try
{

tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource, opacity:
.7 });


}
catch(err)

218
{
}

}

function SetOpacity()
{

var opacityVal = parseFloat(document.getElementById("txtOpacity").value);

if ((opacityVal > 1) || (opacityVal < 0))
{
alert("The opacity value must be between 0 and 1.");
}
else
{
tilelayer.setOptions({opacity: opacityVal});
}

}

</script>
</head>
<input id="txtOpacity" type="text" value=".1" style="width:25px;"/>
<input type="button" value="Set Opacity" onclick="SetOpacity();"/>
</body>
</html>

219
See Also
TileSource Class
Defines a tile source for a tile layer.
Constructor

TileSource TileSource(options:TileSourceOptions) Initializes a new instance
of the TileSource class.

Methods

Name Definition Return Type Description
getHeight getHeight() Number Returns the pixel
height of each tile in
the tile source.
getUriConstructor getUriConstructor() string Returns a string
that constructs tile
URLs used to
retrieve tiles for the
tile layer.
getWidth getWidth() number Returns the pixel
width of each tile in
the tile source.
TileSource object to
a string.

Example

220
<html>
<head>
<title></title>



function GetMap()
{
var map = new
Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key",

try
{

opacity: .7 });


}
catch(err)
{

221
}

}

</script>
</head>
</body>
</html>
See Also
TileSourceOptions Object
Defines options for a tile source.
Properties

height number The pixel height of each tile in
the tile source. The default
value is 256.
The specified height needs to
be a multiplier of 2 of the
current projections tile height
for the tiles to be shown. For
example, since Mercator tile
source tiles are 256x256, this
projection supports tiles that
are 64x64, 128x128, 256x256,
512x512, or any combination of
these.

222
uriConstructor string The string that constructs the
URLs used to retrieve tiles from
the tile source. This property is
required.
The uriConstructor will replace
{subdomain} and {quadkey}.
You can also set this to a
callback function that receives
a tile URL with location (x,y)
and zoom level properties. This
is useful when you want to use
tiles with x/y/zoom URL
structure, or if you are
connecting to a Web Map
Service (WMS) and need to
pass the tile bounding box in
the URL. For an example, see
the Example section below.
width number The pixel width of each tile in
the tile source. The default
value is 256.
The specified width needs to be
a multiplier of 2 of the current
projections tile width for the
tiles to be shown. For example,
since Mercator tile source tiles
are 256x256, this projection
supports tiles that are 64x64,
128x128, 256x256, 512x512, or
any combination of these.

Example
<html>
<head>
<title></title>

223



function GetMap()
{
var map = new

try
{

opacity: .7 });


}
catch(err)
{
}

}

224

</script>
</head>
</body>
</html>

The following example shows how to use a callback function with the URI constructor.

//Create a tile layer source
var tileSource = new Microsoft.Maps.TileSource({ uriConstructor: getTilePath });

function getTilePath(tile)
{
//Tile Format http://tile.contoso.org/hiking/{z}/{x}/{y}.png
return 'http://tile.contoso.com/hiking/' + tile.levelOfDetail + '/' + tile.x + '/' +
tile.y + '.png';
}
See Also
ViewOptions Object
Contains options for the map view.
Properties

animate boolean A boolean that specifies
whether to animate map
navigation. Note that this option
is associated with each
setView call and defaults to

225
true if not specified.
bounds LocationRect The bounding rectangle of the
map view. If both are specified,
bounds takes precedence over
center.
center Location The location of the center of
the map view. If both are
specified, bounds takes
precedence over center.
centerOffset Point The amount the center is
shifted. This property is ignored
if center is not specified.
heading number The directional heading of the
map. The heading is
represented in geometric
degrees with 0 or 360 = North,
90 = East, 180 = South, and
270 = West.
labelOverlay LabelOverlay A constant indicating how map
labels are displayed.
mapTypeId string The map type of the view. Valid
map types are found in the
MapTypeId Enumeration topic.
padding number The amount of padding to be
added to each side of the
bounds of the map view.
zoom number The zoom level of the map
view.
For information about map
scale and resolution with
respect to zoom level, see
Understanding Scale and
Resolution.

226
Remarks
To 'lock' the map in a certain position, disable mouse and keyboard events during the application
session. The following code disables mouse events.
// Attach an event handler for a mousemove event.
Microsoft.Maps.Events.addHandler(map, "mousemove", cancelEvent);

// When the mouse is used, the cancelEvent function will
// get called. Setting the handled property to true will
// disable the mousemove event, which disables panning.
function cancelEvent(e)
{
e.handled = true;
}
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
// Set the initial map and view settings

227
var initialViewBounds = Microsoft.Maps.LocationRect.fromCorners(new
Microsoft.Maps.Location(43,-123), new Microsoft.Maps.Location(33,-113));
var options = {credentials:"Bing Maps Key", width: 500, height: 500, bounds:
initialViewBounds, mapTypeId:Microsoft.Maps.MapTypeId.aerial, animate: false};

map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),options);

}

function SetZoom()
{
// Retrieve the zoom level set by the user - converting it to a number.
var zoomLevel = parseInt(document.getElementById("txtZoom").value);

// Get the existing options.
var options = map.getOptions();

// Set the zoom level of the map
options.zoom = zoomLevel;
map.setView(options);

}

</script>
</head>
<div id='mapDiv' style="position:relative;"></div>
<input id="txtZoom" type="text" value="1"/>
<input type="button" value="Set Zoom" onclick="SetZoom();"/>
</body>
</html>

228
Microsoft.Maps.AdvancedShapes API
Reference
This section contains reference documentation for the Microsoft.Maps.AdvancedShapes API,
which contains types that allow you to draw complex shapes on your Bing Maps AJAX Control
7.0 map.
Before you can access the types found in the Microsoft.Maps.AdvancedShapes API, you
must first load this module using the loadModule method. Information about loading
modules is in the Module Loading Methods topic.
In This Section
Polygon Class
EntityCollection Class (AdvancedShapes)
Contains a collection of entities. These collection of entities can represent a multiple shape entity
on the map. When the Microsoft.Maps.AdvancedShapes module is loaded, this class inherits and
replaces the basic EntityCollection class.
An Entity can be any one of the following types: Infobox, Polygon, Polyline, Pushpin, TileLayer, or
EntityCollection.
Constructor

EntityCollection EntityCollection(options?:EntityCollectionOptions) Initializes a new
instance of the
EntityCollection
class.

Methods

229
Value
Description
clear clear() None Removes all
entities from the
collection.
get get(index:number) Entity* Returns the entity
at the specified
index in the
collection.
getLength getLength() number Returns the
number of entities
in the collection.
the entity
collection is visible
on the map.
getZIndex getZIndex() number Gets the z-index
of the entity
collection with
respect to other
items on the map.
indexOf indexOf(entity:Entity*) number Returns the index
of the specified
entity in the
collection. If the
entity is not found
in the collection, -1
is returned.
insert insert(entity:Entity*, index:number) None Inserts the
specified entity
into the collection
at the given index.
pop pop() Entity* Removes the last
entity from the
collection and
returns it.
push push(entity:Entity*) None Adds the specified
entity to the last
position in the

230
Value
Description
collection.
remove remove(entity:Entity*) Entity* Removes the
specified entity
from the collection
and returns it.
removeAt removeAt(index:number) Entity* Removes the
entity at the
specified index
from the collection
and returns it.
setOptions setOptions(options:EntityCollectionOptions) None Sets the options
for the entity
collection.
EntityCollection
object to a string.

Events

entityadded object: {collection:
following happens:
An entity is added to the
collection.
entityadded event.
when an entity is added to
collection #2, two entityadded
events are fired.

231
entitychanged object: {collection:
following happens:
The collection changes.
An entity of the
collection changes.
entitychanged event.
changes, two entitychanged
events are fired.
entityremoved object: {collection:
following happens:
An entity of the
collection is removed.
entityremoved event.
is removed, two
entityremoved events are
fired.

Remarks
The AdvancedShapes EntityCollection class differs from the base EntityCollection class in two
ways:

232
When an entity of the collection fires an event, the event will fire for all entities of the
collection. For example, if the mouseover event if fired for a pushpin in an entity collection,
then the entity collections mouseover event is fired.
Setting the options of the entity collection sets the options of all its entities unless the entity
collection option bubble is set to false. For example, by default, in an entity collection
composed of multiple polygons, setting one polygons fill color to red changes the fill color of
all of the other polygons in the entity collection to red.
Polygon Class (AdvancedShapes)
Represents a complex polygon on the map. When the Microsoft.Maps.AdvancedShapes module
is loaded, this class replaces the basic Polygon Class.
Constructor

Polygon Polygon(locationsArrays:[Location[]],
options?:PolygonOptions)
a complex Polygon. The
locationsArrays array
represents the polygon
rings, where each element
of the array is an array of
Location objects that
defines a ring. This
constructor can be used to
create a normal polygon, a
multi-polygon, a polygon
with holes, or a combination
of polygons.

Methods

getFillColor getFillColor() Color Returns the
color of the
inside of the
polygon.

233
location array
that defines
the first ring of
the polygon.
getRings getRings() [ Location[] ] Returns an
array of
location
arrays, where
each location
array defines
a ring of the
polygon.
color of the
outline of the
polygon.
string that
represents the
stroke/gap
sequence
used to draw
the outline of
the polygon.
thickness of
the outline of
the polygon.
whether the
polygon is
visible. A
value of false
indicates that
the polygon is
hidden,
although it is
still an entity
on the map.

234
locations that
define a basic
polygon.
setOptions setOptions(options:PolygonOptions) None Sets options
for the
polygon.
setRings setRings(locationArrays:[ Location[]
])
None Sets an array
of location
arrays, where
each location
array defines
a ring of the
polygon.
Polygon object
to a string.

Events

used to click the polygon.
polygon.
of the polygon or any of
the polygons options
change.
the polygon.

235
area covered by the
polygon.
over the polygon.
the polygon.
click the polygon.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

"Bing Maps Key", center: new Microsoft.Maps.Location(47.5, -122.3), zoom: 9 });

236
Microsoft.Maps.loadModule('Microsoft.Maps.AdvancedShapes', { callback:
shapesModuleLoaded });

}

function shapesModuleLoaded()
{
var polygonWithHoles = new Microsoft.Maps.Polygon([

map.entities.push(polygonWithHoles);

}

</script>
</head>

237
</body>
</html>
Microsoft.Maps.Directions API Reference
This section contains reference documentation for the Microsoft.Maps.Directions API, which
contains types that allow you to calculate route directions and display them on your Bing Maps
AJAX Control 7.0 map. Use the calculateDirections method of the DirectionsManager Class to
calculate a route. Sample code can be found at http://www.bingmapsportal.com/isdk/ajaxv7.
Before you can access the types found in the Microsoft.Maps.Directions API, you must
first load this module using the loadModule method. Information about loading modules
is in the Module Loading Methods topic.
In This Section
BusinessDetails Class
BusinessDisambiguationSuggestion Class
DirectionsErrorEventArgs Object
DirectionsEventArgs Object
DirectionsManager Class
DirectionsRenderOptions Object
DirectionsRequestOptions Object
DirectionsStep Class
DirectionsStepEventArgs Object
DirectionsStepRenderEventArgs Object
DirectionsStepWarning Class
Disambiguation Class
DisambiguationRenderEventArgs Object
DistanceUnit Enumeration
IconType Enumeration
LocationDisambiguationSuggestion Class
Maneuver Enumeration
ResetDirectionsOptions Object
Route Class
RouteAvoidance Enumeration
RouteLeg Class
RouteMode Enumeration

238
RouteOptimization Enumeration
RoutePath Class
RouteResponseCode Enumeration
RouteSelectorEventArgs Object
RouteSelectorRenderEventArgs Object
RouteSubLeg Class
RouteSummary Class
RouteSummaryRenderEventArgs Object
StepWarningStyle Enumeration
TimeType Enumeration
TransitLine Class
TransitOptions Object
Waypoint Class
WaypointEventArgs Object
WaypointOptions Object
WaypointRenderEventArgs Object
BusinessDetails Class
Contains business details for a waypoint.
Properties

businessName string The business name of the
waypoint.
entityId string The Bing Maps entity ID of the
business.
phoneNumber string The phone number of the
business.
website string The URL of the business
website.

239
See Also
BusinessDisambiguationSuggestion Class
Contains a possible business result returned from geocoding a specified waypoint address or
location.
Properties

address string The address of the business
result.
distance number The distance of the business
result from the originally
specified waypoint address or
location.
entityId string The Yellow Pages ID for the
business.
index number The index of this suggestion
within the business suggestion
array.
isApproximate boolean A boolean indicating whether
the result location is
approximate.
location Location The location of the business
suggestion.
name string The name of the business.
phoneNumber string The phone number of the
business suggestion.
photoUrl string The URL of a photo of the
rooftopLocation Location The rooftop location of the
website string The URL of the business
results website.

240

Example
<html>
<head>
<title></title>



var map = null;
var directionsManager = null;

function GetMap()
{
map = new
directionsModuleLoaded });

}

function directionsModuleLoaded()
{
// Initialize the DirectionsManager

241
// Create start and end waypoints
var startWaypoint = new Microsoft.Maps.Directions.Waypoint({ address:
"Seattle, WA" });
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address:
"Microsoft" } );

directionsManager.addWaypoint(startWaypoint);
directionsManager.addWaypoint(endWaypoint);

// Set the id of the div to use to display the directions
document.getElementById('itineraryDiv') });

// Specify a handler for when an error occurs
Microsoft.Maps.Events.addHandler(directionsManager, 'directionsError',
displayError);

// Calculate directions, which displays a route on the map

}

function displayError(e)
{
// Display the error message
alert(e.message);

// If the error is a disambiguation error, display the results.
if (e.responseCode ==
Microsoft.Maps.Directions.RouteResponseCode.waypointDisambiguation)
{
DisplayDisambiguation();
}
}

242
function DisplayDisambiguation()
{
var results = "";

var waypoints = directionsManager.getAllWaypoints();

var i = 0;
for (i=0; i<waypoints.length; i++)
{
var disambigResult = waypoints[i].getDisambiguationResult();

if (disambigResult != null)
{
results = results + "Address matches for " + waypoints[i].getAddress()
+ ":\n";

if(disambigResult.businessSuggestions.length != 0)
{
var j = 0;
for (j=0; j<disambigResult.businessSuggestions.length; j++)
{
results = results + disambigResult.businessSuggestions[j].name +
", " + disambigResult.businessSuggestions[j].address + "\n";
}
}
else if (disambigResult.locationSuggestions.length != 0)
{
var k = 0;
for (k=0; k<disambigResult.locationSuggestions.length; k++)
{
results = results +
disambigResult.locationSuggestions[k].suggestion + "\n";
}
}

243
else
{
results = results + disambigResult.headerText + "\n";
}
}
}

alert(results);

}

</script>
</head>
<div id='itineraryDiv' style="position:relative; width:400px;"></div>
</body>
</html>
See Also
DirectionsErrorEventArgs Object
Contains arguments for directions error events.
Properties

responseCode RouteResponseCode The code which identifies
the error that occurred.
message string The error message.

244
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

{
var directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints and add them to the route

245
var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Seattle,
WA"});
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Paris,
France"});


// Set directions render options - in this case, specify the div where the
itinerary is displayed.

// Specify a handler for when the directions are calculated and when an error
occurs
Microsoft.Maps.Events.addHandler(directionsManager, 'directionsUpdated',
displayMessage );
displayError );


}

function displayMessage(e)
{
alert("Route calculation complete!");

}

{
alert( e.message );

246
}

</script>
</head>
</body>
</html>
DirectionsEventArgs Object
Contains the arguments for directions events.
Properties

routeSummary RouteSummary[] The route summary (or
summaries) of the route(s)
defined in the route property.
route Route[] The calculated route (or
routes, if the route mode is
transit).

Example
<html>
<head>
<title></title>

247


var map = null;

function GetMap()
{
map = new

}

{

WA"});
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Bellevue,
WA"});


// Set directions options - in this case, calculate a transit route.
Microsoft.Maps.Directions.RouteMode.transit });

248

// Set directions render options - in this case, specify the div
// where the itinerary is displayed.

// Specify a handler for when the directions are calculated
displayRouteNumber);


}

function displayRouteNumber(e)
{
alert("Number of transit routes available: " + e.route.length);

}

</script>
</head>
</body>
</html>
DirectionsManager Class
Contains methods for calculating directions and displaying a route on a map.

249
Constructor

DirectionsManager DirectionsManager(map:Map) Initializes a new instance of
the DirectionsManager
class.

Methods

addWaypoint addWaypoint(waypoint:Waypoint,
index:number)
None Adds a
waypoint to the
route at the
given index, if
specified. If an
index is not
specified the
waypoint is
added as the
last waypoint in
the route.
To recalculate
the route, use
calculateDirec
tions.
The maximum
number of
walking or
driving
waypoints is
25. The
maximum
number of
transit
waypoints is 2.
Up to 10 via
points are
allowed
between two

250
stop waypoints.
calculateDirecti
ons
calculateDirections() None Calculates
directions
based on
request and
render options
set
(setRequestO
ptions,
setRenderOpti
ons) and the
waypoints
added
(addWaypoint)
. The
directionsUpd
ated event fires
when the
calculation is
complete and
the route is
displayed on
the map.
You must call
this method
after making
any changes to
the route
options or
waypoints.
clearDisplay clearDisplay() None Clears the
directions
displayed and
removes the
route line from
the map. This
method does
not remove
waypoints from
the route and

251
retains all
calculated
direction
information and
option settings.
To clear the
calculated
directions and
options, use
resetDirection
s.
dispose dispose() None Deletes the
DirectionsMan
ager object and
releases any
associated
resources.
getAllWaypoint
s
getAllWaypoints() Waypoint[] Returns the
waypoints for
the route.
getMap getMap() Map Returns the
map object
associated with
the directions
manager.
getNearbyMajor
Roads
getNearbyMajorRoads(location:Locatio
n, callback:function,
errorCallback:function,
userData:object)
None Searches
around the
specified
location for
nearby major
roads and
returns them as
an object to the
callback
function.
getRenderOptio
ns
getRenderOptions() DirectionsRender
Options
Returns the
route render
options.

252
getRequestOpti
ons
getRequestOptions() DirectionsRequest
Options
Returns the
directions
request
options.
getRouteResult getRouteResult() Route[] Returns the
current
calculated
route(s). If the
route was not
successfully
calculated, null
is returned.
removeWaypoi
nt
removeWaypoint(waypoint:Waypoint) or
removeWaypoint(index:number)
None Removes the
given waypoint
or the waypoint
identified by the
given index
from the route.
Use
calculateDirec
tions to update
the route once
a waypoint has
been removed.
resetDirections resetDirections(options:ResetDirectio
nsOptions)
None If no options
object is
supplied, clears
the directions
request and
render options
and removes
all waypoints.
reverseGeocod
e
reverseGeocode(location:Location,
callback:function,
errorCallback:function,
userData:object)
None Matches the
specified
location to an
address and
returns the
address to the
specified

253
callback
function.
setMapView setMapView() None Sets the map
view based on
the current
route index.
setRenderOptio
ns
setRenderOptions(options:DirectionsR
enderOptions)
None Sets the
specified
render options
for the route.
setRequestOpti
ons
setRequestOptions(options:Directions
RequestOptions)
None Sets the
specified route
calculation
options.

Events

afterRouteSelectorRender RouteSelectorRenderEventArgs Occurs after the route
selector has fully rendered.
afterStepRender DirectionsStepRenderEventArgs Occurs after each step in the
itinerary has fully rendered.
afterSummaryRender RouteSummaryRenderEventArg
s
Occurs after the route
summary has fully rendered.
afterWaypointRender WaypointRenderEventArgs Occurs after each route
waypoint has fully rendered.
beforeDisambiguationRende
r
DisambiguationRenderEventArg
s
Occurs before the waypoint
disambiguation element is
rendered. Use the
autoDisplayDisambiguatio
n directions render option to
automatically display
waypoint disambiguation.
beforeRouteSelectorRender RouteSelectorRenderEventArgs Occurs just before the route
selector renders.

254
beforeStepRender DirectionsStepRenderEventArgs Occurs just before each step
in the itinerary renders.
beforeSummaryRender RouteSummaryRenderEventArg
s
Occurs just before the route
summary renders.
beforeWaypointRender WaypointRenderEventArgs Occurs just before each
route waypoint renders.
directionsError DirectionsErrorEventArgs Occurs when calculating the
directions caused an error.
directionsUpdated DirectionsEventArgs Occurs when the directions
calculation was successful
and the itinerary and route
on the map have been
updated.
dragDropCompleted None Occurs when the drag of a
waypoint or route is
completed.
itineraryStepClicked DirectionsStepEventArgs Occurs when a step in the
itinerary is clicked.
mouseEnterRouteSelector RouteSelectorEventArgs Occurs when the mouse
cursor is over the route
selector.
mouseEnterStep DirectionsStepEventArgs Occurs when the mouse
cursor is over a directions
step.
mouseLeaveRouteSelector RouteSelectorEventArgs Occurs when the mouse
cursor leaves the route
selector.
mouseLeaveStep DirectionsStepEventArgs Occurs when the mouse
cursor leaves a directions
step.
routeSelectorClicked RouteSelectorEventArgs Occurs when the route
selector is clicked.
waypointAdded WaypointEventArgs Occurs when a new
waypoint is added to the
route.

255
waypointRemoved WaypointEventArgs Occurs when a waypoint is
removed from the route.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

{

256

WA"});
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Portland,
OR"});



displayError);


}

{
alert(e.message);
}

</script>
</head>

257
</body>
</html>
DirectionsRenderOptions Object
Represents render options for a route.
Properties

autoDisplayDisambiguation boolean A boolean indicating
whether to automatically
display a disambiguation
dialog for waypoints. The
If this value is set to true, a
directionsError event
caused by waypoint
disambiguation is not
thrown.
autoUpdateMapView boolean A boolean indicating
whether to automatically
set the map view to the
best map view of the
calculated route. The
disambiguationPushpinOptions PushpinOptions The options that define the
pushpin to use for
disambiguation.
displayDisclaimer boolean A boolean indicating
whether to display the
disclaimer about the
accuracy of the directions.
The default value is false.
displayManeuverIcons boolean A boolean indicating
icons for each direction

258
maneuver. The default
value is true.
displayPostItineraryItemHints boolean A boolean indicating
whether to display direction
hints that describe when
an direction step was
missed. The default value
is true.
displayPreItineraryItemHints boolean A boolean indicating
hints that describe what to
look for before you come to
the next direction step. The
displayRouteSelector boolean A boolean indicating
route selector control. The
displayStepWarnings boolean A boolean indicating
warnings. The default
value is true.
displayTrafficAvoidanceOption boolean A boolean indicating
control that allows the user
to choose to avoid traffic.
displayWalkingWarning boolean A boolean indicating
whether to display a
warning about walking
directions. The default
value is true.
drivingPolylineOptions PolylineOptions The options that define
how to draw the route line
on the map, if the
RouteMode is driving.
itineraryContainer DOMElement The DOM element inside
which the directions

259
itinerary will be rendered.
lastWaypointIcon string The URL of the icon to use
for the end waypoint.
middleWaypointIcon string The URL of the icon to use
for intermediate waypoints.
stepPushpinOptions PushpinOptions The options that define the
pushpin to use for each
direction step.
transitPolylineOptions PolylineOptions The options that define
on the map, if the
RouteMode is transit.
viapointPushpinsOptions PushpinOptions The options that define the
pushpin to use for each via
point of the route, which
are any waypoints other
than the start and end
waypoints.
walkingPolylineOptions PolylineOptions The options that define
on the map, if the
RouteMode is walking.
waypointPushpinOptions PushpinOptions The options that define the
pushpin to use for the
route waypoint.

Example
<html>
<head>
<title></title>

260


var map = null;

function GetMap()
{
map = new

}

{

WA"});
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: "Green
Lake" } );


// Set request options

261
Microsoft.Maps.Directions.RouteMode.walking });

// Set the render options
document.getElementById('itineraryDiv'), displayWalkingWarning: false,
walkingPolylineOptions:{strokeColor: new Microsoft.Maps.Color(200, 0, 255, 0)} });

displayError);


}

{
alert(e.message);

}

</script>
</head>
</body>

262
</html>
DirectionsRequestOptions Object
Contains options for the directions to calculate.
Properties

avoidTraffic boolean A boolean indicating whether to
return traffic info when calculating
the route. The default value is
false.
distanceUnit DistanceUnit The unit to use when displaying
direction distances. The default
value is based on the specified
culture.
maxRoutes number The number of routes to calculate.
If the routeMode is driving or
walking, only 1 route is supported.
If the routeMode is transit, up to 6
routes can be calculated and the
default is 3.
routeAvoidance RouteAvoidance[] The features to avoid when
calculating the route. The default
value is none.
routeDraggable boolean A boolean indicating whether the
route line on the map can be
dragged with the mouse cursor.
When a route is dragged, a via
point is added to the route.
To change the drag behavior of a
waypoint, set the draggable
property of the
waypointPushpinOptions (of the
DirectionsRenderOptions).

263
routeIndex number If multiple routes are returned, the
index of the route and directions to
display. This property only applies
to routes where the routeMode is
transit, and in this case up to 6
routes are supported.
routeMode RouteMode The type of directions to calculate.
The default value is driving.
When the culture is ja-jp, only the
transit route mode is supported,
which is the default for that
market.
routeOptimization RouteOptimization The optimization setting for the
route calculation. The default
value is shortestTime.
transitOptions TransitOptions The extra options for calculating a
route if the routeMode is transit.

Example
<html>
<head>
<title></title>



var map = null;

264
function GetMap()
{
map = new

}

{

WA"});
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: "Redmond,
WA" } );


directionsManager.setRequestOptions({ avoidTraffic: true, routeOptimization:
Microsoft.Maps.Directions.RouteOptimization.shortestDistance });



265
displayError);


}

{
alert(e.message);

}

</script>
</head>
</body>
</html>
DirectionsStep Class
Represents one direction in a set of route directions.
Properties

childItineraryItems DirectionsStep[] The child direction items for this
directions step.
coordinate Location The location of the start of the

266
direction.
distance string The total distance of the step in
the unit specified in the
distanceUnit property of the
DirectionsRequestOptions.
durationInSeconds number The total time, in seconds, of the
direction step.
formattedText string The HTML formatted route
instruction associated with the
step.
iconType IconType The type of the icon associated
with this step.
isImageRoadShield boolean A boolean indicating whether
the maneuver image is a road
shield image.
maneuver Maneuver The maneuver type associated
with this step.
maneuverImageName string The name of the maneuver
image.
monetaryCost number The cost of the step.
postIntersectionHints string[] An array of strings, where each
string is a hint to help determine
when to move to the next
direction step. Not all direction
steps have hints.
preIntersectionHints string[] An array of strings, where each
string is a hint to help determine
when you have arrived at this
direction step. Not all direction
steps have hints.
startStopName string The name of the transit stop
where this step originates.
transitLine TransitLine The transit line associated with
this step.
transitStepIcon string The URL of the image to use for

267
transit direction steps.
transitStopId string The ID of the transit stop.
transitTerminus string The name of the transit line end.
warnings DirectionsStepWarning[] An array of strings, where each
string is a route warning
associated with this step.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

268

{

WA"});
WA"});


// Set directions options
Microsoft.Maps.Directions.RouteMode.transit});

displayMessage );
Microsoft.Maps.Events.addHandler(directionsManager, 'itineraryStepClicked',
displayStepMessage );
displayError);


269
}

{
alert(e.message);
}

{
alert("Click a step in the itinerary to display extra transit information.");
}

function displayStepMessage(e)
{

if (e.step.iconType == Microsoft.Maps.Directions.IconType.bus )
{
alert("The name of the transit agency for this step is: " +
e.step.transitLine.agencyName + ". For information about this transit agency and transit
line, go to " + e.step.transitLine.agencyUrl + ".");
}
else
{
alert("The step that was clicked is not a transit step.");
}
}

</script>
</head>

270
</body>
</html>
DirectionsStepEventArgs Object
Contains arguments for directions step events.
Properties

the event is handled. Set this
property to true to override
the default behavior.
location Location The location along the route
where the direction step
occurs.
routeIndex number A number indicating the route
(if multiple routes were
returned) to which the
directions step belongs.
routeLegIndex number A number indicating the route
leg to which the directions
step belongs.
step DirectionsStep The directions step.
stepIndex number A number indicating the index
of the directions step within
the route leg array.
stepNumber number A number indicating the
directions step number within
the route.

271
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

{


272
WA"});
WA"});



displayMessage );
displayError);


}

{
alert(e.message);
}

{
alert("Click a step in the itinerary to display extra step information.");

273
}

{
alert("The directions step that was clicked is step number " + (e.stepIndex +
1) + ", and the location of this step is: " + e.location);
}

</script>
</head>
</body>
</html>
DirectionsStepRenderEventArgs Object
Contains arguments for directions step render events.
Properties

containerElement object The DOM element which
contains the directions step.
You can use this property to
add custom content.
the event is handled. This
property is only available for the
beforeStepRender event. Set
this property to true to override
lastStep boolean A boolean indicating whether
the step is the last directions

274
step.
routeIndex number A number indicating the index
of the route to which this step
belongs.
routeLegIndex number A number indicating the index
of the route leg to which this
step belongs.
step DirectionsStep The directions step.
stepIndex number The index of this directions step
within the route leg step array.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

275

}

{

WA"});
WA"});



Microsoft.Maps.Events.addHandler(directionsManager, 'afterStepRender',
displayError);


276
}

{
alert(e.message);
}

{
var message = "A directions step has rendered.";

if (e.lastStep) { message = message + " This is the last itinerary step.";
}

alert(message);
}

</script>
</head>
</body>
</html>
DirectionsStepWarning Class
Represents a route direction warning, such as a traffic congestion warning.
Properties

277
style StepWarningStyle The type of the route warning.
text string The warning text.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}


278
{

WA"});
WA"});


directionsManager.setRequestOptions({ avoidTraffic: true });

displayMessage );
displayError);


}

{
// Variable for counting warnings

279
var warningCount = 0;

for( j=0; j< e.route[0].routeLegs.length; j++)
{

var i = 0;
for (i=0; i < e.route[0].routeLegs[j].itineraryItems.length; i++)
{
if (e.route[0].routeLegs[j].itineraryItems[i].warnings.length != 0 )
{
warningCount = warningCount +
e.route[0].routeLegs[j].itineraryItems[i].warnings.length;
}
}
}

alert("There are " + warningCount + " warning(s) in this route.");
}

{
alert(e.message);
}

</script>
</head>
</body>

280
</html>
Contains disambiguation results for a waypoint geocoding request.
Properties

businessSuggestions BusinessDiambiguationSuggestion[] The possible business
result matches for the
originally specified
waypoint address or
location.
hasMoreSuggestions boolean A boolean indicating
whether there are more
result suggestions
available.
headerText string The disambiguation
header text.
locationSuggestions LocationDiambiguationSuggestion[] The possible location
result matches for the
originally specified
waypoint address or
location.

Example
<html>
<head>
<title></title>

281


var map = null;

function GetMap()
{
map = new

}

{

"Seattle, WA" });
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: "148th
Way Bellevue" } );


282
// Set the id of the div to use to display the directions, and prevent the
default disambiguation dialog from appearing by setting that option
directionsManager.setRenderOptions({autoDisplayDisambiguation:false,
itineraryContainer: document.getElementById('itineraryDiv') });

displayError);


}

{
alert(e.message);

{
}
}

{
var results = "";


var i = 0;

283
{

{
+ ":\n";

{
var j = 0;
{
}
}
{
var k = 0;
{
results = results +
}
}
else
{
}
}
}

284
alert(results);

}

</script>
</head>
</body>
</html>
See Also
Waypoint Class
DisambiguationRenderEventArgs Object
Contains arguments for a beforeDisambiguationRender event.
Properties

containerElement object The DOM element which
contains the disambiguation
list. You can use this property
to add custom content.
property to true to override the
default behavior. If this property
is set to true, a directionsError
event for waypoint
disambiguation is thrown.
waypoint Waypoint The waypoint that needs to be
disambiguated.

285
DistanceUnit Enumeration
Defines the distance unit to use when generating routes and corresponding itineraries.
Constants

Code Name Description
0 kilometers Kilometers are used to measure
route distances.
1 miles Miles are used to measure
route distances.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

286

}

{

WA"});
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: "Redmond,
WA" } );


directionsManager.setRequestOptions({ distanceUnit:
Microsoft.Maps.Directions.DistanceUnit.kilometers, routeOptimization:
Microsoft.Maps.Directions.RouteOptimization.shortestDistance });


displayError);


287

}

{
alert(e.message);

}

</script>
</head>
</body>
</html>
IconType Enumeration
Contains route icon types.
Constants

Type Code Name Description
0 none There is no route icon.
1 other The icon is some other type of
icon.

288
2 auto The icon is a car icon.
3 ferry The icon is a ferry icon.
4 walk The icon is a walking icon.
5 bus The icon is a bus, or transit, icon
6 train The icon is a train icon.
7 airline The icon is an airline icon.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

289
}

{

WA"});
WA"});



displayMessage );
displayError);


290

}

{
alert(e.message);
}

{
}

{

{
}
else
{
}
}

</script>

291
</head>
</body>
</html>
LocationDisambiguationSuggestion Class
Contains a possible result returned from geocoding a specified waypoint address or location.
Properties

formattedSuggestion string The HTML formatted address
suggestion.
location Location The location of the
suggestion.
rooftopLocation Location The rooftop location of the
suggestion.
suggestion string The address suggestion.

Example
<html>
<head>
<title></title>


292

var map = null;

function GetMap()
{
map = new

}

{

"Seattle, WA" });
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: "148th
Way Bellevue" } );



293
displayError);


}

{
alert(e.message);

{
}
}

{
var results = "";


var i = 0;
{


294
{
+ ":\n";

{
var j = 0;
{
}
}
{
var k = 0;
{
results = results +
}
}
else
{
}
}
}

alert(results);

}

</script>

295
</head>
</body>
</html>
See Also
Maneuver Enumeration
Contains route maneuver types.
Constants

0 none The step is not a maneuver.
1 unknown The maneuver is unknown.
2 departStart Depart from the start
waypoint.
3 departIntermediateStop Depart from an intermediate
stop point going in a
different direction and on a
different road than which
you arrived.
4 departIntermediateStopReturning Depart from an intermediate
stop point going back in the
same direction and on the
same road on which you
arrived.
5 arriveFinish Arrive at the end waypoint.
6 arriveIntermediateStop Arrive at an intermediate
stop point.

296
7 turnLeft Turn left.
8 turnRight Turn right.
9 turnBack Turn back sharply.
10 uTurn Make a u-turn to go in the
opposite direction.
11 turnToStayLeft Turn left to stay on the
same road.
12 turnToStayRight Turn right to stay on the
same road.
13 bearLeft Bear left.
14 bearRight Bear right.
15 keepToStayLeft Keep left to stay on the
same road.
16 keepToStayRight Keep right to stay on the
same road.
17 keepToStayStraight Keep straight to stay on the
same road.
18 keepLeft Keep left onto a different
road.
19 keepRight Keep right onto a different
road.
20 keepStraight Keep straight onto a
different road.
21 take Take the road. This
instruction is used when
you are entering or exiting a
ferry.
22 takeRampLeft Take the ramp to the left.
23 takeRampRight Take the ramp to the right.
24 takeRampStraight Stay straight to take the
ramp.
25 keepOnRampLeft Keep left and continue onto

297
ramp.
26 keepOnRampRight Keep right and continue
onto ramp.
27 keepOnRampStraight Keep straight and continue
onto ramp.
28 merge Merge onto highway.
29 continueRoute Continue on the current
road.
30 roadNameChange The road name changed.
31 enterRoundabout Enter a roundabout.
32 exitRoundabout Exit a roundabout.
33 turnRightThenTurnRight Turn right and then turn
right.
34 turnRightThenTurnLeft Turn right and then turn left.
35 turnRightThenBearRight Turn right and then bear
right.
36 turnRightThenBearLeft Turn right and then bear
left.
37 turnLeftThenTurnLeft Turn left and then turn left.
38 turnLeftThenTurnRight Turn left and then turn right.
39 turnLeftThenBearLeft Turn left and then bear left.
40 turnLeftThenBearRight Turn left and then bear
right.
41 bearRightThenTurnRight Bear right and then turn
right.
42 bearRightThenTurnLeft Bear right and then turn left.
43 bearRightThenBearRight Bear right and then bear
right.
44 bearRightThenBearLeft Bear right and then bear
left.
45 bearLeftThenTurnLeft Bear left and then turn left.

298
46 bearLeftThenTurnRight Bear left and then turn right.
47 bearLeftThenBearRight Bear left and then bear
right.
48 bearLeftThenBearLeft Bear left and then bear left.
49 rampThenHighwayRight Take left ramp onto
highway. This is part of a
combined instruction.
50 rampThenHighwayLeft Take right ramp onto
highway. This is part of a
combined instruction.
51 rampToHighwayStraight Stay straight to take the
ramp onto the highway.
This is part of a combined
instruction.
52 enterThenExitRoundabout Enter and exit a
roundabout.
53 bearThenMerge Bear instruction and then a
merge instruction.
54 turnThenMerge Turn instruction and then a
merge instruction.
55 bearThenKeep Bear instruction and then a
keep instruction.
56 transfer Transfer between public
transit lines at a transit stop.
57 wait Wait at a transit stop.
58 takeTransit Take transit.
59 walk The maneuver is a walking
instruction.
60 transitDepart Get on a public transit line
at a transit stop.
61 transitArrive Get off a public transit line
at a transit stop.

299
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

{


300
WA"});
WA"});



displayMessage );
displayError);


}

{
alert(e.message);
}

301
{
alert("Click a transit step in the itinerary to display extra maneuver
information.");
}

{

if (e.step.maneuver == Microsoft.Maps.Directions.Maneuver.transfer )
{
alert("This step is transit transfer instruction.");
}
else if (e.step.maneuver == Microsoft.Maps.Directions.Maneuver.takeTransit )
{
alert("This step is a transit instruction.");
}
else if (e.step.maneuver == Microsoft.Maps.Directions.Maneuver.transitDepart
)
{
alert("This step is a transit departure instruction.");
}
else if (e.step.maneuver == Microsoft.Maps.Directions.Maneuver.transitArrive
)
{
alert("This step is a transit arrival instruction.");
}
else
{
alert("This step is not a transit instruction.");
}

302
}

</script>
</head>
</body>
</html>
ResetDirectionsOptions Object
Contains options for the resetDirections method of the DirectionsManager Class.
Properties

removeAllWaypoints boolean A boolean indicating whether
to remove all of the
waypoints of the route. The
resetRenderOptions boolean A boolean indicating whether
to reset all of the render
options set for the route. The
resetRequestOptions boolean A boolean indicating whether
to reset all of the request
options set for the route. The

303
Route Class
Represents a route.
Properties

routeLegs RouteLeg[] The legs of the route. Each
route leg represents the route
between two waypoints.

RouteAvoidance Enumeration
Defines features to avoid when calculating the route.
Constants

0 none Calculate the best route
using any travel option
available.
1 minimizeLimitedAccessHighway Reduce the use of limited
access highways when
calculating the route.
2 minimizeToll Reduce the use of roads
with tolls when calculating
the route.
4 avoidLimitedAccessHighway Avoid using limited access
highways when calculating
the route.
8 avoidToll Avoid using roads with tolls
when calculating the route.
16 avoidExpressTrain Avoid using express trains
This option only affects

304
routes with a transit
RouteMode that have the
culture set to ja-jp.
32 avoidAirline Avoid using airlines when
calculating the route. This
option only affects routes
with a transit RouteMode
that have the culture set to
ja-jp.
64 avoidBulletTrain Avoid using bullet trains
This option only affects
routes with a transit

RouteLeg Class
Represents a leg of a route. A route leg is the part of the route between two stop waypoints.
Properties

endTime DateTime The end time of the route leg.
This property only applies when
the routeMode of the
DirectionsRequestOptions is set
to transit.
endWaypointLocation Location The location of the last waypoint
of this leg.
itineraryItems DirectionsStep[] The directions steps associated
with this route leg.
originalRouteIndex number The index of the route to which
this route leg belongs.
startTime DateTime The start time of the route leg.

305
This property only applies when
the routeMode of the
DirectionsRequestOptions is set
to transit.
startWaypointLocation Location The location of the first waypoint
of this route leg.
subLegs RouteSubLeg[] The sub legs of this route leg. A
sub leg of a route is the part of
the route between a stop point
and a via point or between two
via points.
summary RouteSummary The summary which describes
this route leg.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

306

}

{

WA"});
WA"});


displayMessage);
displayError);


}

{
alert("The calculated route has " +
e.route[0].routeLegs[0].itineraryItems.length + " direction steps.");

307

}

{
alert("An error has occurred calculating the directions.");
}

</script>
</head>
</body>
</html>
RouteMode Enumeration
Defines the type of route to calculate.
Constants

Name Description
driving Driving directions are calculated.
transit Transit directions are calculated.
walking Walking directions are calculated.

RouteOptimization Enumeration
Defines optimization options for calculating directions.
Constants

308
0 shortestTime Calculate a route the shortest
time.
1 shortestDistance Calculate a route with the
shortest distance.
3 minimizeMoney Minimize the cost when
calculating directions. This
option only affects routes with
a transit RouteMode that
have the culture set to ja-jp.
4 minimizeTransfers Minimize transit transfers
when calculating directions.
This option only affects routes
with a transit RouteMode that
have the culture set to ja-jp.
5 minimizeWalking Minimize the amount of
walking when calculating
directions. This option only
affects routes with a transit

RoutePath Class
Represents the route line shape on the map.
Use the setRenderOptions method of the DirectionsManager Class to set
DirectionsRenderOptions to customize the look of the route line on the map.
Properties

decodedLatitudes double[] An array of latitudes, where
each latitude is the latitude for
one of the locations that
define the route line.

309
decodedLongitudes double[] An array of longitudes, where
each is the longitude value for
one of the locations that
define the route line.
decodedRegions Object[] An array of regions that
define, depending on the
zoom level, how the route line
should be rendered.

RouteResponseCode Enumeration
Contains response codes for a route calculation request.
Constants

Response Code Name Description
0 success The route was successfully
calculated.
1 unknownError An unknown error has occurred.
2 cannotFindNearbyRoad A nearby road cannot be found for
one or more of the route
waypoints.
3 tooFar The distance between two route
waypoints, or the total length of the
route exceeds the limit of the route
mode. Modify the waypoint
locations so that they are closer
together.
4 noSolution A route cannot be calculated for
the specified waypoints. For
example, this code is returned
when a route between Seattle,
WA and Honolulu, HI is
requested.
5 dataSourceNotFound There is no route data for the

310
Response Code Name Description
specified waypoints.
7 noAvailableTransitTrip There are no transit options
available for the specified time.
8 transitStopsTooClose The transit stops are so close that
walking is always a better option.
9 walkingBestAlternative The transit stops are so close that
walking is a better option.
10 outOfTransitBounds There is no transit data available
for the route or for one or more of
the specified waypoints, or the
waypoints are in different transit
areas that do not overlap.
11 timeout The directions calculation request
has timed out.
12 waypointDisambiguation One or more waypoints need to be
disambiguated. This error does not
occur if the
autoDisplayDisambiguation
directions render option is set to
true.
13 hasEmptyWaypoint One or more waypoints do not
have an address or location
specified.
14 exceedMaxWaypointLimit The maximum number of
waypoints, which is 25, has been
exceeded.
15 atleastTwoWaypointRequired At least two waypoints are required
to calculate a route.
16 firstOrLastStoppointIsVia The first or last waypoint is a via
point, which is not allowed.
17 searchServiceFailed The search service failed to return
results.
18 invalidCredentials The credentials passed to the
Directions module are invalid.

311
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

{


312
var waypoint1 = new Microsoft.Maps.Directions.Waypoint({address:"Seattle,
WA"});
var waypoint2 = new Microsoft.Maps.Directions.Waypoint({ address: "Redmond,
WA"});
var waypoint3 = new Microsoft.Maps.Directions.Waypoint({ address: "Bellevue,
WA", isViapoint: true } );

directionsManager.addWaypoint(waypoint1);


displayError);


}

{
alert(e.message);

// If the error is a viapoint error, display an error
Microsoft.Maps.Directions.RouteResponseCode.firstOrLastStoppointIsVia )
{
alert("Please remove the 'isViapoint' option from your first or last stop
point.");

313
}
}

</script>
</head>
</body>
</html>
RouteSelectorEventArgs Object
Contains arguments for route selector events.
Properties

property to true to override the
default behavior.
routeIndex number A number indicating the index
of the route that was selected.

RouteSelectorRenderEventArgs Object
Contains arguments for route selector render events.
Properties

containerElement object The DOM element which contains
the route selector. You can use this

314
property to add custom content.
handled boolean A boolean indicating whether the
event is handled. This property is
only available for the
beforeRouteSelectorRender event.
Set this property to true to override
routeIndex number A number indicating the index of the
selected route.
routeLeg RouteLeg The route leg of the selected route.

RouteSubLeg Class
Represents a route sub leg. A route sub leg is the part of the route between a stop point and a via
point or between two via points. One or more sub legs make up a route leg.
Properties

actualEnd Location The location of the last
waypoint of the sub leg.
actualStart Location The location of the first
endDescription string The description of the last
routePath RoutePath The properties that define
the route line of this sub leg
on the map.
startDescription string The description of the first
summary RouteSummary The summary of this route
sub leg.

315
RouteSummary Class
Represents a route summary.
Properties

distance double The total travel distance of the
route, specified in the units set in
the distanceUnit property of the
DirectionsRequestOptions.
monetaryCost double The cost of the route. This property
is only returned if the routeMode of
the DirectionsRequestOptions is set
to transit and the map culture is set
to ja-jp.
northEast Location The location of the northeast corner
of bounding box that defines the
best map view of the route.
southWest Location The location of the southwest corner
of bounding box that defines the
best map view of the route.
time number The total travel time, in seconds, for
the route.
timeWithTraffic number The total travel time, in seconds,
taking into account traffic delays, for
the route. This property is 0 if the
avoidTraffic property of the
DirectionsRequestOptions is set to
false.

Example
<html>
<head>

316
<title></title>



var map = null;

function GetMap()
{
map = new

}

{

WA"});
WA"});


317

// Set directions render options - in this case, specify the div where the
itinerary is displayed.

displayDistanceAndTime );


}

function displayDistanceAndTime(e)
{
alert("Total Distance: " + e.routeSummary[0].distance + " miles\n" + "Total
Time: " + e.routeSummary[0].time/60 + " minutes" );

}

</script>
</head>
</body>
</html>

318
RouteSummaryRenderEventArgs Object
Contains arguments for route summary render events.
Properties

the summary. You can use this
beforeSummaryRender event.
Set this property to true to
override the default behavior.
routeLegIndex number A number indicating the index of
the route leg which this summary
describes.
summary RouteSummary The summary that was rendered.

StepWarningStyle Enumeration
Contains types of route direction warnings.
Constants

0 info The warning is just information
about the route direction.
1 minor The warning is a minor
warning, and may affect the
route direction.
2 moderate The warning is a moderate
warning and is likely to affect

319
the route direction.
3 major The warning is a major
warning, and is highly likely to
affect the route direction.
4 ccZoneEnter The warning indicates a
congestion zone is being
entered.
5 ccZoneExit The warning indicates a
congestion zone is being
exited.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

320

}

{

WA"});
WA"});


directionsManager.setRequestOptions({ avoidTraffic: true });

displayMessage );
displayError);


321

}

{
// Variable for counting warnings
var warningCount = 0;

for( j=0; j< e.route[0].routeLegs.length; j++)
{

var i = 0;
for (i=0; i < e.route[0].routeLegs[j].itineraryItems.length; i++)
{
if (e.route[0].routeLegs[j].itineraryItems[i].warnings.length != 0 )
{
warningCount = warningCount +
e.route[0].routeLegs[j].itineraryItems[i].warnings.length;

for (k=0; k<
e.route[0].routeLegs[j].itineraryItems[i].warnings.length; k++)
{
if (e.route[0].routeLegs[j].itineraryItems[i].warnings[k].style
== Microsoft.Maps.Directions.StepWarningStyle.major)
{
alert("Alert! There is a major warning in this route.");
}
}
}
}
}

322
alert("There are " + warningCount + " warning(s) in this route.");
}

{
alert(e.message);
}

</script>
</head>
</body>
</html>
TimeType Enumeration
Defines the transit time type.
Constants

Name Description
arrival The time specified is an arrival time.
departure The time specified is a departure time.
lastAvailable The time specified is the last available time.
This time type is only returned for routes with a
transit RouteMode that have the culture set to
ja-jp.

323
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

{


324
WA"});
WA"});


// Set arrival time to be 4 hours from now
var timeToDepart = new Date();
timeToDepart.setTime(timeToDepart.getTime() + 14400000);

Microsoft.Maps.Directions.RouteMode.transit, transitOptions:{ transitTime: timeToDepart,
timeType: Microsoft.Maps.Directions.TimeType.arrival } });

displayError);


}

{
alert(e.message);
}

325

</script>
</head>
</body>
</html>
See Also
TransitLine Class
Contains information about a transit line.
Properties

abbreviatedName string The short name for the transit
line.
agencyId number The ID of the agency that
owns the transit line.
agencyName string The name of the agency that
owns the transit line.
agencyUrl string The URL of the website of the
agency that owns the transit
line.
lineColor Color The color to use when
rendering this transit line on
the map.
lineTextColor Color The color to use when
rendering text associated with
this transit line.

326
providerInfo string Information about the provider
of this transit line data.
verboseName string The full name of this transit
line.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new

}

327

{

WA"});
WA"});



displayMessage );
displayError);


}

328

{
alert(e.message);
}

{
}

{

{
}
else
{
}
}

</script>
</head>

329
</body>
</html>
Contains extra options for transit routes.
Properties

timeType TimeType The type of the time specified
in transitTime. The default
value is departure.
transitTime Date The transit time to use when
calculating the route. If this
property is set to null, the
current time is used.

Example
<html>
<head>
<title></title>



var map = null;

330

function GetMap()
{
map = new

}

{

WA"});
WA"});


// Set departure time to be 4 hours from now
var timeToDepart = new Date();
timeToDepart.setTime(timeToDepart.getTime() + 14400000);

Microsoft.Maps.Directions.RouteMode.transit, transitOptions:{ transitTime: timeToDepart }
});

331

displayError);


}

{
alert(e.message);
}

</script>
</head>
</body>
</html>
Waypoint Class
Represents a route waypoint.
Constructor

332
Waypoint Waypoint(options:WaypointOptions) Initializes a new instance
of the Waypoint class.

Methods

clear clear() None Clears all
options
associated
with this
waypoint.
dispose dispose() None Releases any
resources
associated
with the
waypoint.
getAddress getAddress() string Returns the
address
associated
with the
waypoint.
getBusinessDetails getBusinessDetails() BusinessDetai
ls
Returns the
business
details
associated
with the
waypoint.
getDisambiguationContai
ner
getDisambiguationContainer() DOMElement Returns the
container
element for
the waypoint
disambiguatio
n list.
getDisambiguationResult getDisambiguationResult() Disambiguatio
n
Returns the
result of the
waypoint
geocoding

333
disambiguatio
n.
getLocation getLocation() Location Returns the
location of the
waypoint.
getPushpin getPushpin() Pushpin Returns the
custom
pushpin
associated
with this
waypoint, if
one has been
specified.
getShortAddress getShortAddress() string Returns the
short address
for the
waypoint.
isExactLocation isExactLocation() boolean Returns a
boolean
indicating
whether the
waypoint
location is the
exact
location.
isViapoint isViapoint() boolean Returns a
boolean value
indicating
whether the
waypoint is a
via point. A
via point is a
location that
your route is
guaranteed to
pass through.
There can be
multiple via
points

334
between two
stop points.
setOptions setOptions(options:WaypointOpti
ons)
None Sets options
for the
waypoint. For
these options
to take effect,
you must
recalculate
the route.

Events

changed WaypointEventArgs Occurs when the any
properties of the waypoint
change or are updated.
geocoded WaypointEventArgs Occurs when a geocoding
request for the waypoints
address is made.
reverseGeocoded WaypointEventArgs Occurs when a reverse
geocoding request for the
waypoints location is made.
This happens when no
address is provided for the
waypoint, or if the waypoint
is dragged (in which case
its location is changed).

Example
<html>
<head>
<title></title>

335



var map = null;

function GetMap()
{
map = new

}

{

WA"});
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address:
"Microsoft" } );


336


displayError);


}

{
alert(e.message);

{
SelectFirstDisambiguationResult();
}

}

function SelectFirstDisambiguationResult()
{

337
var results = "";


var recalculate = false;

var i = 0;
{


{
// Reset the address to the first business or location suggestion
var firstAddress = disambigResult.businessSuggestions.length > 0 ?
disambigResult.businessSuggestions[0].address :
disambigResult.locationSuggestions[0].suggestion;
waypoints[i].setOptions({ address: firstAddress });

// Set the recalculate flag since the waypoint address was changed
recalculate = true;
}
}

if (recalculate)
{
}
}

</script>

338
</head>
</body>
</html>
WaypointEventArgs Object
Contains the arguments for route waypoint events.
Properties

waypoint Waypoint The waypoint for which the
event occurred.

WaypointOptions Object
Contains waypoint options.
Properties

address string The address string, business
name, or search string of the
waypoint. For example, the
following strings are valid for this
parameter: Seattle, Microsoft,
pizza, or pizza Seattle. Either
the address or location
property must be specified.
businessDetails BusinessDetails The business details of the
waypoint, if it is a business.

339
disambiguationContainer DOMElement The DOM element inside which
the waypoint disambiguation list
will be rendered. If this property
is not set, the disambiguation list
is rendered inside the
itineraryContainer.
exactLocation boolean A boolean indicating whether the
waypoint location is the exact
location. The default value is
false.
isViapoint boolean A boolean indicating whether the
waypoint is a via point. A via
point is a point along the route
that is not a stop point. Set this
property to true if you just want
the route to pass through this
location. The default value is
false.
location Location The location of the waypoint.
Either the address or location
property must be specified.
pushpin Pushpin The custom pushpin to use to
represent this waypoint. This
property overrides any pushpin
options that apply to this
waypoint that have been set in
the DirectionsRenderOptions
Object.
shortAddress string The short address of the
waypoint.

Example
<html>
<head>

340
<title></title>



var map = null;

function GetMap()
{
map = new

}

{

var startWaypoint = new Microsoft.Maps.Directions.Waypoint({ location: new
Microsoft.Maps.Location(47.5, -121.9) });
var viaWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: "1
Microsoft Way, Redmond, WA" , isViapoint: true });
var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address:"Space
Needle" } );

341

directionsManager.addWaypoint(viaWaypoint);


// Specify a handler for when an error and success occurs
displayError);


}

{
alert(e.message);

}

</script>
</head>
</body>
</html>

342
WaypointRenderEventArgs Object
Contains arguments for waypoint render events.
Properties

the waypoint. You can use this
beforeWaypointRender event.
Set this property to true to override
waypoint Waypoint The waypoint for which the event
occurred.

Microsoft.Maps.Overlays.Style Reference
This section contains reference documentation for the Microsoft.Maps.Overlays.Style module,
which allows you to access Bing Maps overlay styles.
Before you can access Microsoft.Maps.Overlays.Style styles, you must first load this
module using the loadModule method. Information about loading modules is in the
Module Loading Methods topic.
Navigation Bar Style
To load the new Bing Maps navigation bar, load the Microsoft.Maps.Overlays.Style module, then
set the customizeOverlays map option to true.
<html>
<head>

343
<title></title>



var map = null;

Microsoft.Maps.loadModule('Microsoft.Maps.Overlays.Style', { callback: GetMap });

function GetMap()
{

var options = {credentials: "Bing Maps Key", center: new
Microsoft.Maps.Location(47.5, -122.3), zoom: 9, customizeOverlays: true }

map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), options );

}

</script>
</head>
<body>
</body>
</html>
Microsoft.Maps.Search API Reference
This section contains reference documentation for the Microsoft.Maps.Search API, which
contains types that allow you to return search and location results to display on your Bing Maps

344
AJAX Control 7.0 map. Use the methods geocode, reverseGeocode, and search found on the
SearchManager Class.
Before you can access the types found in the Microsoft.Maps.Search API, you must first
load this module using the loadModule method. Information about loading modules is in
the Module Loading Methods topic.
In This Section
Address Class
GeocodeLocation Class
GeocodeRequestOptions Object
GeocodeResult Class
LocationPrecision Enumeration
MatchCode Enumeration
MatchConfidence Enumeration
PlaceResult Class
ReverseGeocodeRequestOptions Object
SearchManager Class
SearchParseResult Class
SearchRegion Class
SearchRequestOptions Object
SearchResponse Class
SearchResponseSummary Class
SearchResult Class
Address Class (AJAX)
Represents an address.
Properties

addressLine string The street line of an address.
The addressLine property is
the most precise, official line for
an address relative to the
postal agency servicing the

345
area specified by the locality or
postalCode properties.
adminDistrict string The subdivision name within
the country or region for an
address. This element is also
commonly treated as the first
order administrative
subdivision. An example is a
US state, such as Oregon.
countryRegion string The country or region name of
the address.
district string The second, third, or fourth
order subdivision within a
country, dependency, or
region.
formattedAddress string The complete, unparsed
address.
locality string The locality, such as the
primary city, that corresponds
to an address. An example is
Seattle.
postalCode string The post code, postal code, or
ZIP code of an address. An
example is a US ZIP code,
such as 98152.
postalTown string The city or neighborhood that
corresponds to the postalCode.

GeocodeLocation Class (AJAX)
Represents a geocode location.
Properties

346
location Location The map location of this
geocode location match.
name string The name of this geocode
location match.
precision LocationPrecision The precision of this geocode
location match.

GeocodeRequestOptions Object
Contains the options for a geocode request.
Properties

bounds LocationRect A location rectangle that defines
the boundaries of the area in which
to search for location results. The
default is the bounds of the map
view associated with this instance
of the SearchManager, which is
usually the current map view.
callback function The name of the function to call
when a successful result is
returned from the geocode request.
The callback function must accept
two parameters: result, which is a
GeocodeResult type, and a
userData object.
count number The maximum number of results to
return. Required. The maximum
number than can be returned is 20.
errorCallback function The name of the function to call
when the request is returned with
an error. The error callback
function must accept a

347
GeocodeRequestOptions object.
timeout number A number indicating how long to
wait, in seconds, for the geocode
request to return. The default value
is 5 seconds.
userData Object An object containing any data that
needs to be passed to the callback
when the request is completed.
where string A string containing the address or
place to be matched to a location
on the map. Required.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{


348
searchModuleLoaded });

}

function searchModuleLoaded()
{
var searchManager = new Microsoft.Maps.Search.SearchManager(map);

var geocodeRequest = {where:"1 Microsoft Way, Redmond, WA", count:10,
callback:geocodeCallback, errorCallback:errCallback};
searchManager.geocode(geocodeRequest);
}

function geocodeCallback(geocodeResult, userData)
{
alert("The first geocode result is " + geocodeResult.results[0].name + ".");
}

function errCallback(geocodeRequest)
{

alert("An error occurred.");
}

</script>
</head>
</body>
</html>

349
See Also
SearchManager Class
GeocodeResult Class (AJAX)
Represents a geocoded result.
Properties

parsedAddress Address The parsed address of the
input query.
parsedKeyword string The parsed keyword string of
the input query.
parsedSeparator string The parsed separator of the
input query.
results PlaceResult[] The geocoded results.

LocationPrecision Enumeration
Defines the match precision of a geocoded result.
Constants

Name Description
interpolated The geocoding service matched the location to
a point on the road using interpolation of
multiple geocoded sources.
rooftop The geocoding service matched the location to
the rooftop of a building.

350
MatchCode Enumeration
Defines the geocoding level of the location match found by the geocoder.
Constants

Name Description
none No match was found.
good The match was good.
ambiguous The match was ambiguous. Multiple results
were returned.
upHierarchy The match was found by a broader search.
modified The match was found, but possibly using a
modified query.

MatchConfidence Enumeration
Defines the confidence of the location match found by the geocoding service.
Constants

Name Description
high The confidence of the match is high.
medium The confidence of the match is medium.
low The confidence of the match is low.
unknown The confidence of the match is unknown.

PlaceResult Class
Represents a place result.

351
Properties

bestView LocationRect The location rectangle that
defines the boundaries of
the best map view of the
place result.
location GeocodeLocation The geocoded location of
the best result.
locations GeocodeLocation[] The geocoded locations.
matchCode MatchCode The match code of the best
result.
matchConfidence MatchConfidence The match confidence of
the best result.
name string The name of the place
result, if one exists.

ReverseGeocodeRequestOptions Object
Contains options for a reverse geocode request.
Properties

callback function The name of the function to call when a
successful result is returned from the
reverse geocode request. The callback
function must accept two parameters: a
result, which is a PlaceResult type, and
a userData object.
errorCallback function The name of the function to call when
the request is returned with an error.
The callback function must accept a
ReverseGeocodeRequestOptions
object.

352
location Location The location to use to match to
geographic entities and addresses.
timeout number A number indicating how long to wait,
in seconds, for the reverse geocode
request to return. The default value is 5
seconds.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{



353

}

{

var reverseGeocodeRequest = {location:new Microsoft.Maps.Location(47.5, -121.5),
count:10, callback:reverseGeocodeCallback, errorCallback:errCallback};
searchManager.reverseGeocode(reverseGeocodeRequest);
}

function reverseGeocodeCallback(result, userData)
{
alert("The first result is " + result.name + ".");
}

function errCallback(request)
{

}

</script>
</head>
</body>
</html>
See Also
SearchManager Class

354
SearchManager Class
Contains methods for returning search and location results.
Constructor

SearchManager SearchManager(map:Map) Initializes a new instance of
the SearchManager class.

Methods

n
Value
Descriptio
n
geocode geocode(request:GeocodeRequestOptions Object) None Matches
the
address or
place
query in
the
specified
request
options to
a location
and
returns the
results to
the
request
options
callback
function.
reverseGeocod
e
reverseGeocode(request:ReverseGeocodeRequestOptio
ns Object)
None Matches
the
specified
location to
an

355
n
Value
Descriptio
n
address
and
returns the
address
results to
the
specified
request
options
callback
function.
search search(request:SearchRequestOptions Object) None Performs
a search
based on
the
specified
request
options
and
returns the
results to
the
request
options
callback
function.

Example
<html>
<head>
<title></title>

356


var map = null;

function GetMap()
{



}

{

var searchRequest = {query:"pizza in Seattle, WA", count: 5,
callback:searchCallback, errorCallback:searchError};
searchManager.search(searchRequest);
}

function searchCallback(searchResponse, userData)
{
alert("The first search result is " + searchResponse.searchResults[0].name +
".");
}

357
function searchError(searchRequest)
{
}

</script>
</head>
</body>
</html>
SearchParseResult Class
Represents a search request parse result.
Properties

keyword string The keyword of the input
query string.
location GeocodeLocation The geocoded location of
the input query string.
matchConfidence MatchConfidence The confidence of the
geocode match.

SearchRegion Class (AJAX)
Represents a search area.
Properties

358
address Address The address of the center of
the search region.
geocodeLocations GeocodeLocation[] The geocoded locations.
explicitLocation GeocodeLocation The best geocoded
location.
mapBounds LocationRect A location rectangle that
defines the boundaries of
the search area.
matchCode MatchCode The match code of the
geocoded location.
matchConfidence MatchConfidence The match confidence of
the geocoded location.
source string A string indicating the
region used to infer the
location. The current values
are Query or MapView.

SearchRequestOptions Object
Contains options for a search request.
Properties

callback function The name of the function to call
when a successful result is
returned from the search request.
The callback function must accept
two parameters: a result, which is
a SearchResponse, and a
userData object.
count number The maximum number of results to
return. Required. The maximum
number than can be returned is 20.

359
errorCallback function The name of the function to call
when the request is returned with
an error. The callback function
must accept a
SearchRequestOptions object.
query string The search string, such as pizza
in Seattle, WA. Either query or
what/where needs to be specified.
If both are specified, an error
occurs.
startIndex number The index of the first result in the
results. For example, if you had
already returned a first set of 10
search results and now wanted to
return the second set of 10 results,
you would specify 10 as the
startIndex and 10 as the count.
timeout number A number indicating how long to
wait, in seconds, for the search
request to return. The default value
is 5 seconds.
entityType string The type of entities to find.
Currently only Business is
allowed.
what string The business name, category, or
other item for which the search is
conducted. For example, pizza in
the search string pizza in Seattle.
where string The address or place name of the
area for which the search is
conducted. For example, Seattle
in the search string pizza in
Seattle.

360
Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{



}

{

var searchRequest = {what:"pizza", where:"Seattle", count:10,
callback:searchCallback, errorCallback:searchError};
searchManager.search(searchRequest);

361
}

function searchCallback(searchResponse, userData)
{
alert("The first search result is " + searchResponse.searchResults[0].name +
".");
}

function searchError(searchRequest)
{
}

</script>
</head>
</body>
</html>
See Also
SearchManager Class
SearchResponse Class (AJAX)
Represents the results of a search request.
Properties

alternateSearchRegions SearchRegion[] An array of alternate
search regions.
hasMore boolean A boolean indicating

362
whether there are more
results to return.
parseResults SearchParseResult[] An array containing the
parsed results of the
search.
responseSummary SearchResponseSummary The summary of the
response to the search
request.
searchRegion SearchRegion The region in which the
search was performed.
searchResults SearchResult[] A search result array
containing the search
results.

See Also
SearchManager Class
SearchResponseSummary Class
Contains properties that summarize the search service response to a request.
Properties

authResultCode number The authentication result code.
copyright string The copyright string.
errorMessage string The error message, if an error
occurred.
statusCode number The status code of the request.
traceId number A string representing a trace ID
to enable debugging of the
request.

363
SearchResult Class
Represents a distinct search result.
Properties

address Address The address of the search
result.
city string The city of the search result.
country string The country of the search
result.
entityType string The entity type of the search
result.
hoursOfOperation string The hours of operation of the
entity defined by the search
result.
id number The entity ID of the search
result.
location Location The location of the search
result.
name string The name of the entity
defined by the search result.
phone string The phone number of the
search result.
postalCode string The postal code of the search
result.
reviewCount number The number of user reviews
recorded for this search
result.
userRating number The average user rating for
the entity defined by the
search result.
website string The URL of the entity defined
by the search result.

364
Microsoft.Maps.Themes.BingTheme API
Reference
This section contains reference documentation for the Microsoft.Maps.Themes.BingTheme
module, which allows you to use the latest Bing Maps site design.
Before you can access the Microsoft.Maps.Themes.BingTheme functionality, you must
BingTheme Features
When loaded, the Microsoft.Maps.Themes.BingTheme module updates certain visual aspects of
the map control with the latest Bing Maps design. To see the design changes, simply access the
corresponding API after loading the Microsoft.Maps.Themes.BingTheme module. The affected
map control features are listed below.
Map navigation bar The style, position, and size of the map navigation bar elements is
updated, including the map style drop-down, zoom, pan, and rotate controls.
Location bar The style, position, and size of the location bar, which describes the map
context (such as World), is updated.
Pushpins The style and behavior of pushpins are updated to match the Bing Maps site. This
includes the ability to associate a pushpin with an info box, pushpin hover and click behavior,
and pushpin color changes based on the current imagery. Also, a new pinmicro value is
available for the pushpin typeName option. For pushpin options you can set, see
PushpinOptions.
Polygons The style and behavior of polygons changes to match the latest Bing Maps
design. This includes providing info boxes for hover and click events.
Info boxes The style and behavior of info boxes are updated to match the Bing Maps site.
This includes the ability to associate an info box with a pushpin, info box styles for hover and
click events, and info box color changes based on the current imagery. For info box options
you can set, see InfoboxOptions.
Example
<html>
<head>
<title></title>

365



var map = null;

function GetMap()
{


}

{
// Load the map using the Bing theme style.
"Bing Maps Key", center: new Microsoft.Maps.Location(47.5, -122.3), zoom: 9, theme: new
Microsoft.Maps.Themes.BingTheme() });

}

</script>
</head>
</body>
</html>

366

Additional Example: For an example of how to set pushpin options for a pushpin when using the
Microsoft.Maps.Themes.BingTheme, see the example in EntityState Enumeration.
Microsoft.Maps.Traffic API Reference
This section contains reference documentation for the Microsoft.Maps.Traffic API, which contains
types that allow you to display traffic on your Bing Maps AJAX Control 7.0 map.
Before you can access the types found in the Microsoft.Maps.Traffic API, you must first
load this module using the loadModule method. Information about loading modules is in
the Module Loading Methods topic.
In This Section
TrafficLayer Class (deprecated)
TrafficManager Class
TrafficLayer Class (deprecated)
This class is deprecated. Use the TrafficManager Class.
Represents a traffic layer on the map.
Constructor

TrafficLayer TrafficLayer(map:Map) Initializes a new instance of
the TrafficLayer class.

Methods

getTileLayer getTileLayer() TileLayer Returns the traffic
layer.
hide hide() None Hides the traffic layer.

367
show show() None Displays the traffic
layer.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{



}

{

368
var trafficLayer = new Microsoft.Maps.Traffic.TrafficLayer(map);
trafficLayer.show();
}

</script>
</head>
</body>
</html>
TrafficManager Class
Contains methods that display traffic information on the map.
Constructor

TrafficManager TrafficManager(map: Map) Initializes a new instance of
the TrafficManager class.

Methods

hide hide() None Hides all traffic data.
hideFlow hideFlow() None Hides the traffic flow
layer.
hideIncidents hideIncidents() None Hides all traffic
incidents.
hideLegend hideLengend() None Hides the traffic
legend.

369
show show() None Displays all traffic
data.
showFlow showFlow() None Displays the traffic
flow layer.
showIncidents showIncidents() None Displays all traffic
incidents.
showLegend showLengend() None Displays the traffic
legend.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

Bing Maps
Key", center: new
Microsoft.Maps.Location(47.5, -122.3), zoom: 9 });

370

}

{
}

</script>
</head>
</body>
</html>
Microsoft.Maps.VenueMaps API Reference
This section contains reference documentation for the Microsoft.Maps.VenueMaps API. Use the
VenueMapFactory Class to search for available venue maps.
Before you can access the types found in the Microsoft.Maps.VenueMaps API, you must
In This Section
Directory Class
DirectoryGrouping Enumeration
DirectorySortOrder Enumeration
Floor Class

371
Footprint Class
Metadata Class
NearbyVenue Class
NearbyVenueOptions Object
Polygon Class
Primitive Class
VenueMap Class
VenueMapCreationOptions Object
VenueMapFactory Class
Directory Class
Represents a venue map directory, which is a list of businesses and features found within the
venue.
Methods

Value
Description
addToDOM addToDom(div:HTMLElement,
sortOrder:DirectorySortOrder,
to_group_or_not:DirectoryGrouping)
None Adds the venue
map directory to
the DOM
(document
object model).
The specified
div becomes the
parent element
of the venue
map directory.
This method
does nothing if
the
createUIElemen
ts is not called
first.
createUIElement
s
createUIElements() None Creates the
necessary UI
elements and
data structures

372
Value
Description
to visualize the
venue map
directory. After
this method is
called, use the
addToDOM
method to add
the elements to
the DOM.
handleMouseCli
ck
handleMouseClick(e:{eventArgs:MouseEventArg
s, Primitive})
None The base
method to call if
you override the
click event.
handleMouseOu
t
handleMouseMouseOut(e:{eventArgs:MouseEvent
Args, Primitive})
None The base
method to call if
you override the
mouseout
event.
handleMouseOv
er
handleMouseOver(e:{eventArgs:MouseEventArgs
, Primitive})
None The base
method to call if
you override the
mouseover
event.
isInDOM isInDOM() boolea
n
Returns a
boolean
indicating
whether the
venue map
directory is in the
DOM.
removeFromDO
M
removeFromDOM() None Removes the
venue map
directory from
the DOM. It is
recommended
that you use this
method to
remove the

373
Value
Description
venue map
directory from
the DOM instead
of using the
removeChild
method of the
DOM.
setHeight setHeight(h:int or double) None Sets the height
of the venue
map directory,
as a percentage
of the base
maps height or
in absolute
pixels. For
example, to set
the directory as
90% of the base
maps height,
call
setHeight(.9).
To set the height
as 800 pixels,
call
setHeight(800).

Events

click eventArgs:MouseEventArgs,
Primitive
Occurs when the mouse is
used to click a list item in
the directory. If no handler
is specified for this event,
then the list item is
selected.
mouseout eventArgs:MouseEventArgs,
Primitive
Occurs when the mouse

374
area covered by a list item
in the directory. If no
handler is specified for this
event, then the highlight is
removed from the directory
list item.
mouseover eventArgs:MouseEventArgs,
Primitive
Occurs when the mouse is
over a list item in the
directory. If no handler is
specified for this event,
then the list item is
highlighted.

Example
<html>
<head>
<title></title>
var map = null;
var venue = null;
var Events = null;
var clickhandler = null;
var mouseoverhandler = null;
var mouseouthandler = null;

function GetMap()
{

375
map = new
Events = Microsoft.Maps.Events;
Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback:
venuemapsModuleLoaded });
}

function venuemapsModuleLoaded()
{
// Create the venue map
var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);
vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare',
success:successCallback});
}

function successCallback(venueObj)
{
venue = venueObj;
map.setView(venue.bestMapView, true);
venue.show();
venue.directory.createUIElements();
addDirectory();
}

function addDirectory()
{
if (venue && venue.directory && !venue.directory.isInDOM())
{
var directory = venue.directory;
directory.addToDOM(document.getElementById('leftsidebar'),
Microsoft.Maps.VenueMaps.DirectorySortOrder.alphabetical,
Microsoft.Maps.VenueMaps.DirectoryGrouping.none);
directory.setHeight(1.0);
clickhandler = Events.addHandler(directory, 'click', clickHandler);
mouseoverhandler = Events.addHandler(directory, 'mouseover', mouseoverHandler);

376
mouseouthandler = Events.addHandler(directory, 'mouseout', mouseoutHandler);
}
}

function removeDirectory()
{
if (venue)
{
venue.directory.removeFromDOM();
Events.removeHandler(clickHandler);
Events.removeHandler(mouseoverHandler);
Events.removeHandler(mouseoutHandler);
}
}

function clickHandler(e)
{
var p = e.primitive;
venue.directory.handleMouseClick(e);// call base method
display('Clicked Store <br/>' +
'Name : ' + p.name + '<br/>' +
'Id: ' + p.id+ '<br/>' +
'YPId : ' + p.businessId + '<br/>' +
'Category Name : ' + p.categoryName + '<br/>' +
'Category Id : ' + p.categoryId + '<br/>' +
'Optimal Zoom: ' + p.optimalZoom(0.8) + '<br/>' +
'Floor: ' + p.floor.name + '<br/>' +
'Center : ' + p.center + '<br/>' +
'Coordinates : ' + p.locations + '<br/>' +
'Bounding Box: ' + p.bounds);
}

function mouseoverHandler(e)
{

377
venue.directory.handleMouseOver(e);// call base method
display('Mouse Over <br/>' +
'Name : ' + p.name + '<br/>' +
'Id: ' + p.id+ '<br/>' +
}

function mouseoutHandler(e)
{
venue.directory.handleMouseOut(e);// call base method
display('Mouse Out <br/>' +
'Name : ' + p.name + '<br/>' +
'Id: ' + p.id+ '<br/>' +
}

function display(html)
{

378
var e = document.getElementById('rightsidebar');
e.innerHTML = html;
}

</script>
</head>
<div id='leftsidebar' style="position:absolute; top:0px; left:0px; width:300px;"></div>
<div id='mapDiv' style="position:absolute; top:0px; left:310px; width:500px;
<div id='rightsidebar' style="position:absolute; top:0px; left:820px; width:300px;
<input style="position:absolute; top:520px; left:310px" type='button'
onclick='addDirectory();' value='Add Directory' />
<input style="position:absolute; top:520px; left:470px" type='button'
onclick='removeDirectory();' value='Remove Directory' />
</body>
</html>
DirectoryGrouping Enumeration
Contains constants that specify how listings in a venue map directory are grouped.
Constants

Name Description
byCategory The listings in the directory are grouped by
category.
none The listings in the directory are not grouped.
They are displayed in a flat list.

DirectorySortOrder Enumeration
Contains constants that specify the way a venue map directory is sorted.

379
Constants

Name Description
alphabetical The listings in the directory are sorted
alphabetically.
byFloor The listings in the directory are sorted by floor.

Floor Class
Represents one floor map of a venue map.
Properties

name string The name of the floor.
primitives Primitive[] An array of Primitive objects
that represent the points of
interest (for example, stores)
on this venue floor.
zoomRange double[] An array of doubles indicating
the minimum and maximum
zoom levels where imagery is
available for this venue map
floor.

Example
<html>
<head>
<title></title>

380


var map = null;

function GetMap()
{
map = new


}

{


vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:ShowVenue,
error:ShowError});

}

function ShowVenue(venue)
{
// Set the map view
map.setView(venue.bestMapView);

381
venue.show();

DisplayVenueFloorInfo(venue);

}

function ShowError()
{
// Show an error
alert("An error occurred trying to create the venue map.");

}

function DisplayVenueFloorInfo(venue)
{

var floors = "Available floor maps for " + venue.name +":\n";

for(var i in venue.floors)
{
floors = floors + venue.floors[i].name + "\n";

}

// Display the floor info
alert(floors);

}

</script>
</head>

382
</body>
</html>
Footprint Class
Represents the footprint of the venue map.
Properties

polygons Polygon[] The shapes that make up the
footprint of this venue.
zoomRange double[] An array of doubles indicating
the minimum and maximum
zoom levels where imagery is
available for this venue map.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{

383

}

{
error:ShowError});

}

{
// Set the map view
venue.show();

DisplayVenueInfo(venue);

}

{
// Show an error

}

384
function DisplayVenueInfo(venue)
{
var venueinfo = "Venue: " + venue.name +"\n" + "Venue Map ID: " + venue.id +
"\n" + "Venue Map Type: " + venue.type + "\n" + "Default Floor: " + venue.defaultFloor +
"\n" + "Detail Level Range for Default Floor: " + venue.footprint.zoomRange + "\n";

// Display the venue info
alert(venueinfo);

}

</script>
</head>
</body>
</html>
Metadata Class
Contains information about a venue map.
Properties

CenterLatitude number The latitude of the center
location of the venue map.
CenterLongitude number The longitude of the center
location of the venue map.
DefaultFloor string The ID of the default floor of
the venue map.
FloorHeader string A string used in the floor bar
of the venue map.
Floors Floor[] An array containing the floors

385
of the venue map.
Footprint Footprint The footprint of the venue
map.
MapId string The unique ID of the venue
map.
MapType string A string describing the venue
map type (for example,
mall).
Name string The name of the venue map.
YpId string The Yellow Pages ID of the
venue.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
// Initialize the map and set the view to a specific location
map = new
center: new Microsoft.Maps.Location(47.6,-122.3), zoom:11});

386


}

{

// Search for nearby venues
vmaps.getNearbyVenues({map: map, location: map.getCenter(), radius:10000,
callback:DisplayNearbyVenueCount});

}

function DisplayNearbyVenueCount(venues)
{
var displayResults = "Nearby venues with available venue maps:\n";

for (var i=0; i<venues.length; i++)
{
displayResults = displayResults + venues[i].metadata.Name + "\t" +
venues[i].distance/1000 + " km\n";

}

alert(displayResults);
}

387
</script>
</head>
</body>
</html>
NearbyVenue Class
Defines a nearby venue map.
Properties

distance double The distance, in meters, to the
venue.
metadata Metadata The venue map metadata.

Example
<html>
<head>
<title></title>



var map = null;

388
function GetMap()
{
map = new


}

{


}

{
var displayResults = "Nearby venues with available venue maps:\n";

for (var i=0; i<venues.length; i++)
{
displayResults = displayResults + venues[i].metadata.Name + "\t" +
venues[i].distance/1000 + " km\n";

}

389

alert(displayResults);
}

</script>
</head>
</body>
</html>
NearbyVenueOptions Object
Contains search options for retrieving nearby venue maps.
Properties

callback function The function to call when the
search is completed. The
function must accept an array
of VenueMap objects.
location Location The center of the circle in which
to search for nearby venue
maps.
map Map The base map.
radius double The radius, in meters, of the
circle in which to search for
nearby venue maps.

Example

390
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
map = new


}

{


}

391

{
alert("There are " + venues.length + " venue maps nearby.");
}

</script>
</head>
</body>
</html>
Polygon Class (Venue Map)
Defines the shape of venue map entities.
Properties

bounds LocationRect The rectangle that defines the
bounding box for the polygon.
center Location The center of the polygon.
locations Location[] The locations that define the
vertices of the polygon.

Primitive Class
Represents a venue map primitive, which represents a venue map entity.

392
Properties

bounds LocationRect The rectangle that defines the
bounding box for the
primitive.
businessId string The Yellow Pages ID for the
entity.
categoryId string The Yellow Pages business
category ID for the entity.
categoryName string The Yellow Pages business
category name for the entity.
the primitive.
floor Floor The floor to which this
primitive belongs.
id string The unique ID of the entity.
locations Location[] An array of locations that
represent the vertices of the
primitive.
name string The name of the entity.

Methods

highlight highlight() None Highlights the
primitive.
unhighlight unhighlight() None Removes the
highlighting of the
primitive.

393
Example
<html>
<head>
<title></title>



var map = null;
var vmaps = null;

function GetMap()
{
map = new


}

{


vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:ShowVenue});

394

}

{
// Set the map view
venue.show();

Microsoft.Maps.Events.addHandler(venue, 'click', DisplayVenueEntity);

alert("Click on the venue map to display entity info.");

}

function DisplayVenueEntity(e)
{
alert("The name of the store that was clicked is " + e.name + ".");

}

</script>
</head>
</body>
</html>

395
VenueMap Class
Represents a venue map. An example of a venue map is a mall.
Properties

address string The full address of the venue.
bestMapView ViewOptions The best map view of the
venue map.
businessId string The Yellow Pages ID for the
venue map.
the venue map.
defaultFloor string The floor that is displayed if
no floor is specified.
directory Directory The venue map directory,
which is a list of businesses
and features found within the
venue
floorHeader string The header for floors for this
venue map. For example, for
a mall the floor header would
be Level.
floors Floor[] An array, where each element
represents a floor of the
venue.
footprint Footprint The shapes that make up the
venue map.
id string The unique venue map ID.
name string The name of the venue
represented by the venue
map.
phoneNumber string The phone number for the
venue represented by the
venue map.

396
type string The venue map type, such as
Mall.

Methods

dispose dispose() None Disposes the
venue map object.
getActiveFloor getActiveFloor() string Returns the venue
floor map that is
currently
displayed.
hide hide() None Hides the venue
map.
setActiveFloor setActiveFloor(floor:string) None Displays the floor
map for the
specified floor.
show show() None Displays the venue
map.

Events

click eventArgs:Primitive Occurs when the mouse is
used to click the venue map.
close None Occurs when the close
button on the venue map is
clicked.
footprintclick eventArgs:Primitive Occurs when the detailed
map of the venue is clicked.
mouseout eventArgs:Primitive Occurs when the mouse
cursor moves out of the area
covered by the venue map.

397
mouseover eventArgs:Primitive Occurs when the mouse
cursor is over the venue
map.

Example
<html>
<head>
<title></title>



var map = null;
var venue = null;

function GetMap()
{
map = new


}

{

398


vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:SetVenue});

}

function SetVenue(venueObj)
{
venue = venueObj;
}

function ShowVenue()
{
// Set the map view
venue.show();

}

function HideVenue()
{
venue.hide();

}

</script>
</head>

399
<input type="button" value="Show Venue Map" onclick="ShowVenue()"/><input
type="button" value="Hide Venue Map" onclick="HideVenue()"/>
</body>
</html>
VenueMapCreationOptions Object
Contains options for creating a venue map.
Properties

error function The function to call if the venue
map was not successfully
created. The function must
accept two parameters: an
integer which is an error code
and an object that contains the
arguments passed to the create
method of the VenueMapFactory.
The error codes are:
1 The metadata needed to
create the venue map was
not found because of a 404
or other web exception, or
because the metadata was
found but was empty.
2 The venue map metadata
is invalid.
3 A timeout has occurred
trying to retrieve the venue
map metadata.
success function The function to call if the venue
map was successfully created.
The function must accept two
parameters: a VenueMap and an
object that contains the
arguments passed to the create
method of the VenueMapFactory.

400
venueMapId string A string that identifies the venue
map to display.

Example
<html>
<head>
<title></title>



var map = null;

function GetMap()
{
credentials:"Bing Maps Key"});


}

{

401
error:ShowError});

}

{
// Set the map view
venue.show();

}

{
// Show an error

}
</script>
</head>
</body>
</html>
VenueMapFactory Class
Contains methods for creating a venue map.
Constructor

402
VenueMapFactory VenueMapFactory(map:Map) Initializes a new instance of
the VenueMapFactory class.

Methods

n
Type
Description
create create(options:VenueMapCreationOptions) None Creates a venue map.
If the venue map is
created successfully, a
VenueMap is returned
to the function specified
in the success property
of the
VenueMapCreationOpti
ons.
You can display a
venue map using the
show method of the
VenueMap Class.
getNearbyVen
ues
getNearbyVenues(options:NearbyVenueMap
Options)
None Searches for venue
maps within a specified
distance. The callback
function must accept a
NearbyVenue array.

Example
<html>
<head>
<title></title>

403


var map = null;

function GetMap()
{

}

{
vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare',
success:DisplayInfobox});
}

function DisplayInfobox(venue)
{
// Set the map view
venue.show();

// Put an info box label on the map
mapCenter = map.getTargetCenter();

404
var venueinfobox = new Microsoft.Maps.Infobox(mapCenter, {title: venue.name,
showPointer: false, showCloseButton:false, height: 50, width: 180, offset:new
Microsoft.Maps.Point(-220, 150)});

map.entities.push(venueinfobox);

}
</script>
</head>
</body>
</html>
Bing Maps AJAX Control 7.0 Supported
Browsers
This topic contains information about browser support for the Bing Maps AJAX Control 7.0.
The Bing Maps AJAX Control 7.0 uses features of HTML5 if it detects that the client
browser supports HTML5. If this is the case, map performance will be faster, and map
animations and transitions will be smoother.
Supported Browsers
The Bing Maps AJAX Control 7.0 is supported on the following Web browsers. If you are not
using a supported Web browser, certain features of the map control may not work.

Desktop Browser Description
Internet Explorer 7.0 and later Supported on the PC
Firefox 3.6 and later Supported on the PC and the Mac
Safari 5 and later Supported on the Mac
Google Chrome Supported on the PC

405
Mobile Browser
Internet Explorer Mobile Browser
Apple iPhone Browser
Google Android Browser
Research in Motion (RIM) BlackBerry Browser

Release History for Bing Maps AJAX Control,
Version 7.0
The following release notes document updates to the Bing Maps AJAX Control 7.0.

Release Date Description
February 25, 2014 The following features were released in
preview:
You can display map labels in two
languages by specifying a primary and a
secondary language for the mkt parameter
in the map reference.
You can display map labels for each
country or region on the map in the local
language of that country or region by
specifying the custom language option ngt
Reference: Setting Map Control Parameters,
Localizing the Map

Notes include updates from February 25, 2014 onward.
Bing Maps AJAX Control 7.0 Developer
Resources
This topic contains support resources and contact information.
Developer Resources
The following resources are available for Bing Maps developers:

406
Check out the Bing Maps AJAX Control 7.0 Interactive SDK, which allows you to test out your
own map control code.
Connect with other Bing Maps developers on the Bing Maps AJAX Control Forum.
Visit the http://www.microsoft.com/maps website.
Read the Bing Maps Developer blog
Account Issues
If you are having issues creating a Bing Maps Developer Account, getting a Bing Maps Key, or
have an account access question, contact mpnet@microsoft.com.

Licensing Questions
If you are interested in finding out more about Bing Maps or have questions about licensing Bing
Maps, see the Bing Maps Licensing Tool.

Bing Maps Ajax Controls DK 70

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Bing Maps Ajax Controls DK 70

Загружено:

Авторское право:

Доступные форматы

Contents

Bing Maps AJAX Control, Version 7.0 ........................................................................................... 14

Вам также может понравиться