Baidu Maps Javascript API Document

Baidu Maps Javascript API Document
The latest version of Baidu Maps Javascript API is V2.0. But it looks this version is not ready yet. We tested the stable version in V1.5, and below document are based on V1.5 not 2.0.
In future, if we got stable version for V2.0, then we will update the document.

Features

The Baidu Map module is an API wrapper which currently only stores a Baidu Map API key (see Implementation, below for more information).
All of the features are actually provided by the Baidu Map Geofield sub-module integrated with the Geocoder and Geofield modules APIs.

Baidu Geocoder: (Currently supports Geocoding API v2.0)
Integrates with Geofield (Geocode from field) through a Geocoder Plugin that returns geo-coordinates from any address in China.

  • Geocode address or location data from numerous types of fields: text, addressfield, location, computed, taxonomy_term_reference, etc…
  • Improved handling of addressfield values to match with China’s addresses format and support for China address field.
  • Filter geocoding results based on precision level.

Baidu Map Display Formatter: (Currently supports Map Javascript API v2.0)
Provides a display formatter for Geofield values to be displayed through Baidu Maps.

  • Supports all Geometries provided by GeoPHP (Polygon, linestring, multilinestring, etc…) and Geofield Widgets (WKT, Bounds, Longitude/Latitude, GeoJSON and geocoding from field).
  • Provides numerous Baidu Map display formatter settings such as size, default zoom, map control types and many other display properties (see the screenshot of the formatter form).
  • Overridding Marker Bubbles (InfoWindow) from Theme.
  • Automatic adjustment of Map’s center and zoom to display all available data in the same viewport.
  • Supports display of multiple field values.
  • Integration with Views and Variable API.

Implementation:

The idea behind the Baidu Map module is to provide an API wrapper that would allow other modules or APIs to potentially integrate with Baidu Map. After further investigation, it would seem the Baidu Map API key could potentially be used by other modules that would extend its logic to be integrated with other Drupal modules’ APIs, that’s why it was kept as an independent wrapper module.

Then, the integration with Geofield and Geocoder already provides all the necessary logic related with Field and Storage concerns.
The Baidu Map Geofield module’s code was greatly inspired and adapted from the excellent Geocoder (7.x-1.x branch, see google.inc) and Geofield(7.x-2.x branch, see geofield_map) modules and their integration with Google Maps. Several features provided by Google Geocoder and Maps APIs had to be adjusted since Baidu has its own (slightly different) ways, methods and API to provide a similar set of features.

The Baidu Map Geofield module provides a Baidu Geocoder to geocode textual addresses in China and a display formatter to display any Geofield values through Baidu Maps.

Main differences with the Google Geocoder and Geofield implementations:
For the Geocoder, although Google certainly provides more advanced features, Baidu is probably more accurate or would provide perhaps more data when geocoding requests in Chinese for China.
In terms of features, the major difference is that Baidu would return at most a single location result, no matter how generic the request could be (for example, ??? / Train station), when Google Geocoder could return multiple results with various precision/approximation/filtering parameters or Geometries. With a single point returned at most, fewer supported properties, unfortunately, Geometry Types, such as Bounds or Viewport and other filtering parameters provided by Google don’t seem to be currently supported by Baidu Geocoder.

For the Baidu Map display formatter, the entire Geofield Map module could be re-used almost “as is”.
In terms of JS Map API, Google still seems to provide more advanced features than Baidu, which mostly resulted in fewer properties for the field formatter settings form (customization of the display). Another notable difference was found in the way Google Map API handles complex paths, such as multiple polygons, as a single path, which is not the case for Baidu Map API, requiring each different polygon to be treated as a specific path/group/overlay (see GeoJSON to Google Maps for more information).

Otherwise, overall, GeoJSON to Google, formatter settings form, Views support, Google Geocoder, geofield_map JS code, etc… had all to be slightlyadapted to match closer with Baidu’s APIs, but in general, most of Google Maps features could cross-over very nicely with a great amount of similarities(Some parts could even be re-used almost exactly “as is”, such as for the formatter form or the views display style plugin).

Installation and configuration

All this information could also be found in the Baidu Map README.TXT or Baidu Map Geofield README.TXT files.

Baidu Map:
1 – Download the module and copy it into your contributed modules folder:
[for example, your_drupal_path/sites/all/modules] and enable it from the modules administration/management page.
More information at: Installing contributed modules (Drupal 7).

2 – Configuration:
a. After successful installation, browse to the Baidu Map Settings form page under:
Home » Administration » Configuration » Web services » Baidu Map
Path: admin/config/services/baidu_map or use the “Configure” link displayed on the Modules management page.

b. To start using Baidu Map fill in the Baidu Map API Key as described in field’s help text (first field of the admin settings form). If you don’t already have an API Key, feel free to apply for one on the Baidu API website.

Baidu Map Geofield:
0 – Prerequisites:
Requires Geocoder, Geofield and Baidu Map modules to be installed.

1 – Same as Step 1 above, for Baidu Map.

2 – Configuration:
After successful installation, two new components should be made available for configuration:

a. Baidu Geocoder:
For any existing or newly created Geofield field, with the widget type “Geocode from another field”, the Baidu Geocoder could be selected from the main field configuration settings form, in the required dropdown field “Geocoder” (see screenshot of a geofield settings page).
For example: the page content type:
Home » Administration » Structure » Content types » Page » Manage fields

b. Baidu Map display formatter:
Browse to the “Manage Display” settings page, for the entity (Node content type, for example) with a Geofield field, to configure the formatter (See attached screenshot of the formatter settings form).
For example: the page content type:
Home » Administration » Structure » Content types » Page » Manage display

Useful Resources

Baidu Online Document Portal:
Below link is shows document start page for Baidu Map JavsScript API V2.0
http://developer.baidu.com/map/index.php?title=jspopular

First, we give the tested code for Baidu Map functions:

You can download whole test code here: BaiduMapsDemo1.html
html>

<html>

<head>

<meta name=“viewport” content=“initial-scale=1.0, user-scalable=no”> <meta charset=“utf-8”>

<title>Geocoding servicetitle>

<style>

html, body, #map-canvas { height: 90%; width:90%; top: 50px; margin: 0px; padding: 0px }

#panel { position: absolute; width: 50%; top: 5px; left: 10%; margin-left: -10px; z-index: 5; background-color: #fff; padding: 5px; border: 1px solid #999;}

#address { width: 75%;} style> <script src=http://api.map.baidu.com/api?v=1.5&ak=nT3zdUWKrvmLkAUzTkhV7lqq&#8221;>

script>

head>

<body>

<div id=“panel”>

<input id=“address” type=“textbox” value=“????” onkeydown=if(event.keyCode == 13){codeAddress();}>

<input type=“button” value=“?????Baidu Map?” onclick=codeAddress()>

div>

<div id=“map-canvas”>div>

<script type=“text/javascript”> var geocoder; //global variable for GEOCoder var map; //global variable for Baidu Map //initialize Baidu Map functioninitialize() { //get map-canvas as Baidu Map painting area map = new BMap.Map(“map-canvas”); var point = newBMap.Point(116.30814954222,40.056885091681); map.centerAndZoom(point, 16); //you have centralize the map map.addControl(newBMap.NavigationControl()); //add Navigation Controller map.addControl(new BMap.MapTypeControl()); //add Map Type Controllermap.addControl(new BMap.OverviewMapControl()); //add Overview Map Controller//map.enableScrollWheelZoom(); //scroll wheel zoom is not working well in Mac book//map.removeControl(CopyrightControl); map.addOverlay(new BMap.Marker(point)); //create new maker geocoder = newBMap.Geocoder(); //create new GEO coder //add event listener depends on needs.//BMap.addEventListener(‘zoomend’, function() {}); } //show content in InfoWindow function createInfoWindowContent(address,latlng) { return [address, ‘LatLng: ‘ + latlng.lat + ‘ , ‘ + latlng.lng].join(
);} //Convert new address into Map Marker on Baidu Map function codeAddress() { var address = document.getElementById(‘address’).value; geocoder.getPoint(address, function(point) { alert(point.lat ‘:’ point.lng); //if the GEO coder error, then it will return null. if (point) { map.centerAndZoom(point, 16); varmarker = new BMap.Marker(point); map.addOverlay(marker); var opts = { width : 250, // ?????? height: 50 // ?????? } var infoWindow = newBMap.InfoWindow(createInfoWindowContent(address,point),opts); map.openInfoWindow(infoWindow,map.getCenter());}});} initialize(); //Call initialize function script>

body>

html>

Above code is demonstrated the simple function we used in myCinsay.com, which convert the given address into latlng pair data and then mark on Baidu map.
In this demo, it includes basic functions we are going to expend:

  1. Loading the Baidu Map Javascript API


<script src=http://api.map.baidu.com/api?v=1.5&ak=nT3zdUWKrvmLkAUzTkhV7lqq&#8221;>script>
v=1.5 means version 1.5, and ak means access key, which like API_key in google map. Without valid access key, you could not use Baidu Map.
Baidu claimed that ak is mandatory parameter to use Baidu map services.
To get access key, you have to register a Baidu account.

  1. Map DOM Element


<div

id=“map-canvas”>div>
Map DOM element is for the map to display on a web page. It must reserve a spot for it. In the example above, we defined a div named “map_canvas” and in style, we set its size and other style attributes.

  1. The Elementary Object BMap


map = new BMap.Map(“map-canvas”);

Constructor Description
Map(container:String|HTMLElement[,opts:MapOptions]) Creates a new map inside the given HTML container, which is typically a DIV element. You may also pass optional parameters of type MapOptions in the opts parameter.



The Javascript class that represents a Baidu map is the BMap.Map class. Objects of this class define a single map on a page. You may create more than one instance of this class – each object will define a separate map on the page. Using the JavaScript “new” Operator creates the new instance of this class. You need specify a DOM node in this page as a container for the map (usually a div element).
More details about this class refer to:
http://developer.baidu.com/map/reference/index.php?title=Class:%E6%A0%B8%E5%BF%83%E7%B1%BB/Map

  1. Initializing the Map


map.centerAndZoom(point, 16); //you have centralize the map
map.addControl(new BMap.NavigationControl()); //add Navigation Controller

map.addControl(new BMap.MapTypeControl()); //add Map Type Controller

map.addControl(new BMap.OverviewMapControl()); //add Overview Map Controller

The new map initialization is accomplished with use of the map’s centerAndZoom() method. This method requires a LagLng coordinate and a zoom level and this method must be set before any other operations are performed on the map, including setting any other attributes of the map itself.

  1. Loading the Map


We defined function initialize() to initialize the map, so it can be called in JavaScript while an HTML page rendered. To ensure that map is only placed on the page after the page has fully loaded, we can execute the function once theelement of the HTML page receives an onload event. Doing so avoids unpredicted behavior and gives it more control on how and when the map draws.
Baidu Map Javascript API also provides a number of events that you can “listen” for to determine state changes. See below links for more information.
http://developer.baidu.com/map/reference/index.php?title=Class:%E6%A0%B8%E5%BF%83%E7%B1%BB/Map#.E4.BA.8B.E4.BB.B6
The clearHotspots() function is a utility function designed to prevent memory leaks.

  1. GEOCoder

geocoder = new BMap.Geocoder(); //create new GEO coder
Now that we have a map, we need a way to refer to locations on the map. Geocoder object provides such a mechanism within the Baidu Map API.

Method Description
getPoint(address:String, callback:Function, city:String) getPoint() is used to convert a string address into a LatLng coordinate. This method takes as parameters a string address to convert, and a callback function to execute upon retrieval of the address. It’s better providing the city of the address, because same street name may be found in many cities. If search failed, it will return NULL.
getLocation(poit:Point, callback:Function[, options:LocationOptions]) getLocation() method is the process of translating a point into a human-readable address, is known as reverse geocoding. Note: reverse geocoding is not an exact science, Baidu Map will attempt to find the closest addressable location within a certain tolerance. If search failed, it will return NULL.


For more detail information about Geocoder class, see:
http://developer.baidu.com/map/reference/index.php?title=Class:%E6%9C%8D%E5%8A%A1%E7%B1%BB/Geocoder

  1. Map Marker

map.addOverlay(new BMap.Marker(point)); //create new maker
Marker object will places a marker overlay on the map at the given geographic location.
You can customize the marker by using your own icons.
For more detail information about Marker Class, see:
http://developer.baidu.com/map/reference/index.php?title=Class:%E8%A6%86%E7%9B%96%E7%89%A9%E7%B1%BB/Marker

  1. Map Info Windows

var infoWindow = new BMap.InfoWindow(createInfoWindowContent(address,point),opts); map.openInfoWindow(infoWindow,map.getCenter());
Each map within one Baidu Map API may show a single “info window”, which displays HTML content in a floating window above the map. The info windo looks a little like a comic-book word ballown; it has a content area and a tapered stem, where the tip of the stem is at a specified point on the map.
The InfoWindow object has no constructor. An info window is automatically created and attached to the map when you crate the map. You can’t show more than one info window at a time for a given map.
For full documentation on info windows, consult the:
http://developer.baidu.com/map/reference/index.php?title=Class:%E8%A6%86%E7%9B%96%E7%89%A9%E7%B1%BB/InfoWindow

All other Baidu Map API Class reference is available in:
http://developer.baidu.com/map/reference/index.php


Here is more detail explain how Baidu Geocoding API working, which you can combine with other map API, like Google Maps. In case the Google map could not return exact Chinese address, you can call Baidu Geocoding API, to convert a Chinese address into LatLng, and mark it in Google Map.

http://developer.baidu.com/map/index.php?title=webapi/guide/webservice-geocoding

And here is the screen short for Baidu Map demo page I created above.




Advertisements

About qianggan

Sr. Software Engineer
This entry was posted in Computers and Internet. Bookmark the permalink.

3 Responses to Baidu Maps Javascript API Document

  1. Vishnu Reddy says:

    Hi, How do we change the marker icon color? I want it to be blue.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s