---
title: Landuse
source: https://infrared.city/docs/sdk/1.0/python/landuse/
---

# Landuse

Classified Overture land use for a polygon area.

Reads the Overture `land_use` features over a polygon and maps their free-text classes onto the shared Infrared land-use categories. See `infrared_sdk.landuse.service`.

## OVERTURE_LANDUSE_TYPE  `module-attribute`

```python
OVERTURE_LANDUSE_TYPE = 'land_use'
```

Name of the Overture collection the land-use read uses (`"land_use"`).

## LandUseServiceClient

Bases: `ScrubbedSessionState`

Client for classified Overture land use.

`api_key`, `base_url`, `gateway_base_url` and `telemetry` are accepted for construction compatibility with the other service clients and are unused: this client sends no request of its own. The public data read goes through the shared Overture range reader, and the classification runs in-process.

### logger  `instance-attribute`

```python
logger: Logger = logger
```

Logger the client reports progress to.

### base_url  `instance-attribute`

```python
base_url: str = base_url
```

Base URL accepted for construction compatibility; never contacted.

### close

```python
close() -> None
```

Release the client's resources. Kept for API compatibility.

### get_area

```python
get_area(
polygon: dict,
*,
timeout: int = 60,
total_timeout: int = 600,
max_workers: int = 10,
overture_release: Optional[str] = None,
analysis_type: Optional[str] = None,
on_progress: Optional[Callable[[TileProgress], None]] = None,
max_tiles_override: Optional[int] = None,
) -> AreaLandUse
```

Read and classify Overture land use over `polygon`.

The area is read once: as a single rectangle up to 4 km2, and above that as a grid of roughly 2 x 2 km read chunks, the same shape the ground-material read uses.

There is no partial answer. A read that fails, or a deadline that expires, raises `TiledRunError`, whose `failed_tiles` names the chunks. A land-use answer covering an unknown part of the polygon would be indistinguishable from one covering all of it, and the categories would be silently wrong rather than visibly absent.

The one failure that is not wrapped is `GeodataDependencyError`: a missing optional `[geodata]` extra is an install problem, not a failed read, and it reaches your own `except` clause unchanged.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `polygon` | `dict` | GeoJSON Polygon. | *required* |
| `timeout` | `int` | Per-request budget in seconds (default 60), trimmed to what is left of `total_timeout`. | `60` |
| `total_timeout` | `int` | Wall-clock deadline over the whole read, in seconds (default 600). | `600` |
| `max_workers` | `int` | Accepted for signature compatibility with the sibling area reads and has no effect: the Overture read is one scan over the area, so there is nothing to run in parallel. | `10` |
| `overture_release` | `str` | Pin the read to an Overture release. The public index pointer moves daily; pass back `AreaLandUse.overture_release` to reproduce a run. | `None` |
| `analysis_type` | `str` | The analysis the read margin follows. `None` reads the widest margin, which is valid for every analysis. | `None` |
| `on_progress` | `callable` | Called once per chunk read, with a `TileProgress`. | `None` |
| `max_tiles_override` | `int` | Raise the tile ceiling for the grid that fixes the read rectangles. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `[AreaLandUse](#infrared_sdk.landuse.AreaLandUse)` | The classified FeatureCollection and what the classification saw. |

Raises:

| Type | Description |
| --- | --- |
| `PolygonValidationError` | If `polygon` is not a valid GeoJSON Polygon, if the grid it needs exceeds the tile ceiling, or if `max_tiles_override` is not a non-negative integer. |
| `TiledRunError` | If the read fails or `total_timeout` expires. |
| `GeodataDependencyError` | If the optional `[geodata]` extra is not installed. |

## AreaLandUse  `dataclass`

Classified Overture land use for a polygon area.

### features  `instance-attribute`

```python
features: dict
```

GeoJSON FeatureCollection. Each feature carries `name`, `overture_class` (the source spelling, kept so you can audit the mapping) and `category`, one of the shared Infrared land-use categories.

### polygon  `instance-attribute`

```python
polygon: dict
```

The input GeoJSON polygon.

### total_features  `instance-attribute`

```python
total_features: int
```

Land-use features READ, before classification.

### categorized  `instance-attribute`

```python
categorized: int
```

Features that survived into `features`. Below `total_features` when a feature carried no usable geometry: those are dropped. The difference is the loss, and it is reported rather than left to be inferred from two lengths.

### category_counts  `class-attribute` `instance-attribute`

```python
category_counts: Dict[str, int] = field(default_factory=dict)
```

Feature count per category, over `features`. A category with no features is absent rather than zero.

### unmapped_classes  `class-attribute` `instance-attribute`

```python
unmapped_classes: List[str] = field(default_factory=list)
```

Source `class`/`subtype` spellings the category table did not know, sampled. The list is capped, so it is evidence that something is unmapped, never a complete inventory. Every such feature still appears in `features`, under the fallback category.

### execution_time  `class-attribute` `instance-attribute`

```python
execution_time: float = 0.0
```

Wall-clock seconds for the read and the classification.

### overture_release  `class-attribute` `instance-attribute`

```python
overture_release: Optional[str] = None
```

Overture Maps release the features were read from. The public index pointer moves daily, so the same polygon can otherwise classify differently on two days with no signal to the caller; pass the value back as `overture_release=` to pin a later run. Several releases are joined with ", " on the rare run that straddles a refresh.

### read_margin_m  `class-attribute` `instance-attribute`

```python
read_margin_m: Optional[float] = None
```

Half extent, in metres, of the rectangle the area was read with. It is the same margin the ground-material read uses, because both read the same Overture `land_use` rows.

### analysis_type  `class-attribute` `instance-attribute`

```python
analysis_type: Optional[str] = None
```

The analysis type the read margin was taken from. `None` on results built by hand, which make no claim.