Importing Map Features into EarthRanger

Map features represent geographic data on the EarthRanger map — boundaries, roads, rivers, and points of interest. They help field staff and managers understand where events and patrols are happening.

tip

Most import failures come from file preparation issues — incorrect projection, mixed geometry types, or missing name values. Work through Step 1 carefully before uploading.

---

How EarthRanger Organizes Map Features

EarthRanger uses two levels to organize map features:

• Display Categories — top-level groupings (e.g., Hydrography, Boundaries)
• Feature Types — nested under Display Categories; each represents a specific layer (e.g., Primary Rivers, Park Zones)

Both appear under Map Layers in the Admin and Operator interfaces.

---

Overview

1. Prepare and optimize your geospatial file
2. Create or confirm the Display Category and Feature Type
3. Upload the file in EarthRanger Admin
4. Verify the import
5. Customize appearance

---

Step 1: Prepare Your File

EarthRanger accepts Shapefile (.shp) and GeoJSON (.geojson) formats.

File requirements checklist

Before uploading, confirm all of the following:

• Format: .shp (zipped) or .geojson
• Projection: EPSG:4326 (WGS 84)
• One geometry type per file: points, lines, or polygons — not mixed
• One layer per file
• Name column: every feature has a unique, non-null value in a dedicated attribute column (EarthRanger uses this to label features on the map)

Shapefile: create a zip archive

EarthRanger requires the following component files in a single .zip:

File	Purpose
.shp	Geometry
.dbf	Attribute data
.shx	Shape index
.prj	Projection definition
.cpg	Character encoding

caution

Do not nest the files inside a subfolder within the zip — place them at the root level.

GeoJSON:

GeoJSON files are self-contained and can be uploaded directly.

Check and fix your projection in QGIS

EarthRanger requires EPSG:4326. To confirm and reproject if needed:

1. Right-click the layer in the Layers Panel and select Properties > Information.
2. If the CRS is not EPSG:4326, go to Vector > Data Management Tools > Reproject Layer, set the target CRS to EPSG:4326, and save the output.

Optimize for map performance

Large or complex files slow map loading for all users. Before uploading:

Simplify geometry In QGIS: Vector > Geometry Tools > Simplify Geometries. Start with a tolerance of 0.0001 degrees and visually check that the output still looks correct. Reduce further if needed.

Remove unused attributes In QGIS, open the Field Calculator or use Processing > Field(s) calculator to keep only the columns you need in EarthRanger. The name column is required; everything else is optional.

Split by Feature Type If features belong in different Feature Types (e.g., primary rivers vs. secondary rivers), use separate files — even if they share the same geometry type.

---

Step 2: Create the Display Category and Feature Type

Before uploading, make sure the correct Feature Type exists in EarthRanger Admin. Feature Types control how features appear on the map — stroke color, fill, opacity, icon, and so on — and also define which attribute column EarthRanger uses to label features. Each Feature Type sits under a Display Category, which groups related layers together in the Map Layers panel.

1. In EarthRanger Admin, go to Map Layers > Feature Types.
2. Check whether a suitable Feature Type already exists for this layer.
3. If you need a new Feature Type, click Add Feature Type and fill in:
   • Name — clear and descriptive (e.g., Primary Rivers, Park Boundaries)
   • Display Category — select an existing category or create a new one using the + icon
   • Styling — configure how features appear on the map. Options depend on geometry type:
     • Lines: stroke color, stroke width, opacity
     • Polygons: fill color, stroke color, stroke width, opacity
     • Points: icon image URL, icon size
4. Click Save.

---

Step 3: Upload the File

1. In EarthRanger Admin, go to Map Layers > Feature Import Files.

2. Click Add Feature Import File.

3. Complete the form:

   Field	What to enter
   File type	Select shapefile or GeoJSON
   Spatial File Name	A recognisable name for this import
   Description	Optional — useful for noting the data source or date
   Data	Click Choose File and select your .zip (Shapefile) or .geojson
   Feature Type	Select the Feature Type from Step 2, or create one with the + icon
   Name field	Select the attribute column from the file containing unique feature names

4. Click Save.

caution

The Name field must reference an attribute where every feature has a unique, non-null value. If values are missing or duplicated, features may fail to import or appear on the map with incorrect labels.

---

Step 4: Verify the Import

1. Go to the main EarthRanger site and open the Map Layers tab.
2. Under Features, find your Display Category and toggle on the Feature Type you just imported.
3. If features don't appear, try refreshing the browser — large imports can take a moment to process.

If something looks wrong:

Problem	Likely cause	Fix
No features visible	Wrong projection	Reproject to EPSG:4326 and re-upload
Features in wrong location	Lon/lat swap or datum mismatch	Check source data; re-export from QGIS
Features visible but no labels	Name field mismatch	Check the Name Attribute on the Feature Type matches the column name exactly
Slow map loading	Large or complex geometry	Simplify geometry in QGIS and re-upload
Missing features	Null values in name column	Fix nulls in the attribute table before re-uploading

---

Step 5: Customize Appearance

After importing, you can adjust how features look on the map in Map Layers > Feature Types:

• Polygons and lines — fill color, stroke color, stroke width, opacity
• Points — icon size, image URL

---

Alternative: Draw Features Directly in EarthRanger

If you don't have a geospatial file, you can draw features manually in EarthRanger Admin. This is useful for one-off boundaries or markers.

For a full walkthrough, see: Draw and Add Map Features in EarthRanger Admin