Analyses & versions

An analysis is a document: a territory, a question, and the paid results that were computed for it. It has one public code (12 characters, the last segment of its web URL, /a/<code>) and belongs to the user who created it. Others see it only through explicit sharing; the one exception is the owner of the organization, who can read every analysis of the organization. Only the creator can change it.

Bind a run to an analysis

Send the header X-Analysis-Id: <code> on a charged execution. When the run is charged, the server stores it as a version of that analysis: input, state, results, credits and the data versions it was computed on. The response carries the version summary. The analysis must be yours; otherwise the run executes and is charged, but no version is written. analysis.isochrone draws a catchment and is never stored as a version, even when charged.

Create an analysis with POST /api/v1/analyses (scope manage) or in the web app; the code comes back as id. The body needs a name (up to 255 characters) and a state, the configuration the web app reopens: send {} when the analysis lives only in the API.

curl -X POST https://www.k-stra.com/api/v1/analyses \
  -H "Authorization: Bearer ks_live_…" -H "Content-Type: application/json" \
  -d '{"name":"Bondi Junction catchment","state":{}}'

The other writes, all with scope manage:

Route	What it does
`PUT /api/v1/analyses/{code}/name`	renames one of your analyses: `{"name":"…"}`
`POST /api/v1/analyses/{code}/duplicate`	copies an analysis you can read into a new one of yours, without its permissions or versions; with `?withResults=true` the latest results are copied too. Returns the new `id`
`DELETE /api/v1/analyses/{code}`	deletes one of your analyses

Read results for free

Reading never spends credits:

GET /api/v1/analyses — your analyses and the ones shared with you, with the last run of each: the 100 most recently updated.
GET /api/v1/analyses/{code} — the analysis with its latest saved results (latestRun), plus Coverage and Site comparison when they exist, and currentData, the data versions available now.
GET /api/v1/analyses/{code}/versions — the history: version number, action, credits, data versions, date, author.
GET /api/v1/analyses/{code}/versions/{no} — one version in full.

What you paid for is what you read back: versions are never recomputed.

Data versions

Each version records the data versions it used, for the families its action depends on: territory (the road graph and address poles), sociodemo, realestate, players. GET /api/v1/data returns the versions available today. When they differ from a version's, the results are still valid but newer data exists; a new run costs as much as the first one.

Sharing is a permission on the analysis, not a new link: team, organization, anyone with the link (optionally expiring), or specific people by email. GET/PUT /api/v1/analyses/{code}/shares need the manage scope and only work on your own analyses. A PUT replaces all the permissions with the ones in the body:

{ "team": true, "organization": false, "anyone": true, "anyoneExpiresDays": 30, "people": ["anna@example.com"] }

anyoneExpiresDays is 7, 30 or null (no expiry); people holds up to 50 addresses. The answer is the permissions as they are now, with the analysis url. People added by email are notified once.

Versioning of this API

The public surface /api/v1 is additive: fields, values, actions and routes are added, never removed or changed in meaning. When something must change, a new field or a new action is added alongside the old one; a v2 would be served next to v1 for at least twelve months, announced with the Sunset header. Every change is listed in the Changelog.