How to Add Baidu Maps to Your Application Without Learning Chinese
Google Maps, like all the Google services, is blocked in the People’s Republic of China. Due to their Internet censorship policy, certain websites can only be accessed via VPN. We must accept it and use any of the Chinese map services alternatives, like Baidu Maps or Gaode Maps.
We must keep this in mind not only when traveling to China but when we develop our applications too. In our case, we had to adapt our React applications to use a different map service when the user accesses them from the Asian country.
Baidu Maps
Baidu Maps is the most used web map service in China. It offers features like satellite imagery, street maps, street view, and even indoor view but it is available only in the Chinese language.
To access Baidu APIs, you will need to register as a developer and create a valid API Key. It used to be mandatory to have a Chinese phone number to register in Baidu. Now you can also do it through this link for overseas registrations, although some countries, like the European ones, are not supported yet. You can overcome this by getting a compatible mobile phone number using a web service like Skype.
In our case, we decided to use a third-party library. A library that encapsulates the Baidu API offering us a wrapped and simpler version of the API. Preferably in a known language. We found a couple of React libraries like react-baidu-maps or react-baidu-map, but we dismissed the latter because its latest commit is from 2016.
react-baidu-maps
react-baidu-maps exposes React components wrapping the Baidu Maps API. This library lets us render a Baidu map without having to access or manage the real Baidu API. Besides, its documentation is in English.
Its Github documentation is not too exhaustive, but the examples allow us to render a simple map example:
As we see in the example, to use the BaiduMap component dynamically with asynchronous load, we need to use the asyncWrapper function to wrap the BaiduMap component.
These examples are enough to render a simple map. But to fully grasp how this library works we recommend to follow the next steps:
- Read the react-baidu-maps README.md.
- Download the repo or go over its Github page to examine the code.
- Review the BaiduMap props, understanding its types and naming.
- Experiment with the props to customize the map examples.
- Repeat the process with every component from the library that we want to add to our maps.
Customizing a Baidu Map
BaiduMap has some statically defined PropTypes within the component and other namedcontrolledPropTypes. Among the first ones, we find different props to define the map by default. We must notice that the mapContainer prop appears as required, so we must define a container for the map. The mapContainer or the element wrapping the map must have a specific height. The documentation does not explicitly specify it, but otherwise, we will only see a blank page.
The controlledPropTypes object includes props as:
- the map center.
- the zoom level.
- whether to allow different movements on the map.
- the type of map (normal, perspective, satellite, hybrid).
We must also review the shapes of each one of these props, defined in src/utils/MapPropTypes.
Applying some of the previously mentioned props, we can easily render a custom map:
Moreover, the library offers us all Baidu Maps supported overlays. Like Marker, InfoWindow, Circle, Curve, etc.
We can complete our example by adding a Marker that shows an InfoWindow (an information popup) when it is clicked. We need to thoroughly review the Marker and InfoWindow propTypes as well.
This simple code snippet renders a 400px height map centered in Beijing. Now we are able to drag the map or zoom in with our scroll wheel and by double-clicking.
With these simple steps, you will be able to render your own customized Baidu Maps. Now it is your turn to try it out. Good Luck!
Summing up
Due to the People’s Republic of China’s web restrictions, some of the most widely used internet services are blocked. For example, Google Maps, which forces us to adapt our worldwide targeted apps to this situation. Trying to use a local map service, like Baidu Maps, can be challenging. Its websites are only in Chinese which can be overwhelming if you don’t know the language. An option is using a third-party library, which encapsulates the Baidu API offering us a wrapped and simpler version. Using react-baidu-maps we can render maps without mastering the Baidu API or using a dictionary.
