Skip to content
A Python program which parses city data and Google location history files (in JSON), interpolates data point between flights and train rides, projects the data points onto a Mercator map, and then renders the data into a MPEG-4 video frame by frame.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



A Python script to render a video of a marker moving on a map showing where you've been, using your Google location history.

Getting Started

Install Python 3

Be sure to download the latest version of Python 3. After the installation, verify that both "python" and "pip" are available to you in the command line. You can do this by entering "which pip" to see if the Terminal returns a valid system path.

Clone Repository

Enter this command in the Terminal at the location of your choice to copy the Mappr project files there.

git clone

Install Prerequisites

Once inside of the Mappr directory, run the following command in Terminal.

pip install -r requirements.txt

All Python dependencies should install except for Basemap.

Installing Basemap

  1. Download the latest source code zip from the Basemap Github page. Un-zip the archive and navigate your Terminal to the "geos-x.x.x" folder inside of the "basemap-x.x.x" folder.

  2. You need to install the GEOS library by compiling it in C and writing the header files to a reasonable location.

export GEOS_DIR=<where you want the libs and headers to go>
# A reasonable choice on a Unix-like system is /usr/local, or
# if you don't have permission to write there, your home directory.
./configure --prefix=$GEOS_DIR
make; make install
  1. Go back up to the "basemap-x.x.x" folder and run the following.
python install
  1. Verify that Basemap successfully installed by importing the module. If Basemap successfully imports, the Terminal should return nothing.
python -c "from mpl_toolkits.basemap import Basemap"


This project specifically works using JSON data provided by Google. Location History is a service provided by Google for smartphone users to periodically log their GPS. You can read more here on how you can enable/disable the service and begin collecting data. To check if you have data available for use, visit your Google Timeline.

  1. Once you have verified that Google has GPS data from your device, visit the Google Takeout page to download your Location History. Be sure to uncheck all other services, and to set the Location History output to JSON. Then click the NEXT button, set the file type to .zip, and click CREATE ARCHIVE.
Screenshot of Google Takeout
Fig 1. Screenshot of Google Takeout
  1. Download the archived data (which should have been emailed to you). Unzip the archive, and navigate to the Location History folder, which should contain a single file within titled Location History.json.

  2. At this point, I recommend splitting the data file into various chunks so that the data is easier to handle, process in Python, and edit manually in text files. The split JSON files should then be moved to the Mappr directory, inside of the data folder.

  3. Inside of the Location History files, the GPS data is stored within JSON objects, with the first key for the timestamp in milliseconds. You can use online epoch converter tools to determine where certain date ranges start and end. For example, Year 2018 began at timestampMs=1514764800000 and Year 2017 began at timestampMs=1483228800000. It is recommended that you split the Location History JSON into chunked files within folders named by year, all within the data directory (such as mappr/data/2017, mappr/data/2018, etc.).


In the root Mappr folder, you can make changes to config.ini to change parameters necessary to create the video.


parameter type description
root Folder the root folder for all of your location and place data
year Folder the specific folder within the root location to use for rendering the video


parameter type description
debug Boolean to print verbose information about Mappr (recommended: yes)
scrub Boolean to scrub consecutive data points in one place (dependent on FPS) (recommended: yes)
interpolate Boolean to interpolate (animate) flight/train path between points (recommended: yes)


parameter type description
zoom Float The width (in degrees longitude / meridians) of the video viewport
use_arcgis Boolean to use ARCGIS map background (recommended: no)
use_etopo Boolean to use topographic map background (recommended: yes)
use_fill Boolean to use solid color-filled map background (recommended: yes)


parameter type description
fps Integer the number of frames (data points) per second in the output video
resolution_w Integer video width (in pixels)
resolution_h Integer video height (in pixels)
time_before Integer time to linger before beginning the animation (in seconds)
time_after Integer time to linger once the animation completes (in seconds)
time_zoom Integer time to zoom out once the animation completes (in seconds)
show_date Boolean to show the calendar date on the bottom left
show_status Boolean to show the location/status on the bottom left


parameter type description
water Hex Color used for oceans and lakes
grass Hex Color used for land
place Hex Color used for city/park/place markers
drive Hex Color used for the primary map trail (by driving or on foot)
train Hex Color used for map trails generated by train rides
flight Hex Color used for map trails generated by flights

Running Mappr

To run Mappr, simply enter the following into the Terminal.


The resulting video will be placed in the same location uniquely named using the current timestamp. Thus, running the script multiple times will not overwrite previous renderings.


  • Rendering 11871 data frames at 45 FPS with a resolution of 1920x1080 pixels takes about 6 hours on my laptop. I strongly suggest rendering at a much lower resolution (say, 640x360 pixels) first to see how the video looks, then to render the video once more with the maximum settings. If you have a GPU at your disposal, more power to you.

  • Use the following formula to estimate the duration of the video:

Time Before + (Total_Frames / FPS) + Time Zoom + Time After

Sample Output

Screenshot of Terminal Output
Fig 2. Screenshot of Terminal Output


This project is licensed under the MIT License - see the file for details


  • My parents for allowing me to globetrot
  • Nathan Handler for inspiring the project
You can’t perform that action at this time.