Cartagen Wiki
Importing Data

So, for example, Kate wanted to use a more recent dump of the Rio de Janiero map data from She navigated to Rio on that site, and opened the Export menu. She checked “OpenStreetMap XML Data” under Format to Export, and pressed “Export”.

A file called “map.osm.xml” was downloaded, with a lot of lines like this:

What to do next?

Well, you need to get a running copy of Cartagen Server, which you can find at Github (more info at Cartagen Server). Or you can use the existing demo install of Cartagen at

I’ll assume you’re running a local copy at “http://localhost:3000/”, a common port number for Rails applications. If you’re not, just substitute “” wherever you see it.

Move the file into a web-accessible folder. It’s convenient to just put it in the /public/ folder, and I created a subfolder called ‘rio’. So my file is accessible at:


You might try entering that URL in your browser just to be sure you can actually download the file from there. Now navigate to:


This should take a little while but it will download a new file called “map-osm.js”. (I’m changing this in the latest code to ‘.json’ but it’s not a big deal for now.)

You can now use this file as a standard static layer in Cartagen Client, with the following setup code, assuming you correct the lat/lng coordinates to display the map data you’ve downloaded:

			stylesheet: "style.gss",
			static_map: true,
			static_map_layers: [
			lat: 41.92,
			lng: 12.12

Batch caching from

For large datasets which are impractical to load statically, you might consider ‘tricking’ Cartagen into thinking it actually does have a dynamic server generating data tiles.

Cartagen dynamic data consists of files in the format (to follow the \OpenStreetMap Rails port modification). You can use wget or a browser to just download all the files relevant to your project, and store them at that relative path. (to learn more about geohashes, see the Geohash article on Wikipedia)

Visiting gets you to Rio de Janiero, but shows the geohash grid overlaid on the map.

So for example, if you want to display Rio de Janiero without depending on the main Cartagen server, you can see that the whole city is in the geohash “75cm” (that’s ‘7’, ‘5’, ‘c’, and ‘m’, not seventy-five centimeters).

Since Cartagen reads 6-digit geohash files, we might get all the geohash map data files that start with ‘75cm’, like 75cmaa, 75cmab, 75cmac, etc. You may correctly suppose that there are 36^2 of these, or 1,296 files. But most of these will be of the countryside and won’t be very big. You could write a script, or just start downloading them manually. I’d start around 75cm8z.json and work outward…

If you’re good with scripting you can probably do this faster.

Then just place these files in the same relative path from your Cartagen install. If you’re running Cartagen Server, thats:


And for Cartagen Client, it’s in the same folder as your index.html file:


Now, your Cartagen code can read these files with the setup code:

			stylesheet: "style.gss",
			static_map: false,
			lat: 41.92,
			lng: 12.12