Request Bodies

This page documents request body fields that are actually used by each endpoint implementation.

Shared Types

`area`

area accepts Koji geo input formats. In practice, use one of:

GeoJSON FeatureCollection
GeoJSON Feature
Coordinate arrays ([[lat, lon]] or [[[lat, lon]]])

`data_points` and `clusters`

Accepted forms resolve into a list of points ([lat, lon]):

[[lat, lon], ...]
[{ "lat": number, "lon": number }, ...]
GeoJSON Feature
GeoJSON FeatureCollection

Calculation Endpoints

`POST /api/v1/calc/bootstrap`

Field	Type	Required	Default	Notes
`area`	GeoFormats	No	empty	One of `area`, `instance`, or `parent` must resolve to input area.
`instance`	string	No	`""`	Area lookup key in Koji/scanner DB.
`parent`	string \| number	No	`null`	Loads all geofences by parent when present.
`benchmark_mode`	boolean	No	`false`	If `true`, returns stats only (`data: null`).
`radius`	number	No	`70`	Meters.
`return_type`	string	No	inferred	See return type values in `params`.
`calculation_mode`	string	No	`radius`	`radius`, `s2`, or custom plugin name.
`s2_level`	integer	No	`15`	Used when calculation mode relies on S2.
`s2_size`	integer	No	`9`	S2 grid size for S2-based bootstrap.
`sort_by`	string	No	`unset`	Route ordering strategy.
`route_split_level`	integer	No	`0`	Validated to `0..20`.
`routing_args`	string	No	`""`	Extra args for routing plugin.
`bootstrapping_args`	string	No	`""`	Extra args for bootstrap plugin (radius is appended automatically).
`save_to_db`	boolean	No	`false`	Saves generated route to Koji DB.
`save_to_scanner`	boolean	No	`false`	Saves to scanner/controller DB and triggers project update API.
`save_to_scanner_only`	boolean	No	`false`	Saves to scanner/controller DB without project update API call.

`POST /api/v1/calc/{mode}/{category}`

Field	Type	Required	Default	Notes
`area`	GeoFormats	No	empty	Used when `data_points` is not supplied.
`data_points`	point list/formats	No	empty	If empty, points are queried from DB by `category` and area.
`instance`	string	No	`""`	Area lookup key.
`parent`	string \| number	No	`null`	Parent-based area lookup.
`benchmark_mode`	boolean	No	`false`	Stats-only response toggle.
`cluster_mode`	string	No	`balanced`	`honeycomb`, `fastest`, `fast`, `balanced`, `better`, `best`, custom.
`cluster_split_level`	integer	No	`0`	Validated to `0..20`.
`max_clusters`	integer	No	unlimited	`0` becomes unlimited.
`radius`	number	No	`70`	Meters.
`min_points`	integer	No	`1`	Minimum points per cluster target.
`last_seen`	integer	No	`0`	Timestamp filter for DB point queries.
`tth`	string	No	`all`	Spawnpoint filter: `all`, `known`, `unknown`.
`sort_by`	string	No	`unset`	When `mode=route` and unset, server forces `tsp`.
`route_split_level`	integer	No	`0`	Validated to `0..20`.
`calculation_mode`	string	No	`radius`	`radius`, `s2`, or custom plugin.
`s2_level`	integer	No	`15`	S2 parameter.
`s2_size`	integer	No	`9`	S2 parameter.
`routing_args`	string	No	`""`	Extra routing plugin args.
`clustering_args`	string	No	`""`	Extra clustering plugin args (radius/min/max are appended automatically).
`center_clusters`	boolean	No	`false`	Re-centers cluster coordinates.
`genetic_post_processing`	boolean	No	`false`	Additional post-processing step.
`return_type`	string	No	inferred	See return type values in `params`.
`save_to_db`	boolean	No	`false`	Saves output route to Koji DB.
`save_to_scanner`	boolean	No	`false`	Saves to scanner/controller DB and triggers project update API.
`save_to_scanner_only`	boolean	No	`false`	Saves to scanner/controller DB without project update API call.

`POST /api/v1/calc/reroute`

Field	Type	Required	Default	Notes
`clusters`	point list/formats	No	empty	Preferred reroute input.
`data_points`	point list/formats	No	empty	Legacy fallback when `clusters` is empty.
`instance`	string	No	`""`	Added to output metadata.
`mode`	string	No	`unset`	Route mode label/type (example: `circle_pokemon`).
`radius`	number	No	`70`	Meters.
`sort_by`	string	No	`unset`	Ordering strategy.
`route_split_level`	integer	No	`0`	Validated to `0..20`.
`routing_args`	string	No	`""`	Extra routing plugin args.
`benchmark_mode`	boolean	No	`false`	Stats-only response toggle.
`return_type`	string	No	inferred	See return type values in `params`.

`POST /api/v1/calc/route-stats`

Field	Type	Required	Default	Notes
`clusters`	point list/formats	Conditionally	empty	Must provide `clusters` or `data_points`; both empty returns `400`.
`data_points`	point list/formats	Conditionally	empty	Used for coverage stats if provided.
`instance`	string	No	`""`	Added to output metadata.
`mode`	string	No	`unset`	Added to output metadata.
`radius`	number	No	`70`	Used for coverage computation.
`min_points`	integer	No	`1`	Used in score computation.

`POST /api/v1/calc/route-stats/{category}`

Field	Type	Required	Default	Notes
`clusters`	point list/formats	Conditionally	empty	Must provide clusters or resolvable data points; both empty returns `400`.
`data_points`	point list/formats	No	empty	If empty, server loads points by `category` from area lookup.
`area`	GeoFormats	No	empty	Used when server must query points by category.
`instance`	string	No	`""`	Area lookup key.
`parent`	string \| number	No	`null`	Parent-based area lookup.
`last_seen`	integer	No	`0`	Point query timestamp filter.
`tth`	string	No	`all`	Spawnpoint filter for spawnpoint category.
`mode`	string	No	`unset`	Added to output metadata.
`radius`	number	No	`70`	Used for coverage computation.
`min_points`	integer	No	`1`	Used in score computation.

`POST /api/v1/calc/area`

Field	Type	Required	Default	Notes
`area`	GeoFormats	Yes	empty	Sums geodesic area across Polygon and MultiPolygon geometry.

Conversion Endpoints

`POST /api/v1/convert/data`

Field	Type	Required	Default	Notes
`area`	GeoFormats	Yes	empty	Input geometry to convert.
`simplify`	boolean	No	`false`	Simplifies polygon/multipolygon before conversion.
`return_type`	string	No	inferred	Output format.
`benchmark_mode`	boolean	No	`false`	If `true`, data is omitted.
`instance`	string	No	`""`	Included in output metadata where relevant.

`POST /api/v1/convert/simplify`

Field	Type	Required	Default	Notes
`area`	GeoFormats	Yes	empty	Input geometry to simplify.
`return_type`	string	No	inferred	Output format.

`POST /api/v1/convert/merge-points`

Field	Type	Required	Default	Notes
`area`	GeoFormats	Yes	empty	Point features are merged into one MultiPoint feature.
`return_type`	string	No	inferred	Output format.

Geofence and Route Save Endpoints

`POST /api/v1/geofence/save-koji`

`POST /api/v1/geofence/save-scanner`

`POST /api/v1/route/save-koji`

Field	Type	Required	Notes
`area`	GeoFormats	Yes	Upsert payload written to target database.

S2 Endpoints

`POST /api/v1/s2/circle-coverage`

Field	Type	Required	Default	Notes
`lat`	number	Yes	-	Center latitude.
`lon`	number	Yes	-	Center longitude.
`level`	integer	Yes	-	S2 cell level.
`radius`	number	No	`70`	Radius in meters.

`POST /api/v1/s2/cell-coverage`

Field	Type	Required	Default	Notes
`lat`	number	Yes	-	Center latitude.
`lon`	number	Yes	-	Center longitude.
`level`	integer	Yes	-	S2 cell level.
`size`	integer	No	`15`	Coverage size.

`POST /api/v1/s2/polygons`

Body type:


["1152921504606846977", "1152921504606846979"]

`POST /api/v1/s2/{cell_level}`

Field	Type	Required	Default	Notes
`min_lat`	number	Yes	-	Bounds min latitude.
`min_lon`	number	Yes	-	Bounds min longitude.
`max_lat`	number	Yes	-	Bounds max latitude.
`max_lon`	number	Yes	-	Bounds max longitude.
`ids`	string[]	No	all cells	If provided, filters output to matching ids only.
`last_seen`	integer	No	unused	Accepted but not used in this endpoint.
`tth`	string	No	unused	Accepted but not used in this endpoint.

Request Bodies

Shared Types

area

data_points and clusters

Calculation Endpoints

POST /api/v1/calc/bootstrap

POST /api/v1/calc/{mode}/{category}

POST /api/v1/calc/reroute

POST /api/v1/calc/route-stats

POST /api/v1/calc/route-stats/{category}

POST /api/v1/calc/area

Conversion Endpoints

POST /api/v1/convert/data

POST /api/v1/convert/simplify

POST /api/v1/convert/merge-points