public-api-docs

Operations API Areas Guide

Overview

Areas are geofenced zones with policies that influence vehicle behavior, map display, parking, rental-end validation, speed limits, notices, and capacity rules. Use the Areas Operations API when building operator tools for geofence administration, policy configuration, service-area management, parking restrictions, no-end-rental zones, and speed-limit zones.

Areas are different from branches and stations:

Concept	Use it for
Branch business area	Compatibility/read model for branch-level area geometry. Use Areas for new geofence management workflows.
Station	Pickup, return, booking, parking, docking, and station-capacity workflows.
POI	Informational map marker.
Area	Geofenced rule zone with policies.
Voucherable geofence promotion	Promotion or surcharge geofence used for rental pricing and promotional map/search display.

Related reference: Areas Operations API

Operations API Guide

Branches And Stations Guide

Promotions, Packages, Subscriptions, And Benefits Guide

Vehicle Guide

Rental Guide

Points Of Interest Guide

Error Codes

Core Concepts

Areas

An area is a named geofence assigned to a branch and an area type. It can target vehicle categories/types and contain one or more policies.

Important fields:

Field	Meaning
`uuid`	Area identifier.
`name`	Display name.
`branchId`	Branch the area belongs to.
`areaTypeId`	Area type that defines allowed policy types and style.
`status`	Area state, usually `ACTIVE` or `INACTIVE`.
`vehicleTypeIds`	Vehicle categories/types affected by the area.
`geofence`	GeoJSON `MultiPolygon` defining the zone.
`policies`	Policy configuration applied in the zone.
`tags`	Client-managed free-form tags.
`labels`	System-managed read-only labels.

Use includeChildBranches=true when a parent-branch operator view should include areas from child branches. Keep this visible in the UI because area rules can be branch-specific.

Area Types

Area types define the class of area, map styling, and which policies are allowed or required on areas of that type.

Important fields:

Field	Meaning
`uuid`	Area type identifier.
`name` / `description`	Display text for the area type.
`style`	Map style: color, line thickness, opacity.
`policyTypes`	Policy types allowed/required for areas of this type.
`readOnly`	Whether this area type can be changed.
`tags` / `labels`	Client-managed tags and system-managed labels.

Changing policyTypes on an area type can affect policies attached to existing areas of that type. Treat area-type changes as higher impact than ordinary area edits.

Policies

Policies define what an area does.

Policy type	Meaning
`END_RENTAL_CAPACITY_POLICY`	Limits how many vehicles in selected states/categories can be in the area.
`SPEED_LIMIT_POLICY`	Defines speed limits, optionally with vehicle-category overrides.
`NO_PARKING_POLICY`	Marks the area as no-parking.
`NO_END_RENTAL_POLICY`	Prevents ending rentals in the area.
`ALLOW_END_RENTAL_POLICY`	Allows ending rentals in the area.
`NOTICE_AREA_POLICY`	Shows a notice without direct rental/ride-flow enforcement.

Areas can affect the same operational questions that operators ask in the rental and vehicle guides: whether a vehicle can be parked, whether a rental can end, whether a speed limit applies, and whether capacity has been reached.

Branch Business Area And Map Overlay Compatibility

The Areas API is the recommended API for new operator tools that create or maintain business areas, prohibited areas, restricted/warning overlays, no-end-rental zones, speed zones, notices, and capacity rules.

Branch responses can still expose compatibility fields such as businessArea, mapOverlayProhibited, and mapOverlayWarning. These fields exist because some app and backend paths still consume branch-level geometry. Internally, Area Service synchronizes selected area definitions back into Core branch fields while the platform transitions these checks to Areas directly.

For custom tools:

Use the Areas API as the authoritative management surface for geofenced rules and overlays.
Treat branch businessArea and map overlay fields as read/display compatibility fields, not the primary write model.
Use branch fields when an existing endpoint or client explicitly returns them, but do not build new branch-editing workflows around those fields.
When troubleshooting rental-end or vehicle-availability behavior, inspect both the branch compatibility fields and the relevant area policies if the tenant is already configured through Areas.

Coordinates

Areas use GeoJSON geometry:

Geometry	Use
`MultiPolygon`	Area geofence.
`Point`	Vehicle or point positions in policy checks and examples.

The Areas API coordinate schema documents coordinates as latitude/longitude pairs. Verify coordinate order carefully when integrating with libraries or services that expect standard GeoJSON longitude/latitude order.

Common Operator Workflows

List Areas

Use GET /areas.

Useful parameters:

Parameter	Use it for
`branch`	Limit areas to a branch.
`includeChildBranches`	Include areas from child branches.
`page` / `size`	Pagination.
`sort`	Sort by a field, with optional `,DESC`.

The endpoint returns pagination metadata in X-Pagination-* headers.

Create Or Update An Area

Use:

Task	Endpoint
Create area	`POST /areas`
Get area	`GET /areas/{id}`
Update area	`PUT /areas/{id}`
Delete area	`DELETE /areas/{id}`

When updating an area, confirm:

Branch scope.
Area type.
Geometry validity.
Vehicle category/type targeting.
Policies and policy status.
Whether the change affects active rentals, parking, or end-rental behavior.

The resetNew update parameter exists in the reference. Use it only for workflows that intentionally reset “new” state handling.

Manage Area Types

Use:

Task	Endpoint
List area types	`GET /areatypes`
Create area type	`POST /areatypes`
Get area type	`GET /areatypes/{id}`
Update area type	`PUT /areatypes/{id}`
Delete area type	`DELETE /areatypes/{id}`

Do not delete area types that are still in use. The API can return conflict when an area type is referenced.

Configure Parking And End-Rental Rules

Use these policies for parking and rental-end behavior:

Policy	Use it when
`NO_PARKING_POLICY`	Vehicles should not be parked in this area.
`NO_END_RENTAL_POLICY`	Users should not be able to end rentals in this area.
`ALLOW_END_RENTAL_POLICY`	The area explicitly allows ending rentals.
`END_RENTAL_CAPACITY_POLICY`	Ending/parking should be allowed only while area capacity is available.

For support tooling, show the failed area rule together with the rental end requirement. This helps an operator distinguish “outside business area” from “inside no-end-rental zone” or “capacity full”.

Configure Capacity Rules

END_RENTAL_CAPACITY_POLICY can set:

Field	Meaning
`overallCapacity`	Total capacity for the area.
`applicableStates`	Vehicle states counted by the policy, such as `AVAILABLE` or `PARKING`.
`capacityByCategories`	Category-specific limits.
`schedule`	Optional time windows for when the policy applies.

If overallCapacity and category-specific capacity are both set, the stricter limit applies. Use this to model areas where the total fleet count and category mix both matter.

Configure Speed Limits

SPEED_LIMIT_POLICY can define a general speedLimit and category-specific speedLimitOverrides.

Use this when operators need geofenced speed behavior, especially for micromobility fleets. Show category overrides clearly because a vehicle category override can differ from the general area speed limit.

Configure Notice Areas

NOTICE_AREA_POLICY has no direct rental or ride-flow enforcement. Use it for user-facing or operator-facing map notices where the location should communicate information but should not block parking, ending, or driving.

Display Promotional Geofences

Do not use the Areas API alone to build search or display flows for geofence promotions. Promotional geofences, geo-event promotions, and geofence surcharges are configured as voucherables. If a tool needs to show promotional areas in search results, campaign screens, or map overlays, retrieve the promotion or surcharge configuration from /voucherables and use the geofence data linked to that voucherable.

Use the Areas API for operational policies such as parking, end-rental, speed, notices, and capacity. Use voucherables for commercial geofence behavior such as promotional discounts or surcharges.

Most Relevant APIs

Area	Endpoint
Areas	`GET /areas`, `POST /areas`
Area detail	`GET /areas/{id}`
Area update	`PUT /areas/{id}`
Area delete	`DELETE /areas/{id}`
Area types	`GET /areatypes`, `POST /areatypes`
Area type detail	`GET /areatypes/{id}`
Area type update	`PUT /areatypes/{id}`
Area type delete	`DELETE /areatypes/{id}`

Permissions And Settings

Area endpoints are permission-gated by branch. For example, creating an area requires area-create permission for the selected branch.

For custom tools:

Require elevated area-management permissions before showing create, update, or delete actions.
Show branch scope and whether child branches are included.
Treat area-type changes as high impact because they can affect policy validation on existing areas.
Require confirmation before changing policies that affect rental end, parking, speed limits, or capacity.
Root permissions are reserved for Wunder Mobility and can only be accessed by Wunder Mobility.

Implementation Notes

Use areas for geofenced policy enforcement.
Use branch businessArea, mapOverlayProhibited, and mapOverlayWarning only as compatibility/read fields in new tools.
Use POIs for informational map markers.
Use stations for booking/parking/docking infrastructure.
Use /voucherables when the geofence is part of a promotion, geo-event promotion, or surcharge display.
Validate geometry before writing.
Show policy effects in operator UIs, not only the area name.
Re-check vehicle category/type targeting when a rule appears not to apply.
Use data exports or the data warehouse for recurring spatial reporting instead of polling area lists.

Review Notes

Confirm how each tenant uses area types before exposing policy writes. Area naming and policy combinations are operationally sensitive because they can directly affect where users can park, end rentals, drive, or receive warnings.