Customizations

Cityweft provides numerous opportunities for customizing output, allowing for tailored solutions that meet specific user requirements.

Customizing a POST Request

Below is a table outlining the key settings you can customize in a POST request:

Setting Parameter	Description	Type	Default
topographyModel	Includes or excludes the topography model from output	Boolean	false
disableSurfaceProjection	Don't project the surface geometry onto the terrain. The parameter will be changed soon in our to support images as the surfaces.	Boolean	false
defaultRoofType	Applies a default roof type when the actual type is unknown.	'flat' | 'hipped' | 'gabled' | 'onion' | 'dome' | 'round' | 'skillion' | 'mansard' | 'quadrupleSaltbox' | 'saltbox' | 'gambrel' | 'pyramidal'	flat
defaultLevels	Applies a default amount of levels the actual data is unknown.	Number	1
defaultLevelHeight	Applies a default level height when the actual height is unknown.	Float	4
topographyReturnType	Topography type. More info: Topography	'meshes' | 'elevationMap' | 'both'	meshes
crs	Specifies the coordinate reference system for geometry coordinates (e.g., "EPSG:3857" for Web Mercator, "UTM" to get UTM-zone-based coordinates, "LOCAL" for meter-based coordinates with a defined origin)	local EPSG:3857 UTM	local
geometry	An array specifying the desired geometry type is returned. Supported geometry types are buildings surface barriers topography infrastructure (or instances ) More detailed information about the geometry types: Geometry NB. Does not include topography by default.	Array	[ 'buildings', 'surface', 'barriers', 'instances', ]
upAxis	Specifies which axis represents the "up" direction in the generated 3D geometry. The parameter ensures that buildings, terrain, and other geometry elements are properly oriented for your target application, preventing the need for manual rotation after import. In the current API version, Y is the default.	'Y' | 'Z'	Y
cropScene	When provided, the API slices the city model to include only geometry inside the polygon boundary. It might slow down the response by 5-20% depending on the area.	Boolean	false
projectToTopography	When true, enables terrain projection for geometry (buildings, barriers, surface) without returning topography geometry. Useful when you need buildings to sit on terrain elevations but don't need the terrain mesh in the response.	Boolean

Example of settings object

settings: {
    defaultRoofType:  "gabled"
    defaultLevels: 2,
    defaultLevelHeight: 4.5,
    geometry: ["buildings", "infrastructure", "barriers"],
    cropScene: true
}

New!

Export Parameter

Overview

The export parameter enables direct export of geometry data to various 3D formats. When provided, the API processes the geometry and returns a download URL instead of the raw geometry JSON.

Usage

Include the export parameter in your request body with a format field:

{
  "polygon": [[lat1, lon1], [lat2, lon2], ...],
  "settings": { ... },
  "export": {
    "format": "obj"
  }
}

Supported Formats

The following export formats are supported:

• obj - Wavefront OBJ format (3D model file)

• 3dm - Rhino 3DM format (CAD file)

Response Structure

When the export parameter is provided, the API returns:

{
  "downloadUrl": "https://s3.amazonaws.com/bucket/preview-id/exports/file.obj",
  "spatialReference": {
    "crs": "local" | "EPSG:3857" | "UTM",
    "utmZoneEPSG": "EPSG:32633",
    "zoneString": "33N",
    "hemisphere": "north",
    "zone": 33,
    "letter": "T",
  }
}

More details about supported coordinate systems Coordinate Systems (CRS)

Response Fields

• downloadUrl (string): Direct URL to download the exported file. The file is stored in S3 and accessible via this URL.

• spatialReference (object): Contains coordinate system information:

  • crs (string): Coordinate Reference System used (local, EPSG:3857, or UTM)

  • utmZoneEPSG (string, optional): UTM zone EPSG code (e.g., EPSG:32633) when CRS is UTM

  • zoneString (string, optional): UTM zone identifier (e.g., 33N) when CRS is UTM

  • hemisphere (string, optional): Hemisphere (north or south) when CRS is UTM

  • zone (number, optional): UTM zone number when CRS is UTM

  • letter (string, optional): UTM zone letter when CRS is UTM

  • origin (array, optional): Origin coordinates [latitude, longitude] when CRS is local

Notes

• Export processing may take longer than standard geometry requests.

• The exported file is temporarily stored in on our servers. Ensure you download it promptly, as files may be cleaned up after a period.

• The spatialReference object helps you understand the coordinate system used in the exported file, which is important for correctly importing and using the geometry in your application.