# Quickstart
## Retrieve geometry
`POST` `https://api.cityweft.com/v1/context`
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**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 |
| No |
| `origin` | coortinate \[lat,lon] | Optional if you want to directly set the origin | No |
{% hint style="info" %}
Our API offers extensive customization options. Learn more at [customizations](https://cityweft.gitbook.io/docs/basics/customizations "mention")
{% endhint %}
#### Example API Request
Here is an example of a complete API request to retrieve a model in London using the `polygon` parameter:
```javascript
{
"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"]
}
}
```
{% hint style="info" %}
Polygon must be closed
{% endhint %}
**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](https://cityweft.gitbook.io/docs/basics/coordinate-systems-crs "mention")
{% hint style="info" %}
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]`.
{% endhint %}
{% hint style="info" %}
**Cityweft's API supports various coordinate systems, more info at** [coordinate-systems-crs](https://cityweft.gitbook.io/docs/basics/coordinate-systems-crs "mention")
{% endhint %}
{% 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** `upAxis` **parameter, more info at** [customizations](https://cityweft.gitbook.io/docs/basics/customizations "mention")
{% endhint %}
### 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.
{% hint style="info" %}
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**.
{% endhint %}
### Types of geometry
{% tabs %}
{% tab title="200" %}
```json
{
"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,
...
]
}
}]
}
]
}
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
⚠ 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.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://cityweft.gitbook.io/docs/getting-started/quickstart.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
