I'm having issues importing zones. How can I resolve this?

Question

Accepted Answer

Diagnose and resolve errors that occur when importing zones from a Shapefile or GeoJSON file into Altitude.

When importing zones using a Shapefile or GeoJSON file, individual zones or entire uploads may fail. After an import, Altitude sends an email listing any zones that failed, along with the error message for each. Use the error message to identify the cause and apply the appropriate resolution.

Note:

For steps on importing zones, refer to Importing zones.

File requirements

Altitude supports the following file formats for zone import:

Shapefile (uploaded as a ZIP archive containing the .shp, .shx, and .dbf files)
GeoJSON

The following requirements apply to all uploads:

Maximum file size: 200 MB
Supported geometry types: Polygon, MultiPolygon, Point (converted to a circular polygon at a fixed radius)
Coordinate system: WGS84 (EPSG:4326)
Coordinates must be 2D (latitude and longitude only - no Z/altitude values)
Zone names must be unique within the database

Note:

For uploads with more than 500 zones, split the file into smaller batches and upload each batch separately. This prevents rate limit errors that can cause an upload to stop partway through.

Error message reference

The following table maps common upload error messages to their cause and resolution.

Error message	Cause	Resolution
`Geography not supported: Unsupported geometry type.`	The zone polygon is kinked (self-intersecting), has a hole (donut shape), forms a figure-8 (bowtie shape), or uses an unsupported geometry type such as LineString.	Repair kinked geometries using QGIS. Redesign donut and bowtie shapes as simple polygons. Convert line features to polygon features before uploading.
`Invalid coordinates`	The file uses a projected coordinate system other than WGS84 (EPSG:4326), or contains 3D coordinates with a Z/altitude value.	Reproject the file to EPSG:4326 in QGIS or Python. Remove Z-coordinates before exporting.
`This file doesn't have any valid shape`	The Shapefile contains line features instead of polygon features.	Convert LineString geometry to polygons before uploading.
`APP rate limit exceeded for the current user. Please contact your APP support for more details.`	The upload exceeded the API rate limit. This typically occurs with large uploads or when multiple uploads run in quick succession.	Split the Shapefile into batches of 500 zones or fewer and upload each batch separately.
`Zone description was not provided or is already in use`	A zone name in the upload file matches a zone name that already exists in the database.	Use unique zone names. To preserve a customer-defined identifier, use the `CustomerZoneId` field instead of the zone name.

Coordinate system requirements (WGS84)

Altitude requires all uploaded zone geometries to use the WGS84 (World Geodetic System 1984) coordinate system, also known as EPSG:4326. Files that use a projected coordinate system - such as Web Mercator (EPSG:3857) - return an Invalid coordinates error, or cause zones to appear in the wrong geographic location with no error.

To reproject a file to WGS84 in QGIS:

Open the Shapefile in QGIS.
Right-click the layer and select Export > Save Features As.
In the CRS field, select EPSG:4326 - WGS 84.
Save the file and re-upload.

Note:

In Python, use the geopandas library with gdf.to_crs(epsg=4326) to reproject before exporting to a Shapefile or GeoJSON.

3D coordinates (Z-values)

Some GIS tools export Shapefiles and GeoJSON with 3D polygon geometry - adding an altitude or Z-coordinate to each vertex. Altitude expects 2D polygons (latitude and longitude only) and returns an Invalid coordinates error when Z-values are present.

To remove Z-values in QGIS:

Open the Shapefile in QGIS.
From the Processing menu, search for and run Drop M/Z values.
Export the output layer and re-upload.

Kinked and self-intersecting geometries

A kinked polygon is one where the boundary line crosses itself, creating a figure-8 or a shape with self-intersecting edges. Altitude does not accept kinked geometries and returns a Geography not supported: Unsupported geometry type. error for affected zones.

To identify and repair kinked geometries in QGIS:

Open the Shapefile in QGIS.
From the Vector menu, select Geometry Tools > Check Validity to identify which zones are invalid.
In the Processing Toolbox, run Fix Geometries to automatically repair self-intersections.
Re-export the file and re-upload.

Note:

If specific zones can't be repaired automatically, redraw them manually in QGIS or ArcGIS Pro.

Unsupported geometry types: donuts, bowties, and lines

The following geometry types return a Geography not supported: Unsupported geometry type. error and can't be auto-repaired:

Donut polygons - polygons with a hole cut out of the interior
Bowtie polygons - polygons whose boundaries cross to create two enclosed areas
LineString geometry - line features rather than closed polygons

For donut and bowtie shapes, redesign the affected zones as simple polygons without holes or self-intersections. If a ring-shaped coverage area is needed, represent it using multiple adjacent zones instead. For line features, convert them to closed polygons before uploading using Processing Toolbox > Lines to Polygons in QGIS.

Multipolygon zones in Traffic Analytics

Zones uploaded as MultiPolygon geometry are visible in Zone Management but don't appear in the Traffic Analytics zone selector. Traffic Analytics supports only single-polygon (Polygon) geometry. This affects zones that GIS tools have exported as MultiPolygon, even when the source shape appears to be a single polygon.

To convert MultiPolygon zones to single-polygon geometry in QGIS:

Open the Shapefile in QGIS.
In the Processing Toolbox, run Multipart to Singleparts.
Re-export the file and re-upload.
In Zone Management, delete the original MultiPolygon zones and replace them with the newly uploaded Polygon versions.

Note:

MultiPolygon support in Traffic Analytics is planned for a future release.

Zone ID whitespace

Trailing spaces in a zone's ZoneId value - spaces that appear at the end of the ID string - cause access check failures when the zone is used in an analysis. The zone uploads successfully but returns an access error when selected in an analysis.

Altitude assigns a unique system-generated ZoneId (for example, z-3h340uomjbk) to each zone at upload. This ID doesn't contain spaces. If a workflow passes a manually entered or externally sourced zone ID to the API, verify there are no trailing spaces in the ID string before submitting the request.

To store a customer-defined identifier alongside the system-generated ID, use the CustomerZoneId field during upload. This preserves the customer's own reference without overriding the ZoneId.

Uploading zones at scale

For uploads with large numbers of zones (typically 3,000 or more), keep the following in mind:

Split large Shapefiles into batches of 500 zones or fewer to avoid rate limit errors. Upload each batch separately and wait for one to complete before starting the next.
Stay under the 200 MB file size limit per upload.
Delete test zones from the database after testing. Accumulating large numbers of unused zones slows down Zone Management for all users on that database.
Use Zone Type to tag and filter large zone sets - this is the recommended way to organize zones when there's no grouping or folder structure.

Note:

For guidance on organizing and managing large zone sets in Altitude, refer to Managing zones.