Landuse, Python SDK reference

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`	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.