Virtual Earth, An Evangelist's Blog

Live Search Maps API

I need to mention an API that many people don't know exist and that's the API that allows you to publish data right to Live Search Maps using URL parameters. If you click on the "Help" link on the bottom right of Live Search Maps you get a help file popup.

From there you can look up problems with Live Search Maps and other stuff, but more importantly you can pull up the API documentation for how to publish data directly to Live Search Maps by passing in the respective arguments in a URL string. Search for "API" and the first result will be "Build your own URL" as shown below.

So, if Virtual Earth is a little more than you need, but Live Search Maps is just not enough perhaps this methodology of publishing your data is just right. I've pasted some of the docs below just to get it indexed.

Build your own URL

Create a link to add to an e-mail, blog (Short for weblog. An online journal. Each entry typically contains personal thoughts and Web links, with the newest entries listed first.) , or personal website that opens Live Search Maps to a specific location, map view, and zoom level. You can customize your link to display specific search results, driving directions, or items in a collection (A group of map pushpins, items, or search results that you create and save online.) .

Start with the base URL (Uniform Resource Locator. The unique address for a file that is accessible on the Internet.) for Live Maps, and then use parameters (A value appended to a URL that lets you pass specific information from your browser to a server. A parameter begins with a question mark and takes the form ?parameter=value.) to specify your location and define options such as zoom level, map view, search panels, and more.

To build your own URL:

1. Start with the base address.

   http://maps.live.com/default.aspx

2. Add a question mark (?).

   http://maps.live.com/default.aspx?

3. Add the first parameter you want to use, and then set the value of the parameter by using an equal sign (=).

   http://maps.live.com/default.aspx?v=2

4. Add the other parameters that you want to use, separating each parameter with an ampersand (&).

   http://maps.live.com/default.aspx?v=2&yp.gouda

Add parameters to your URL to customize what others see when they click your link.

General map view parameters

Parameter
Definition
Example
Details

v
Version
v=2

Defines the version of the URL API (Application Programming Interface. The language used by an application program to communicate with a computer's operating system.) . When used, you should always assign the value of 2 to this parameter. If you omit this parameter, the latest version of the API is used by default.

cp
Center point
cp=47.677797~-122.122013

Defines where the center of the map should be. Use the following format for the cp parameter:

Latitude~Longitude

Both values must be expressed in decimal degrees.

lvl
Zoom level (2D view only)
lvl=5

Defines the zoom level of the map view in 2D view. Valid values are 1–19. This parameter is ignored if you don't include the cp parameter.

alt
Zoom level (3D view only)
alt=1000

Defines the zoom level of the map view in 3D view. The value you apply to this parameter equals the number of meters above sea level that you want the zoom level to be at. For example, alt=1000 sets the zoom level at 1000 meters above sea level. Valid values are 0 to 20,000,000.

style
Map view
style=r

Defines the map view. Valid values for this parameter include:

• a: Used to display an aerial view of the map.
• r: Used to display a road view of the map.
• h: Used to display the hybrid view of the map.
• o: Used to display the bird's eye (oblique) view of the map.

Note

If you set the view to o, you may also provide the scene parameter, to specify a view or angle.

scene (required if style=o)
Scene ID reference
scene=3715328

Specifies the ID of the bird's eye (oblique) image tile to display; used to choose a specific view or angle.

tilt
Camera tilt
tilt=-45
Specifies the angle of the camera. Valid values are from -90 (straight down) to 0 (horizontal). This value is ignored in 2D view.

dir
Direction
dir=180
Specifies in degrees the direction the camera is pointing. Valid values are 0 to 360, where 0 is north, 90 is east, 180 is south, and 270 is West. This value is ignored in 2D view.

Examples

The following example opens Live Maps with the map centered on a specific location with a zoom level of 12, and sets the map view to the road map view:

http://maps.live.com/default.aspx?cp=43.901683~-69.522416&lvl=12&style=r&v=2

The following example opens Live Maps with the map centered on a specific location, uses the bird's eye (oblique) image map view, and specifies the zoom level and scene to use:

http://maps.live.com/default.aspx?cp=37.814692~-122.477339&style=o&lvl=1&tilt=-90&dir=0&alt=-1000&scene=1140291

Search parameters

To build a link that displays specific search results, use the base address http://maps.live.com/default.aspx and any of the following parameters.

Parameter
Definition
Example
Details

where1
Location
where1=1 Microsoft Way, Redmond, WA

Defines a location to center the map based on a specific address or a place name. The text is the same text that you type in the upper search box in Live Maps to search for a specific address or place name.

ss
Search type search
ss=yp.coffee

Defines the searches that you want to display. Use this parameter to display search results for a business, person or collection.

You can add a prefix to each search string that specifies whether the search is a yellow pages search (for business listings), a white pages search (for individuals), or a collection (for community generated data). Use the yp. prefix for yellow pages searches, the wp. prefix for white pages searches, and the Cl. prefix for collections. If you do not specify a prefix, a yellow pages search is performed by default.

sst
Search type sort
sst.1

You can add a prefix to each search string that specifies whether the search sort is displayed by relevance, distance, rating, or page number. Use the following values to define the type of sort you want:

• 0 = Relevance
• 1 = Distance
• 2 = Rating

Examples

The following example opens Live Maps to a specific address:

http://maps.live.com/default.aspx?where1=1%20Microsoft%20Way%20Redmond%20WA%2098052&v=2

This example opens Live Maps with a business search:

http://maps.live.com/default.aspx?ss=yp.Pizza&v=2

This example opens Live Maps with a people search sorted by distance:

http://maps.live.com/default.aspx?ss=wp.John~sst.1&v=2

Driving directions parameters

To build a link that displays directions from a specific start and end point, use the base address http://maps.live.com/default.aspx and any of the following parameters.

Parameter
Definition
Example
Details

rtp
Route
Rtp=adr.
Seattle,WA
~adr.1Microsoft Way,
Redmond, WA

Defines the start and end of a route to draw on the map, each separated by a tilde (~). Each of the waypoints (Coordinates that identify a point on the map.) are defined by either a pos (position) or adr (address) identifier, described below.

A complete route contains at least two waypoints. For example, a route with two waypoints is defined by the following:

rtp="A"~"B"

You can also specify an incomplete route. For example, you can define only the start of a route:

rtp="A"~

or the end of a route:

rtp=~"B"

If you provide only one waypoint, the driving directions panel is displayed with the provided waypoint, but no route is drawn.

Identifier
Definition
Example
Details

pos
Position
Rtp=
pos.42.2_
-122.3~
pos.55.2_-127.

Defines a waypoint as a specific position on the map. Use the following format:

rtp=pos.latitude_longitude_name

adr
Address
Rtp=
adr.Seattle,
WA~adr.1 Microsoft Way,
Redmond, WA

Defines a waypoint as an address. Use the following format:

rtp=adr.address

rtop
Route options
Rtop=0~0~E

Defines options for the route. There are three possible options, each separated by ~. The default value of non-abbreviated route, quickest without traffic will be used if not specified.

• 0 = Quickest
• 1 = Shortest
• 0 = Don't use traffic
• 1 = Use traffic
• 0 = No abbreviation
• E = End only
• S = Start Only

Note

The pos and adr identifiers must be used with the rtp parameter

To create directions for a party and let others view those directions in the One Click Directions map view, start with the following base address http://maps.live.com/OnceClickDirections.aspx.

You can use any of the parameters listed in the above tables to specify your waypoints.

The destination is specified using the rtp and pos parameters described above. Make that sure you specify only the end location, for example rtp=~pos.45.21_-123.2. The following parameters can be used to specify the default view index that you want displayed:

Parameter
Definition
Example
Details

rtv
View index
rtv=4

This is an optional parameter that specifies the start view for a route. Use the following format:

rtv=1

• 0 = Show all (default)
• 1 = Start from the first direction
• 2 = Start from the second direction
• 3 = Start from the third direction
• 4 = Start from the fourth direction

Examples

The following example displays a route on the map from a specific address to a specific point:

http://maps.live.com/default.aspx?v=2&rtp=adr.One%20Microsoft Way,%20Redmond,%20WA%2098052~pos.45.23423_-122.1232_MyPlace

The following example opens the driving directions panel with a start address only:

http://maps.live.com/default.aspx?v=2&rtp=adr.Seattle,%20WA

The following example opens driving directions to Papa John's Pizza in Redmond, WA:

http://maps.live.com/default.aspx?v=2&rtp=~pos.rycz2z4tpkxm_16110 NE 87th St,
Redmond, WA_Papa John_425-283-6478

Collections editor and collections parameters

To build a link that displays information from the collections editor or a specific collection, use the base address http://maps.live.com/default.aspx and any of the following parameters.

Parameter
Definition
Example
Details

sp
Collections editor
sp=adr.1 microsoft way,
redmond, wa

Defines a specific entity, address, or pushpin (A marker containing information such as notes and links, which you can place at a specific point on a map.) to add to the collections editor.

Collections editor items are defined as a pairing: the category and the value, separated by a period. There are six valid categories: adr, an, point, polyline, polygon,and yp. These are described in the next table.

Separate multiple collections editor items with tildes (~). If the item you specify contains a tilde, make sure the tilde is encoded as %7E.

cid
Collection ID
cid=15A41C376

Specifies the collection that you want to display by using the ID assigned to that collection. For the collection ID parameter, use the following format:

cid=collection ID

mapurl
Map URL
maprul=http://myurl/
goodstuff.xml

Displays a collection of items by using the location specified in the URL. For the map URL parameter, use the following format:

mapurl=url

fave
Favorites
fave=1

Displays the viewer's Favorites, if they are signed in to Live Maps. If the viewer isn't signed in to Live Maps, they will receive a notification to sign in. To enable the fave parameter, use the following format:

fave=1

Note

The value used for the fave parameter should always be 1.

explore
Explore mode
explore=sst.
1~tag.food

Forces Live Maps to open in exploration task mode. There are three ways to sort results in explore mode:

• 1 = Distance
• 3 = Static rank
• 4 = Chronological

For the explore parameter, use the following format:

explore= sst.sorttype
~tag.tagstring

tour
Tour mode
tour=1

Displays a collection in 3D tour mode. There are two options for how to display the tour that is loaded:

• 0 = Loads the collection tour in a paused state
• 1 = Loads the collection tour in an automatic playing state

Category
Definition
Details

adr
Address

Specifies an address to add to the collections editor. For the address, the value can be the address string, the address string and title, or the address string, title, and description:

sp=adr.addressString

sp=adr.addressString_title

sp=adr.addressString_title_description

Make sure that the addresses you provide are as specific as possible.

point
Point

Specifies a point to add to the collections editor by using latitude and longitude. For points, the value includes the latitude, longitude, title, notes, link URL, and photo URL to display, separated by underscores (_):

sp=point.position_
title string_notes,
string_link URL_photo URL

polyline
Polyline

Specifies a point to add to the collections editor by using the vertex positions on the map. For polylines, the value includes the latitude, longitude, title, notes, link URL, photo URL, fill color, line color, line weight, and line style to display, separated by underscores (_):

sp=polyline.vertex positions_title string_notes string_link URL_photo URL_fill color_line color_line weight_line style_label position

polygon
Polygon

Specifies a point to add to the collections editor by using the vertex positions on the map. For polygons, the value includes the latitude, longitude, title, notes, link URL, photo URL, fill color, line color, line weight, and line style to display, separated by underscores (_):

sp=polygon.vertex positions_title string_notes string_link URL_photo URL_fill color_line color_line weight_line style_label position

yp
Yellow pages listing

Specifies yellow page listings. For yellow page listings, the value is a valid yellow pages entity id:

sp=yp.listingID

Examples

The following example opens Live Maps and adds a specific yellow page listing to the collections editor:

http://maps.live.com/default.aspx?v=2&sp=yp.YN926x17845652

The following example opens Live Maps and adds the address "1 Microsoft Way, Redmond, WA 98052" to the collections editor:

http://maps.live.com/default.aspx?v=2&sp=yp.YN925x15732835~yp.YN925x15789183~adr.1%20Microsoft%20Way%2C%20Redmond%2C%20WA%2098052

The following example opens Live Maps and adds an address and two yellow page listings to the collections editor:

http://maps.live.com/default.aspx?v=2&sp=yp.YN926x17845652~yp.YN925x15732835~adr.1%20Microsoft%20Way%2C%20Redmond%2C%20WA%2098052

The following example shows how to open a collection in Live Maps:

http://maps.live.com/?v=2&cid=1234567890ABCDEF!

Notes

• The tour parameter must be used with the cid or mapurl parameter.
• The collection ID in the previous example is fictitious. You must change the collection ID to the collection ID that you want to open.

Note

The tables in this topic list the parameters currently supported by the Live Maps URL API (Application Programming Interface. The language used by an application program to communicate with a computer's operating system.) . These parameters may change in future versions.

CP