All docsHelpTutorialsGeoreference imagery

Georeference imagery

Georeferencing is the process of assigning geographic coordinates to a raster image to define its location in the world based on a map coordinate system. If you've ever used Mapbox Satellite you've already worked with georeferenced images. This is because each raster tile in Mapbox Satellite is an image that's been assigned a particular location in the world.

There are lots of reasons why you may want to georeference your own custom raster images. For example, you might receive satellite imagery in a non-spatial image format, you may need to compare historic maps to current maps, or you might be building an interactive map of a fictional place for a gaming app.

For this tutorial, you'll be georeferencing a JPEG image of historical downtown Portland, Oregon using QGIS, a free open-source Geospatial Information System (GIS). Once you've exported your image to GeoTIFF format in QGIS, you'll upload it to your Mapbox account as a tileset. Mapbox does not provide built-in tools to georeference your imagery because there are free, open-source tools that do this, such as QGIS.

historical map of Multnomah county

Getting started

For this tutorial you'll need:

Download image

Georeference your image in QGIS

First you'll need to follow the instructions in the Georeferencing Topo Sheets and Scanned Maps tutorial for QGIS. This introduction to georeferencing will guide you through the process using the most recent version of QGIS. Make sure you use the image you downloaded at the beginning of this tutorial rather than the image provided in the QGIS tutorial and EPSG:900913 or EPSG: 3857 (Web Mercator) as your coordinate reference system (CRS).

Once you've finished georeferencing your image, make sure to save your GeoTIFF file as downtown-pdx.tif in a convenient location for when you upload it to Mapbox.

Upload to Mapbox as a tileset

You successfully transformed a JP2 image into a GeoTIFF and are ready to upload it to Mapbox as a tileset using either Mapbox Studio or the Mapbox Uploads API.

Finished product

You georeferenced your custom imagery and uploaded it to your Mapbox account. Now that your imagery is in raster tile format, you can add it to any of your Mapbox projects as a raster tile source. Here's an example of adding your imagery to a map using Mapbox GL JS.

<!DOCTYPE html>
<html lang="en">
<meta charset="utf-8" />
<title>Demo: Georeference imagery</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script src=""></script>
<script src=""></script>
body {
overflow: hidden;
margin: 0;
padding: 0;
#map {
position: absolute;
top: 0;
bottom: 0;
width: 100%;
body * {
-webkit-touch-callout: none;
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
.map {
position: absolute;
top: 0;
bottom: 0;
width: 100%;
<div id="comparison-container">
<div id="streets" class="map"></div>
<div id="historic" class="map"></div>
var style1 = 'cj173dx4q001l2so0pyozfnuf';
var style2 = 'cj173cqom001s2smz3yyvto8z';
// add the map
mapboxgl.accessToken = '<your access token here>';
var streetsMap = new mapboxgl.Map({
container: 'streets',
style: 'mapbox://styles/examples/' + style1,
center: [-122.58862880207116, 45.53387784078623],
zoom: 12.6
var historicMap = new mapboxgl.Map({
container: 'historic',
style: 'mapbox://styles/examples/' + style2
var container = '#comparison-container';
var map = new mapboxgl.Compare(streetsMap, historicMap, container);

Next steps

To learn more about georeferencing, read QGIS's advanced Georeferencing Aerial Imagery guide to extend your georeferencing skills.

1 Habersham, Robert A, and Julius Bien & Co. Map of Multnomah County, Oregon: compiled from county records, railroad surveys, and other official data. [New York: Julius Bien & Co Photo. Lith, 1889] Map. Retrieved from the Library of Congress, (Accessed April 18, 2017.)