No code
Georeference imagery
Familiarity with QGIS.

Georeferencing is the process of assigning geographic coordinates to a raster image in order 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 already great free, open-source tools which do this, such as QGIS.

historical map of multnomah county

Getting started

For this tutorial you’ll need:

  • QGIS. Check out the download instructions for more information and be sure you’ve installed the latest version.
  • An image to georeference. This tutorial uses a historical map of downtown Portland, Oregon in JP2 (a type of high resolution JPEG) format, which you’ll need to download. This image is clipped from a larger map of Multnomah County, Oregon provided by the Library of Congress.1

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

Congratulations on finishing the QGIS tutorial! You successfully transformed a JP2 image into a GeoTIFF and are ready to upload it to Mapbox as a tileset.

You can upload your GeoTIFF in Mapbox Studio or programmatically using the Mapbox Uploads API. For more information on uploading using Mapbox Studio, check out the Uploads section of the Mapbox Studio Manual. For more information on using the Uploads API, check out our API documentation.

Finished product

Congratulations on georeferencing your custom imagery and uploading 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.

View full map

Next steps

If you’d like to learn more about georeferencing, check out 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.)