Regions

In one sentence

An OctetRegion is the area you ask about (country, city, disc, polygon, bounding box), and its shape determines how the SDK proves containment.

How shapes map to evidence

Different region shapes are answered in different ways. A disc needs a precise location fix. A city resolves to a polygon set. Letting callers supply a free-form lat/lon polygon would force the SDK to triangulate and re-quantize every query, which the H3-based proof format does not support. Polygons are therefore accepted only as H3 cell sets.

flowchart TD
    R[OctetRegion] --> Named[Named lookups]
    R --> Geometric[Geometric shapes]
    Named --> Country[country isoCode]
    Named --> Sub[subdivision isoCode]
    Named --> City[city name]
    Geometric --> Disc[disc center radius]
    Geometric --> Ellipse[ellipse center axes heading]
    Geometric --> Box[box3D lat lon alt ranges]
    Geometric --> Poly[polygonSet H3 cells]
    Geometric --> Earth[earth maxAltitude]

The shapes

Factory	Verified via	Typical use
`earth(maxAltitudeMeters)`	Always `YES`.	Sanity check / fallback.
`country(isoCode)`	Resolved on the device and bound into the signed proof.	"Is the user in the US?"
`subdivision(isoCode)`	Resolved on the device at the state or province level.	ISO 3166-2 codes: `US-CA`, `FR-75`, `JP-13`.
`usState(stateCode)`	Same as `subdivision`.	Sugar for `subdivision("US-XX")`.
`city(name)`	SDK resolves the name to an H3 polygon set. The proof is verified against that polygon.	"Is the user in San Francisco?"
`disc(center, radiusMeters)`	The proof carries the disc as an ellipse with equal axes. The SDK checks containment from the distance between the centers and the two radii.	"Is the device within 250 m of a saved anchor point?"
`ellipse(center, semiMajorM, semiMinorM, headingDeg)`	2D ground ellipse. Disc is a special case. Only discs are answered today: an ellipse with unequal axes returns `INDETERMINATE` with `NOT_YET_RELEASED`.	GNSS uncertainty ellipses, oriented zones.
`box3D(latRange, lonRange, altRange)`	3D bounding box.	Volumetric containment, building floors.
`polygonSet(cells)`	Union of H3 cells.	Custom geofences pre-quantized to H3.

All factories validate eagerly. Invalid lat/lon, malformed ISO codes, non-positive radii, ellipse axes out of order: all trap at construction. An invalid region never reaches a predicate call.

Why polygons are H3-only

If you have a free-form polygon (a delivery zone, an event venue, a building footprint), you (or your tooling) quantize it to H3 cells ahead of time and pass the cell list. The SDK compares those cell IDs with the cells of the proof's claimed region on the device, so nothing is triangulated at request time. The claimed cells are part of the signed proof.

The comparison treats each cell ID as an exact value. When every claimed cell is in your list, the answer is YES. When none of them is, the answer is NO. Any other overlap is INDETERMINATE with NO_PROOF_AT_RESOLUTION. A cell ID also encodes its resolution, but the comparison doesn't relate cells across resolutions: a coarse cell in your list doesn't match the finer cells inside it.

Construction helpers (Android only)

On Android, two additional surfaces let you build regions dynamically:

getRegion(RegionSpec.country("US")). Symbolic lookup, useful when the region name comes from configuration or a server response. The city / namedZone variants currently throw OctetFutureFlag and are not available in this release.
buildRegion { disc(center = LatLon(37.42, -122.08), radiusMeters = 250.0) }. A DSL over the static factories for assembling regions from runtime data.

The RegionSpec DSL and getRegion are Android-only. iOS exposes the static factories.

Inspecting a region

Two helpers turn a region into a string:

whatisRegion(r). Short, human-readable. For log lines and debug overlays. Not stable across SDK versions.
regionToStr(r). Canonical, machine-readable, stable wire form. Suitable for log diffs, idempotency keys, eventual regionFromStr round-trip.

Both are surfaced uniformly on every API object via .toStr(), .toJson(), and .toJsonl(). See Serialization.

Where to go next

OctetRegion API Reference for the exact signatures and validation rules.
Verdicts for what happens when the cached proof's region is coarser than your query.