Geozones

A geozone is a geographic area drawn on a map, into which Insights sites fall automatically according to their coordinates. Geozones let you group, filter and report on sites by territory — a sales region, a municipality, a distribution network area — without maintaining that grouping by hand.

The model

Three objects, and one relationship that is computed rather than declared.

The geozone model

Object Endpoint What it is
Geozone type /geozones/types A family of zones — Region, Municipality, Sales area. Zones only exist inside a type.
Geozone /geozones/zones One area: a name and a GeoJSON geometry. Zones of a type can nest through parentGeozoneIds.
Site membership /geozones/zones/sites Which sites fall inside which zones. Derived from the site's coordinates.

Golden rule

Membership is computed from geometry, never assigned by hand.

A site belongs to a zone because its coordinates fall inside the zone's polygon. So a site with no coordinates belongs to nothing, and fixing a missing grouping means fixing the site's position — not looking for an assignment screen.

Creating zones from a GeoJSON file

Zones are almost always uploaded rather than drawn. Three upload endpoints cover the usual cases:

Endpoint Use when
POST /geozones/zones/upload The file itself carries the type information.
POST /geozones/zones/upload/{geozoneTypeId} A FeatureCollection where each feature becomes one zone of that type.
POST /geozones/zones/upload/{geozoneTypeId}/{geozoneName} The whole file becomes a single named zone.

The payload is multipart/form-data, and the file may be plain GeoJSON or a ZIP — which matters, because administrative boundary files are large.

Parameter Role
geozoneNameProperty Which GeoJSON feature property supplies the zone name.
relationType How the uploaded zones relate to the zones already present.
Tip

GET /geozones/zones/sample returns sample GeoJSON files. Start from one to confirm the shape the API expects before wrestling with a production export.

Querying zones and sites

GET /geozones/zones filters on Ids, Names, GeozoneTypeIds, GeozoneTypeNames, and on spatial criteria: ReferenceGeozoneId with GeozoneRelation returns the zones related to another zone, and geoJsonContent matches against a geometry you supply.

GET /geozones/zones/sites answers the question integrations actually ask — which zones does each site belong to? — and takes the same filters plus siteIds.

AUTH=(-H "Authorization: Bearer $TOKEN" -H "Api-Version: 1.7")

curl -s "${AUTH[@]}" "https://api.opinum.com/geozones/types"
curl -s "${AUTH[@]}" "https://api.opinum.com/geozones/zones?GeozoneTypeNames=Region"
curl -s "${AUTH[@]}" "https://api.opinum.com/geozones/zones/sites?siteIds=12345"
Note

Geozone ids are strings, not the integers used by sites, sources and variables. Do not reuse an integer-typed field to carry one.

Geometry simplification

Administrative boundaries can carry tens of thousands of vertices — accurate, but far too heavy to draw on a dashboard. Insights keeps a simplified version of each geometry alongside the original.

Endpoint Role
GET /geozones/zones/evaluatesimplified/{geozoneId} Evaluate what the simplification would produce, before applying it.
PUT /geozones/zones/recompute/{geozoneTypeId} Recompute the simplified geometry for every zone of a type.

recompute takes verticesThreshold — above how many vertices a geometry is simplified — and verticesDistanceTolerance, how far the simplified outline may drift from the original.

Golden rule

Evaluate a simplification before recomputing a whole type.

Simplification trades fidelity for weight, and too aggressive a tolerance moves borders enough to change which sites fall inside. evaluatesimplified exists precisely so that trade-off is a decision rather than a discovery.

Where geozones are used

  • Filtering sites — GET /sites accepts a GeozoneId, so any site query can be narrowed to a territory.
  • Dashboards and reports — grouping by zone rather than by an ad-hoc form field.
  • The filter itself is described by GeozoneFilterDto: a main geozone type and zone, plus optional secondary geozone types, which is how a view combines two territorial dimensions.

Access

Geozone endpoints sit behind their own OAuth2 scope, geozones-api. A token requested with only datahub-api is rejected — see Scopes.

DOCS 2026.08 REVIEWED 2026-08-28 API 1.7 Documentation changelog →