Coordinate conversions between (lat,lon) and web Mercator


What is the process for including a unit conversion library or somehow facilitating unit conversions in Bokeh enough to illustrate Bokeh’s mapping capability with the various tile providers?
This demo is ready to go except for the unit conversion.

More detail:
The mapping capability of Bokeh is much better than the documentation indicates. Here are a few needs or suggested updates:

(1) the primary doc page for mapping is lacking any clear listing of available tile providers. There are currently 10 open source map tile providers but there is no mention of them individually. A display of all map providers with their different styles seems appropriate and is surprisingly absent.

(2) Supporting mapping natively in Bokeh is good but it begs the need for a companion utility for converting coordinates to and from common map units. At a minimum (lat,lon) and Web Mercator conversions should be supported, or at least referenced enough to allow the documentation to illustrate the Bokeh mapping capability.

Some web Mercator and lat/lon unit conversion references are listed here:

  1. pyproj is a simple, mature, and capable library for unit conversions in multiple formats with multiple options.
  2. OpenStreetMap Mercator wiki has conversions written in multiple programming languages
  3. Web Mercator projection wiki has formulas and good explanations


Hi @comperem Thanks for circling back on this. First I wanted to mention that there was an update to the reference docs that list all the available tile providers, along with representative tiles:

That said I agree 100% that the narrative docs in the Users Guide could stand to be expanded. Some of that could be linking in to the reference guide or examples, and some of it could be new sections directly there.

Regarding pyproj, we have generally tried to keep our dependencies at a bare minimum but this one might be worth considering in order to make the Geo experience much better. Can you make two separate issues on GitHub?

  • Issue to discuss adding pyproj, and also what we would add to the API built on top of pyproj. (We could also consider vendoring code from the other links you mention but I’m personally less keen on vendoring more things). FWIW a minor number bump would be the time to add a dependency and 2.1 is coming up next

  • Issue to discuss ways to improve the current Geo Users guide page

And we can plan on getting your excellent example added when there is a plan forward for making the conversions simpler. Really appreciate all your pushing on this!


Thanks, this sounds like a good plan. I’ll begin on this shortly,


1 Like

for future reference, there is good discussion and working code for converting (lat,lon) units in decimal degrees to Web Mercator coordinates in meters here:

1 Like

Faced this issue last week. Used the simple function conversion mentioned in the discussion.