Coordinate Systems (CRS)

The Cityweft API supports three different coordinate reference systems to accommodate various use cases and integration requirements. Choose the appropriate CRS based on your use case

CRS	Description	Use Case	Coordinates
local Local Coordinate System	Relative to origin point	Small sites, game engines, visualization	Meters from origin
EPSG:3857 Web Mercator (EPSG:3857)	Web Mercator	Web mapping, global applications	Global Web Mercator
UTM Universal Transverse Mercator (UTM)	Universal Transverse Mercator	GIS, surveying, precise mapping	UTM zone coordinates

Local Coordinate System

Parameter: crs: "local" (default)

Description

The local coordinate system positions all geometry relative to a specified origin point. This creates a localized coordinate space with the origin at (0,0,0).

Characteristics

• Origin: User-defined point or first polygon vertex

• Units: Meters

• Coordinate Space: X-right, Y-forward/back, Z-up (depending on upAxis parameter)

• Range: Suitable for sites up to ~10km radius

When to Use

• ✅ Game engines (Unity, Unreal)

• ✅ 3D visualization applications

• ✅ Small to medium-sized sites

• ✅ When you need simple, relative coordinates

• ❌ Large geographical areas (>10km)

• ❌ When integrating with GIS systems

Output format:

{
  "spatialReference": {
    "crs": "local",
    "origin": [52.5200, 13.4050]
  },
  "geometry": [...] // Coordinates relative to origin
}

Web Mercator (EPSG:3857)

Parameter: crs: "EPSG:3857"

Description

Web Mercator is the standard projection used by most web mapping services (Google Maps, OpenStreetMap, Mapbox). Coordinates are in the global Web Mercator coordinate system.

Characteristics

• Origin: Global (0,0) at the intersection of the equator and the prime meridian

• Units: Meters (keep in mind the Mercator distortion)

• Projection: Spherical Mercator

When to Use

• ✅ Web mapping applications

• ✅ Integration with web map services

• ✅ Global or continental-scale projects

• ✅ When working with existing Web Mercator data

• ❌ High-precision surveying

• ❌ Polar regions (>85° latitude)

Output format:

{
  "spatialReference": {
    "crs": "EPSG:3857"
  },
  "geometry": [...] // Global Web Mercator coordinates
}

Universal Transverse Mercator (UTM)

Parameter: crs:"UTM"

Description

UTM divides the world into 60 zones, each 6° wide (with some exceptions like Norway mainland and Svalbard). The system automatically detects the appropriate UTM zone based on your polygon's location and provides high-precision coordinates.

Characteristics

• Origin: Zone-specific (500,000m Easting, 0m or 10,000,000m Northing)

• Units: Meters

• Projection: Transverse Mercator per zone

• Accuracy: Sub-meter precision within zone

• Auto-detection: Zone calculated from the polygon center

When to Use

• ✅ GIS applications (QGIS, ArcGIS)

• ✅ Surveying and engineering

• ✅ High-precision mapping

• ✅ CAD integration

• ✅ Construction and infrastructure projects

• ❌ Cross-zone projects (spanning >6° longitude)

• ❌ Simple visualization needs

Output format

{
  "spatialReference": {
    "crs": "UTM",
    "utmZoneEPSG": "EPSG:32633",
    "zoneString": "33N",
    "hemisphere": "N",
    "zone": 33,
    "letter": "N"
  },
  "geometry": [...] // UTM zone coordinates
}

Integration Compatibility

Software Type	Recommended CRS
Game Engines	local
Web Maps	EPSG:3857
GIS Software	UTM
CAD Software	UTM or local
3D Modeling	local

Error Handling

• Invalid CRS values default to 'local'

• UTM zones are auto-calculated; manual specification is not required

• Cross-zone polygons use the zone of the polygon centroid

Performance Notes

• Local & EPSG:3857: Fastest processing, minimal coordinate transformations

• UTM: Slightly slower, requires zone calculation and transformation