Paul Ramsey • May 17, 2018

CARTO in QGIS using OGR

You can use OGR to move data into and out of CARTO. And you can use QGIS to view and edit layers supported by OGR. So it would stand to reason that you should be able to use QGIS to view and edit CARTO data directly: but how?

Here’s one quick and dirty way to connect QGIS to your CARTO layers.

CARTO_API_KEY

First, you need to make sure QGIS can access your layers using a CARTO master API key. The OGR driver reads system tables, so it requires the master key to operate.

Open the QGIS Preferences menu.
Navigate to the System panel.
Scroll to the Environment area.
Add a new environment variable, CARTO_API_KEY.
Put your API key in the “Value” field.
Press the OK button.
Shut down QGIS and re-open it to bring the new environment variable into effect.

Now we need to record the connection information OGR will need to access CARTO, and put that information into a “VRT” file.

VRT File

A VRT file defines connection information and layer names so that an OGR client (like QGIS) can easily connect to a source without reading a lot of metadata. Here’s an example minimal VRT file with two layers defined:

<OGRVRTDataSource>
    <OGRVRTLayer name="subway_stations">
        <LayerSRS>EPSG:4326</LayerSRS>
        <SrcDataSource>Carto:pramsey</SrcDataSource>
        <SrcLayer>nyc_subway_stations</SrcLayer>
		<GeometryType>wkbPoint</GeometryType>
    </OGRVRTLayer>
    <OGRVRTLayer name="streets">
        <LayerSRS>EPSG:4326</LayerSRS>
        <SrcDataSource>Carto:pramsey</SrcDataSource>
        <SrcLayer>nyc_streets</SrcLayer>
		<GeometryType>wkbLineString</GeometryType>
    </OGRVRTLayer>
</OGRVRTDataSource>

This file reads CARTO tables nyc_subway_stations and nyc_streets and exposes them to QGIS using the names “subway_stations” and “streets”.
The <LayerSRS> should always be EPSG:4326, as that is the system CARTO always uses.
The <SrcDataSource> is of the form “Carto:username”, where “Carto” tells OGR what driver to use and the “username” is your CARTO user name. For multi-user accounts, “username” must be the user name and not the organization name.
The <GeometryType> is optional, but ensures that OGR knows whether the input layer is a point, line or polygon.

You can test your VRT file using the ogrinfo utility. You should be able to run ogrinfo and get a listing of layers back, for example:

# ogrinfo carto.vrt 

INFO: Open of `carto.vrt'
      using driver `OGR_VRT' successful.
1: subway_stations
2: streets

Once you have a working VRT file, you can add the file as a layer in QGIS!

Adding the Layer

After you’ve set up your API key and authored your VRT file, go to Layer > Add Layer > Add Vector Layer… in QGIS, and select your VRT as the source vector dataset, using a “File” source type.

If your VRT includes multiple layer definitions, you’ll be asked to select which layers (or all of them) that you want to add. Then you should be able to see the data draw on your QGIS map!