> For the complete documentation index, see [llms.txt](https://cityweft.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cityweft.gitbook.io/docs/getting-started/quickstart.md).

# Quickstart

Generate your first 3D city model in five minutes — one endpoint, one request.

The Cityweft API has a single endpoint that generates a complete 3D city model — buildings, ground surfaces, barriers, terrain, and infrastructure — for any area you define:

<mark style="color:green;">`POST`</mark> `https://api.cityweft.com/v1/context`

{% stepper %}
{% step %}

### Get your API key

Generate a key on the **API & Plugin Keys** page of the [Cityweft dashboard](https://app.cityweft.com) (keys start with `cw_`). Full walkthrough: [Getting your API key](/docs/plugins/getting-your-api-key.md).

Every request needs two headers:

| Header          | Value                 |
| --------------- | --------------------- |
| `Content-Type`  | `application/json`    |
| `Authorization` | `Bearer YOUR_API_KEY` |
| {% endstep %}   |                       |

{% step %}

### Define your area

The only required parameter is `polygon` — the area to generate, as `[latitude, longitude]` pairs:

* The polygon must be **closed**: first and last points identical.
* Maximum area per request is **10 km²**.

```json
{
  "polygon": [
    [51.5115, -0.1230],
    [51.5115, -0.1195],
    [51.5140, -0.1195],
    [51.5140, -0.1230],
    [51.5115, -0.1230]
  ]
}
```

{% endstep %}

{% step %}

### Make the request

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.cityweft.com/v1/context \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CITYWEFT_API_KEY" \
  -d '{
    "polygon": [
      [51.5115, -0.1230],
      [51.5115, -0.1195],
      [51.5140, -0.1195],
      [51.5140, -0.1230],
      [51.5115, -0.1230]
    ],
    "settings": {
      "geometry": ["buildings", "surface", "barriers", "topography"]
    }
  }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const payload = {
  "polygon": [
    [51.5115, -0.1230],
    [51.5115, -0.1195],
    [51.5140, -0.1195],
    [51.5140, -0.1230],
    [51.5115, -0.1230]
  ],
  "settings": {
    "geometry": ["buildings", "surface", "barriers", "topography"]
  }
};

const response = await fetch("https://api.cityweft.com/v1/context", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${CITYWEFT_API_KEY}`,
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

response = requests.post(
    "https://api.cityweft.com/v1/context",
    headers={"Authorization": f"Bearer {os.environ['CITYWEFT_API_KEY']}"},
    json={
        "polygon": [
            [51.5115, -0.1230],
            [51.5115, -0.1195],
            [51.5140, -0.1195],
            [51.5140, -0.1230],
            [51.5115, -0.1230],
        ],
        "settings": {
            "geometry": ["buildings", "surface", "barriers", "topography"]
        },
    },
)

data = response.json()
```

{% endtab %}
{% endtabs %}

Try it live with your own key on the [API Reference](/docs/getting-started/api-reference.md) page — we recommend a **development key** for testing — and see every available option in [Customizations](/docs/basics/customizations.md). To receive a ready-to-open file instead of JSON, see [Exports](/docs/basics/exports.md).
{% endstep %}

{% step %}

### Use the response

The response contains:

* **`origin`** — the `[latitude, longitude]` the local coordinate frame is anchored to.
* **`geometry`** — one group per requested type. Read each group's data through its `geometryType` (`meshes`, `elevationMaps`, `nodes`, or `polylines`): if `geometryType` is `"meshes"`, the data is at `group.meshes`.
* **`spatialReference`** — the coordinate system of the output. More info: [Coordinate Systems (CRS)](/docs/basics/coordinate-systems-crs.md)
* **`attributions`** — credit lines for the data behind the scene; render them when you display or redistribute the output.
* **`dataAccess`** — present when premium country data wasn't available to your plan and the response fell back to worldwide data. More info: [Customizations](/docs/basics/customizations.md)

To render the model, follow the [Three.js Quick Guide](/docs/getting-started/three-quick-guide.md).
{% endstep %}
{% endstepper %}

#### Response example

{% tabs %}
{% tab title="200" %}

```json
{
  "origin": [51.5115, -0.1230],
  "geometry": [
    {
      "type": "buildings",
      "geometryType": "meshes",
      "meshes": [
        {
          "vertices": [12.4, 0.0, -8.1, 12.4, 21.5, -8.1, "..."],
          "descriptor": {
            "type": "building",
            "buildingHeight": 21.5,
            "datasetName": "Global Buildings - Mapped"
          }
        }
      ]
    },
    {
      "type": "surface",
      "geometryType": "meshes",
      "meshes": [
        {
          "vertices": ["..."],
          "descriptor": { "type": "asphalt" }
        }
      ]
    },
    {
      "type": "topography",
      "geometryType": "elevationMaps",
      "elevationMaps": [
        {
          "info": {
            "width": 611.49,
            "height": 611.49,
            "segmentsWidth": 256,
            "segmentsHeight": 256,
            "moveVector": { "x": 434.17, "y": -93.82 }
          },
          "elevationMap": [245.61, 245.72, 246.12, "..."]
        }
      ]
    }
  ],
  "spatialReference": { "crs": "local", "origin": [51.5115, -0.1230] },
  "attributions": [
    {
      "id": "source-id",
      "name": "Data source name",
      "text": "Credit line to display",
      "license": "License name",
      "url": "https://...",
      "required": true
    }
  ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**The coordinates follow the default format XZY: X points east, Z represents elevation, and Y points north.** The up axis is configurable via the `upAxis` setting — more info: [Customizations](/docs/basics/customizations.md). When importing into a 3D engine, you may need to transform coordinates to match its convention (Y-up vs Z-up).
{% endhint %}

### Cropping the scene

By default, the returned geometry includes everything within the polygon **and** some extra geometry that may extend beyond its boundaries. With `"cropScene": true` in `settings`, the model is sliced precisely along your polygon.

<figure><img src="https://2449447963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2ahel6HN9zgEzJ1vY9kr%2Fuploads%2F3NEJUpq4nO1TgeGd4DKq%2FScreenshot%202025-09-09%20at%2013.41.41.png?alt=media&#x26;token=7bf34c34-8fd2-4a54-9fef-3c2c3d16ceb3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Scene cropping usually adds **10–20% processing time**, depending on the area.
{% endhint %}

### Types of geometry

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th><select multiple><option value="GXJDE1CloO2K" label="Meshes" color="blue"></option><option value="P8roCyk5SLOJ" label="Nodes" color="blue"></option><option value="00g40lPSezeL" label="ElevationMaps" color="blue"></option><option value="PolyLn123456" label="Polylines" color="blue"></option></select></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Buildings</strong></td><td>Buildings Geometry</td><td><span data-option="GXJDE1CloO2K">Meshes</span></td><td><a href="/docs/geometry/buildings.md">Buildings</a></td><td><a href="https://2449447963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2ahel6HN9zgEzJ1vY9kr%2Fuploads%2FED6oIRABg7A5kmFBPiDx%2Fthumbnail%20(1).png?alt=media&amp;token=28d8bc11-444c-4815-ad2c-9664e728b42f">thumbnail (1).png</a></td><td></td></tr><tr><td><strong>Surface</strong></td><td>Surface Geometry</td><td><span data-option="GXJDE1CloO2K">Meshes</span></td><td><a href="/docs/geometry/surface.md">Surface</a></td><td><a href="https://2449447963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2ahel6HN9zgEzJ1vY9kr%2Fuploads%2F1O5eVQfaMEe4m5xTKwkW%2FScreenshot%202026-08-28%20at%2011.52.57.png?alt=media&amp;token=d0330afc-9ce4-48f9-90cb-b2174d41d4f4">Screenshot 2026-08-28 at 11.52.57.png</a></td><td></td></tr><tr><td><strong>Surface Lines</strong></td><td>Centerlines &#x26; Outlines</td><td><span data-option="PolyLn123456">Polylines</span></td><td><a href="/docs/geometry/surface-lines.md">Surface Lines</a></td><td><a href="https://2449447963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2ahel6HN9zgEzJ1vY9kr%2Fuploads%2FZPwTZuFAxwcxiOiBY2HW%2FScreenshot%202026-08-28%20at%2000.30.29.png?alt=media&amp;token=259c9ec5-66ac-4c08-a47f-188aa1d9946b">Screenshot 2026-08-28 at 00.30.29.png</a></td><td></td></tr><tr><td><strong>Barriers</strong></td><td>Walls &#x26; Fences Geometry</td><td><span data-option="GXJDE1CloO2K">Meshes</span></td><td><a href="/docs/geometry/barriers.md">Barriers</a></td><td><a href="https://2449447963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2ahel6HN9zgEzJ1vY9kr%2Fuploads%2Fc9EZsiHGfKMiXQIY83UE%2Fscene-1749156254236.png?alt=media&amp;token=6a7ba616-b45d-4094-8baa-a538bcbd8436">scene-1749156254236.png</a></td><td></td></tr><tr><td><strong>Infrastructure</strong></td><td>Point Instances</td><td><span data-option="P8roCyk5SLOJ">Nodes</span></td><td><a href="/docs/geometry/infrastructure.md">Infrastructure</a></td><td><a href="https://2449447963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2ahel6HN9zgEzJ1vY9kr%2Fuploads%2Fk1NAhPG61naImwNJ5GJ4%2FScreenshot%202026-07-06%20at%2010.52.19.png?alt=media&amp;token=ff414549-4e2b-4f2b-b001-b2ee88d80f9f">Screenshot 2026-07-06 at 10.52.19.png</a></td><td></td></tr><tr><td><strong>Topography</strong></td><td>Topography geometry</td><td><span data-option="00g40lPSezeL">ElevationMaps, </span><span data-option="GXJDE1CloO2K">Meshes</span></td><td><a href="/docs/geometry/topography.md">Topography</a></td><td><a href="https://2449447963-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2ahel6HN9zgEzJ1vY9kr%2Fuploads%2F08PUIEcMuj5jtD73TJ7e%2Fimage%20(1).webp?alt=media&amp;token=386c2f7e-88a4-404e-9dbb-3bc33f7eb386">image (1).webp</a></td><td></td></tr></tbody></table>