Quickstart

Cityweft API is designed to be user-friendly and provides a single endpoint to retrieve comprehensive 3D urban data.

Retrieve geometry

POST https://api.cityweft.com/v1/context

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

The polygon is the only required parameter in this API request.

Make sure to include it in the body to successfully retrieve the geometry

Name	Type	Description	Required
polygon	array of coordinates [lat,lon][]	Represents the user's area on the map	Yes
settings	object	An object of various settings Customizations	No
origin	coortinate [lat,lon]	Optional if you want to directly set the origin	No

Our API offers extensive customization options. Learn more at Customizations

Example API Request

Here is an example of a complete API request to retrieve a model in London using the polygon parameter:

{
  "polygon": [
    [51.5074, -0.1278],
    [51.5075, -0.1279],
    [51.5076, -0.1280],
    [51.5074, -0.1278]
  ],
  "settings": {
    "defaultRoofType": "flat",
    "defaultLevels": 2,
    "defaultLevelHeight": 4,
    "topographyModel": false,
    "geometry": ["buildings", "surface"]
  }
}

Polygon must be closed

Response Example

The response includes:

• geometry: An array containing different geometric elements. The currently supported geometryType values are meshes, elevationMaps, and nodes. Each geometry type is associated with specific data fields and descriptors detailing its characteristics.

• spacialReference: Depends on the selected CRS. More info at Coordinate Systems (CRS)

To access the desired geometry, use geometryType as a key to the geometry object. For example, if geometryType is "meshes", you will access the meshes with g[geometryType].

Cityweft's API supports various coordinate systems, more info at Coordinate Systems (CRS)

The coordinates follow the default format XZY: X points east, Z represents elevation, and Y points north.

The up axis is configurable via upAxis parameter, more info at Customizations

Cropping Scene

We provide an optional parameter to slice the model according to a polygon. By default, the returned geometry includes everything within the polygon and some extra geometry that may extend beyond its boundaries. Using the cropScene parameter, you can obtain a perfectly sliced model that matches your polygon precisely.

Scene cropping may affect API performance because additional geometry operations are required. The impact depends on the specifics of the area, but usually results in 10–20% more processing than usual.

Types of geometry

Buildings

Buildings Geometry

Meshes

Barriers

Walls & Fences Geometry

Meshes

Surface

Surface Geometry

Meshes

Infrastructure

Surface Information

Nodes

Topography

Topography geometry

ElevationMapsMeshes

200

{

    "origin": [lat, lng],  // origin point
    "geometry": [
        {
            "type": "buildings",
            "geometryType": "meshes",
            "meshes": [{
                "vertices": [x1, y1, z1, x2, y2, z2, ...],  // 3 components per vertex
            }, ...]
        },
        {
            "type": "surface",
            "geometryType": "meshes",
            "meshes": [{
                "vertices": [x1, y1, z1, x2, y2, z2, ...],
            }, ...]
        },
        {
            "type": "barriers",
            "geometryType": "meshes",
            "meshes": [{
                "vertices": [x1, y1, z1, x2, y2, z2, ...],
            }, ...]
        },
        
        // if 'topographyReturnType' is 'elevationMap'
        {
            "type": "",
            "geometryType": "elevationMaps",
            "elevationMaps": [{
                "info": {
                    "terrainSize": 392.3526603589423,
                    "segmentsCount": 256,
                    "position": {
                        "x": 434.17214010119096,
                        "y": -93.82671476012737
                    },
                    "elevationMap": [
                        245.6110076904297,
                        245.7227783203125,
                        245.7227783203125,
                        246.12277221679688,
                        247.12277221679688,
                        248.32278442382812,
                        ...
                    ]
                }
            }]
        }
    ]
}

⚠ When working with 3D visualization libraries, you may need to transform the coordinates to match your rendering engine's coordinate system. For example, some engines use Y-up instead of Z-up.