A Short Guide To The Chinese Coordinate System. GCJ-02(gcj 02) Explained.

简体中文 Deutsch 日本語

Posted by Dmitry

Updated on

maps python javascript mapbox china google map WGS-84 GCJ-02 BD-09 baidu openstreetmap
Thanks to Chris Wu from Mapbox China for his feedback on this article and insights about how maps works in China. Without him this article would not be complete.

Have your ever searched google maps china offset? Most people who was in China yes. Here is my story behind this question.

I remember my first visit to China in 2010. We booked a hotel in a good location in Guangzhou and saved coordinates and routes to Google Maps. But when we arrived at a destination, it was obvious that there are no hotels. I was at the point where my hotel should be, but all i have around is a huge square(花城广场 aka Flower City Square). Long story short. At some point, some guy saved us with his Meizu phone by showing that our hotel actually a few miles away from this square.

These days i work with China and face the same challenges as a developer. I decided to write an article to summarize my experience in the hope that this might help someone.

baidu map screenshot and the old chinese map

China coordinate system

For starters let's talk about the main coordinate systems used today. An international standard is WGS-84(Earth coordinates) or World Geodetic System, where 84 is the latest revision of this standard applied in 1984. This standard is used by GPS. Each time you use Google Maps(or almost any maps) you can thank WGS-84. Now let's talk about China.

world coordinate systems. WGS-84, GCJ-02, BD-09

WGS-84 ⇛ GCJ-02 ⇛ BD-09

Chinese regulators require approved map services to use standard GCJ-02(Chinese: 国测局; pinyin: guó-cè-jú). It was formulated by the Chinese State Bureau of Surveying and Mapping in 2002. Sometimes GCJ-02 is called Mars coordinates. GCJ-02 is based on WGS-84 and uses an obfuscation algorithm, which adds random offsets to both the latitude and longitude to improve national security. If the WGS-84 point is placed on the GCJ-02 map, on average, there will be a location offset for about 300-500m. Very few are into the «miles» apart, usually just by a couple of blocks. That's why i got lost during my first visit to China.

Hold tight. There is more. Baidu went further and implemented yet another abstraction adding further obfuscation to GCJ-02. It's called the BD-09(Baidu, formulated in 2009). The primary purpose was to protect Baidu's data so that competitors couldn't easily duplicate. Baidu has internal tools to shift between the three coordinate systems, but only making GCJ-02 to BD-09 public to encourage using their standard for tiles, search coordinates, etc.

As required by the Chinese law there is no official API to convert to WGS-84.


According to Wikipedia, «OpenStreetMap, the crowdsourced project to assemble a map of the world, advises that "private surveying and mapping activities are illegal in China». Although if you look at the Baidu or Mapbox maps, you'll often find OSM attribution next to the map license. It means that the usage of OSM is not illegal in China, and you can add data to OSM from satellite images. But to do ground data collection, you must obtain a Survey License(ability to collect data and create a commercial product). And it's a whole different story.

As Chris mentioned to me, a survey license is extremely difficult to get. As a result, there are fewer than 20 companies that have this license. Giant tech companies like Alibaba needed to acquire AutoNavi just for this license, Tencent had to buy NavInfo. Mapbox, for example, partnered with EMG, a leader in navigation grade map data. Didi was the first company to receive its license directly in the past decade(quite a milestone). Map license, on the other hand, is easier to obtain — if you look at the bottom right of licensed base maps in China (Mapbox, Baidu, AutoNavi, etc.), you'll see something like «GS (2020) 123 号».

baidu map screenshot showing map license

Baidu map license

gcj-02 to wgs84. wgs84 to gcj02

As you can imagine, conversion goes like this: WGS-84GCJ-02BD-09 and backward. It is illegal to publish a formal conversion guide — each use of the coordinate shifting needs to be approved by SBSM.

However, you can find open-source implementations for this algorithm in different programming languages(e.g., eviltransform). In this article, i will use JavaScript implementation, but you easily will find Python, R, Go and etc. Check the Notes section of my article.

Our Chinese office uses Baidu Get Point Service to get BD-09 coordinates of the desired object. A screenshot is below. I then store this coordinates in the database and do conversion towards WGS-84 or GCJ-02, based on the user geolocation. For users in China you must use GCJ-02, remember?

baidu map screenshot showing bd-09 coordinates

BD-09 from http://api.map.baidu.com/lbsapi/getpoint/

I made an example with coordtransform library and Mapbox for you to play around. Copy BD-09 coordinates from this service and paste them here to see the result of transformation.

You can find source code for this example here

Which map provider to use for your users in China?

If you want to provide a smooth map experience to your users from Mainland China, you don't have a lot of options. Google Maps isn't working without a VPN. I love Baidu Maps in China. They provide excellent UI with a lot of handy GEO-data. I mean, look at the details.

But when it comes to the point where you should embed a map on your web page, the only choice left for me is Mapbox. Mapbox is an excellent alternative map service. It's legal and works perfectly fine without a VPN in China. Due to Chinese regulations, they serve 3 licensed base maps through mapbox.cn. All data inside China is shifted (from their mapping partner), all data outside China is unshifted (from their own data sets, including OSM).

Mapbox with a WGS-84 113.31924878632225, 23.12426152397713 coordinates (花城广场 in Guangzhou)

I tested api.mapbox.com endpoint with a global access token, and it worked perfectly fine from Guangzhou. But in the case with China, it's a gamble, so i suggest to obtain the access token from mapbox.cn.

Here is an algorithm for you. Is your visitor GeoIP in China?

  • Yes: show mapbox.cn embed with GCJ-02 coordinates
  • No: show mapbox.com embed with WGS-84 coordinates

I hope this post will save time for someone. I will probably add more information later since this is a complex and not well-understood topic. Drop me a line if you have any questions or suggestions.

The Latest

recv() failed (104: Connection reset by peer) while reading response header from upstream

python uwsgi error snippet

Geolocate the Location of an IP Address With Cloudflare Workers and JavaScript

javascript cloudflare geolocation workers

Detect a visitor's country and city by IP address with Cloudflare Workers and JavaScript.

JavaScript Document Onload + TypeScript version

javascript DOM snippet basics typescript
🗃 JavaScript Basics

Universal code-snippet to know when HTML is ready for modern browsers.

How to Create Jinja2 Filters in Flask

python flask jinja2 snippet

In this post, I'll talk about filters. Jinja2 has a list of built-in filters, and Flask leverages them.

How to Upload Files To Bunny.net Storage

python bunny_net storage snippet

Bunny.net is a well-known CDN and storage among developers. Here is my python snippet on how to upload a file to the storage.

How to Copy Text to Clipboard With Javascript

javascript DOM browser

Here is a short snippet on how to copy text to the clipboard with Javascript. Your visitors will thank you. Most likely not, but here we are.

Flask Boilerplate and Your Guide to Flask in 2023. With SQLAlchemy.

boilerplate open source flask

Flask-Backbone is my take to create an initial structure and a set of rules, so most of my flask projects are easy to support.

How to Import CSV Files to PostgreSQL with Pgfutter

csv postgresql

Sometimes I need to upload large CSV files to PostgreSQL. CSV file might have hundreds of columns, that's why i want a tool that can do some magic for me.

How to Upload Files to DigitalOcean Spaces with Python

digitalocean python

Snippet on how to upload files to DigitalOcean Spaces with boto3 and python.

The Definitive Guide To Sitemaps With Python

open source python

Sitemaps are important. Especially for big websites. It is always a good idea to develop your website with SEO in mind. Unfortunately, most developers ignore this part.