爱立信实验室Web Maps API文档

发布于: 2011年10月26日

标签：API, 地图, 手机, 移动

原文链接：https://labs.ericsson.com/apis/web-maps/documentation

Table of Contents

1. Dynamic Web Maps
1.1. Creating your first map
1.1.1. Step 1 – Sign up for a Web Maps developer key
1.1.2. Step 2 – Create a simple web page to include the maps in
1.1.3. Step 3 – Upload your HTML page to your web server
1.2. Adding controls to your map
1.3. Creating interaction with your map
1.4. Customizing look and feel
1.5. API Documentation
2. Static Web Maps
2.1. Static Maps Documentation
2.2. Request Format
2.3. Required Request Parameters
2.4. Optional Request Parameters

The Web Maps documentation contains the resources you need to get started on and master developing web applications using Web Maps.

1. Dynamic Web Maps

How to embed a simple dynamic map on a web page.

This tutorial will teach you how to setup and create the simplest web application using Web Maps from Ericsson Labs.

To create your first web page with web maps you need to follow 3 simple steps.

To use Web Maps you need to receive developer key which you will use when you are including the maps in you web page. You also need to register the URL of the website from which you intend to use Web Maps. To sign up for a developer key and register your website URL click here.

When you have received your developer key you can create your first web page with Web Maps to see that it works. To do this there are four simple things you need to add to the HTML code of your web page:

Include the Web Maps JavaScript
Define the doOnLoad function that will initiate the map
Make sure the doOnLoad function is run to initiate the map when the body is loaded
Create the div that will contain the map. The contents of this div will be replaced by the map when it is loaded

See the example of code below for a simple but complete HTML page that displays a map in the center of the page.

<!DOCTYPE html PUBLIC “-//W3C//DTD HTML 4.01 Transitional//EN”
“http://www.w3.org/TR/html4/loose.dtd”>
<html>
<head>
<meta http-equiv=”Content-Type” content=”text/html;
charset=ISO-8859-1″/>
<title>Web Maps – The Simplest Example</title>

<!– This is the simplest example of how to include
maps in a web page using Web Maps from Ericsson Labs–>

<!– 1. Include the Web Maps JavaScript –>
<script type=”text/javascript”
src=”http://maps.labs.ericsson.net/ravegeo/webmap2/ewm.js”/>
</script>
<!– 2. Define the doOnLoad function that will
initiate the map –>
<script type=”text/javascript”>
function doOnLoad() {

//The callback is the object that will receive notifications
//from the map.
//You don’t need to worry about it now, just initialize it.
var callback = {
mapLoaded: function(map) {
mainMap = map;
}
};

//Define the parameters that will be used to
//initialize the map.
//mapContainer is the element that will
//contain the map.
//key is your developer key received from labs.ericsson.com.
//callback is the callback object defined above.
var params = {
mapContainer: document.getElementById(“mapdiv”),
key: “YOUR_DEVELOPER_KEY”,
name: “OSM_1_Mercator”,
callback: callback
};

//Make sure mainMap var is null
mainMap = null;

//Initiate the map using the parameters defined above.
ericsson.WebMap.initiateCreation(params);
}
</script>
</head>

<!– 3. Make sure the doOnLoad function is run to
initiate the map when the body is loaded –>

<!– 4. Create the div that will contain the map.
The contents of this div will be replaced by the map
when it is loaded –>

</center>
</body>
</html>

To test the maps you need to upload your HTML page to a web server from which it can be accessed with the URL you that you registered in step 1.

Navigate your web browser to your web page to out the map (you navigate by dragging with the left mouse key to pan and holding down the right mouse key to zoom).

This is how the page should look in your browser

Now you have a simple map on your website, the next step is to Add a few controls to the map.

You can also dive into the full API Documentation if you want to start playing around with all the functionalities.
Back to Top
1.2. Adding controls to your map

How to add a few controls to your map to let your users navigate it.

Once you have created the map, the next step is to add some controls to your map to enable your users to navigate it.

It’s always possible to pan and zoom the map by dragging it with the mouse but you may also want to add some buttons on the page to make it easy for your users.

Add some buttons like this:

<!– Navigation buttons –>
<img onclick=”mainMap.pan(-0.5,0);” style=”cursor: pointer;”
width=”50″ src=”images/arrow_left.png” alt=”Pan Left”
title=”Pan Left” border=”0″ />
<img onclick=”mainMap.pan(0.5,0);” style=”cursor: pointer;”
width=”50″ src=”images/arrow_right.png” alt=”Pan Right”
title=”Pan Right” border=”0″/>
<img onclick=”mainMap.pan(0,0.5);” style=”cursor: pointer;”
width=”50″ src=”images/arrow_up.png” alt=”Pan Up”
title=”Pan Up” border=”0″ />
<img onclick=”mainMap.pan(0,-0.5);” style=”cursor: pointer;”
width=”50″ src=”images/arrow_down.png” alt=”Pan Down”
title=”Pan Down” border=”0″ />
<img onclick=”mainMap.zoom(0.5)” style=”cursor: pointer;”
width=”50″ src=”images/plus.png” alt=”Zoom In”
title=”Zoom in” border=”0″/>
<img onclick=”mainMap.zoom(2);” style=”cursor: pointer;”
width=”50″ src=”images/minus.png” alt=”Zoom Out”
title=”Zoom out” border=”0″ />

In this example we use image icons for the user to click but any HTML element that the user can click on will do.

To define what is going to happen when the icons are clicked you enter the JavaScript call to the mainMap in onclick property. The mainMap is the JavaScript object representing the map.

The pan() function will cause the map to pan left, right, up, or down a given number of screens relative to the current display. The function call pan(-0.5, 0) means that the displayed area is moved half a screen left.

The zoom() function will cause the map to zoom a given factor. The function call zoom(2) means the display is zoomed out to an area twice as wide as the current area.

The resulting page should look something like this.

The next step is to Create interaction with the map and add some symbols to it.
Back to Top
1.3. Creating interaction with your map

How to define how your users should interact with the map itself and add a few symbols to add.

Many map applications let the users interact with the application by clicking on the map (i.e. to mark the location of something or select an area). To do this we need to add a function to the callback parameter used when initializing the map. The functions in the callback parameter lets you define what should happen when different events are invoked by the map.

In this example we want to add a JavaScript function that will trigger when the user clicks somewhere on the map. We also need to make the map create a layer when it is loaded. The layer will be called mainLayer and we will use it to add symbols that we want displayed on the map.

To do this we change the assignment of the callback parameter to:

This will create the mainLayer when the map is loaded. Each time the map is clicked, a symbol will be created and added to the mainLayer.

We also want the make sure the mainLayer var is null when the page is loaded so we add the following to the doOnload() function:

mainLayer = null;

To try out how to read data from the map objects we can also add a button that will let the user center the map on the symbol that has been placed on the map. To do this we add the following piece of HTML to the page:

Clicking this button will call the function moveTo() and cause the map to center on the x and y values that are read from the geoObject called ‘TestSymbol’ (which is added when the map is clicked).

The page with the map should now look something like this

Now you can start creating your own innovative map applications using Web Maps. The Web Maps API Documentation contains a full description of how to use all of the funtionality of the API.
Back to Top
1.4. Customizing look and feel

How to change the colors and elements of the map to make it designed to fit your application’s needs.

One advantage of rendering the maps in the browser (which is different from most other map APIs that send rendered images from the server) is that you can customize how the maps are rendered. This allows you to change the colors of all the elements in the maps, change the icons that represent the different points of interests, and change which elements should be rendered.

To do this with Web Maps is as simple as introducing a new parameter called style in the doOnLoad function. In the style parameter you define the colors of the different objects in the map and set the URLs to icons, as seen in this example.:

var style = {
LAND_COLOR:”235 235 220″,
WATER_COLOR:”165 195 215″,
WATER_BORDER_COLOR:”150 160 200″,
CITY_COLOR:”225 225 200″,
BORDER_COLOR:”210 210 210″,
WOODLAND_COLOR:”207 225 195″,
STREET_COLOR:”255 255 255″,
STREET_THIN_COLOR:”255 255 255″,
ROAD_COLOR:”255 245 160″,
MOTORWAY_COLOR:”240 190 36″,
OTHER_ROAD_COLOR:”255 255 255″,
ROAD_BG_COLOR:”210 210 210″,
MOTORWAY_SIGN_COLOR:”240 190 36″,
ROAD_SIGN_COLOR:”255 255 200″,
PARK_COLOR:”185 220 175″,
PARK_BORDER_COLOR:”200 130 130″,
INDUSTRY_COLOR:”215 215 215″,
FERRY_COLOR:”100 160 200″,
RAILWAY_COLOR:”120 120 120″,
BUILDING_COLOR:”230 215 170″,
OFFICIAL_BUILDING_COLOR:”200 200 200″,
BUILDING_BORDER_COLOR:”230 200 120″,
ELEVATION_COLOR:”235 215 170″,
TEXT_COLOR:”50 50 50″,
WATER_TEXT_COLOR:”50 50 130″,
FERRY_TEXT_COLOR:”80 80 80″,
INDUSTRY_TEXT_COLOR:”100 100 100″,
PARK_TEXT_COLOR:”50 130 50″,
AREA_TEXT_COLOR:”100 100 100″,
AIRPORT_SYMBOL:”yourairporticon.png”,
RAILWAY_SYMBOL:”http://www.anothersite.com/images/yourrailwayicon.png”,
SUBWAY_SYMBOL:”yoursubwayicon.png”,
FERRY_SYMBOL:”yourferryicon.png”,
BUS_SYMBOL:”yourbusicon.png”,
TRANSPORTATION_STOP_SYMBOL:”res/bus.png”,
DEFAULT_SYMBOL:”res/smallsquare.png”,
CITY_SYMBOL:”res/reddot.png” ,
LANDUSE_VISIBLE:”true”,
BUILDINGS_VISIBLE:”true”,
WOODLAND_VISIBLE:”true”,
ELEVATION_VISIBLE:”false”,
POIS_VISIBLE:”true”
};

The style parameter should then be included in the initialization parameters:

var params = {
mapContainer: document.getElementById(“mapdiv”),
style:style,
key: “YOUR_DEVELOPER_KEY”,
name: “OSM_1_Mercator”,
callback: callback
};

Experiment with different colors and with the elements you want to have rendered to find the map style that fits your application. By creating your own style of maps you can really make your website stand out from all other map sites out there.

Here is an example of how a pirate style treasure map could look

Here is an example of how a map in night mode

Note that styling your maps only works when you are using the Applet version of Web Maps, which renders the maps in the browser. If your users have a browser that doesn’t support Java, or if you initialize the map with ericsson.TiledMap.initiateCreation(params), the maps will have the default style.
Back to Top
1.5. API Documentation

The full Dynamic Web Maps API Documentation with overview and detailed specifications of the entire API can be found here.

The Static Maps documentation describes how you use Web Maps when you only want a static non-interactive map image to include in your web site.

The Static Maps API offers a way of retrieving a map image from the server at a fixed position and zoom level. It is useful when you only need a map image and don’t want your users to be able to interact with it.

Using it is as simple as inserting an image into a web page. As URL of the image you set the path to the Static Maps API. Example:

This results in an image looking like this.

In the request you specify the location of the map image, zoom level, and data source. You use the same Web Maps API key as you use for the dynamic web maps. To sign up for the API key go here.

Note that you have to use the Static Maps API to insert map images to web pages located at the URL you have registered to your API key. This is to prevent anyone else from using your key in their applications.

The base URL for requesting the static map image looks like this:

http://maps.labs.ericsson.net/StaticMap/

The details of the image are placed in the URL as standard GET parameters.

Parameter    Value    Description
name    String    A name that identifies the map configuration to use. Currently the only available value is: “OSM ” for Open Street Maps data.
geox    double    The longitude for the center of the requested geographic area.
geoy    double    The latitude for the center of the requested geographic area.
geow    double    Width of the requested geographic area. At least one of geow and geoh is required. If only one of geow and geoh is specified the other one is calculated to keep the aspect ratio.
geoh    double    Height of the requested geographic area. At least one of geow and geoh is required. If only one of geow and geoh is specified the other one is calculated to keep the aspect ratio.
width    int    Width in pixels of image to generate.
height    int    Height in pixels of image to generate.
devKey    String    This is the API key that you received when signing up for the Web Maps API key. If you haven’t already got one, you can get one here.

Parameter    Value    Description
format    String    Image format for the produced image. Available formats are gif and png. The default is png.
rotation    int    Rotate the map this many degrees counter clockwise. The default is not to rotate the map.
background    String    The background color, “transparent” or a string defining the intensity of each color (RGB) like “255 0 215”.

- EOF -