Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
Feb 15, 2013
Feb 15, 2013

PhoneGap + MapBox + Leaflet: Offline Mapping Proof of Concept

Demo Android app available for download here

##Usage Simply enter a MapBox map id (looks like or several (separated by a comma) and click the "Download Tiles" button. You can click "Clear Tiles" to clear the tiles.

##Problem & Approach I built this app because I needed a way to do offline mapping in a PhoneGap app. Scott Davis had put together a solution that used PhoneGap, MapBox (TileMill+mbTiles), and Leaflet, but this requires the SQLite plugin for PhoneGap.

Because PhoneGap Build doesn't support that plugin yet, I thought I'd try the brute-force strategy of downloading the raw tiles from the MapBox API, saving them locally through the PhoneGap File API and then pointing a Leaflet TileLayer at the directory.

This isn't the ideal solution, of course, because there are a lot of advantages to using mbTiles (highly compressed storage is the big one). However, I didn't want to give up PhoneGap Build... so I gave this a shot. And it works!

Here is the order of operations:

  • The user specifies some MapBox map ids and presses "Download"
  • tiles.js calculates the tile URLs for the pyramid of tiles centered on the default lat/lng of Louisville, KY (home, sweet home)
  • files.js downloads all those tiles to a local directory
    • tiles/{map_id}/{z}/{x}/{y}.png
  • map.js points Leaflet at the appropriate directories, initializes a layer chooser, and displays the map

This is my first contribution to open source software and I hope this code is helpful to you. I certainly learned a lot making it!

##Code Structure

  • libs/ - 3rd party libraries
  • utils/ - core JS code for doing offline mapping
    • file.js - download/delete many files at once
    • tile.js - get tile URLs for an area
    • map.js - point Leaflet at the correct tiles and display map
  • config.xml - configuration details for PhoneGap Build
  • index.html - PhoneGap opens this page. Just a map and some UI elements
  • main.js - some UI and bookkeeping code for this particular proof of concept

##Extending this code This project is solely intended to be a proof of concept. The core utilities are in the utils directory - most of the functions are documented and should be fairly straightforward to understand.

To actually make a mobile "app" out of this code, simply fork this project, create a PhoneGap Build account and then tell PhoneGap Build to pull from your git repo.

A few "gotchas" to look out for:

  • Domain whitelisting in config.xml - make sure you allow access to MapBox servers
  • You have to sign up for a MapBox Basic account ($5/month) to have access to the satellite map tiles API. Terrain and streets should be free though.


Proof of concept for offline mobile mapping with PhoneGap, Leaflet, and MapBox



No releases published


No packages published
You can’t perform that action at this time.