> For the complete documentation index, see [llms.txt](https://spatialise.gitbook.io/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spatialise.gitbook.io/api-reference/whats-new-v0.3.0.md). # What's new in v0.3.0 `spatialise` **v0.3.0** adds first-class support for the **V2** soil-prediction API while staying fully backward compatible with v0.2. Every change below is **additive**: existing v0.2 code keeps working unchanged. If you only use `client.batch.create(...)` and `client.batch.retrieve_status(...)` against v1, you do not have to change anything. > **TL;DR** — pass `version="v2"` to target the V2 deployment, and use the new `retrieve_job_status` / `retrieve_patch_batch_status` calls to see per-job progress. Batch count fields are unchanged for callers. ## Installation ```sh pip install --upgrade spatialise ``` ## 1. Selecting v1 or v2 with `version=` The client now takes a `version=` argument that selects which API host it talks to — `"v1"` (the default, unchanged behaviour) or `"v2"`: ```python from spatialise import SpatialiseSoilPrediction # v1 (default) — identical to v0.2 behaviour client = SpatialiseSoilPrediction(api_key=api_key) # v2 — targets the V2 deployment, no URL to spell out client = SpatialiseSoilPrediction(api_key=api_key, version="v2") ``` v1/v2 routing is **host-based on the server**, so `version=` is purely a client-side host selector. An explicit `base_url` argument — or the `SPATIALISE_SOIL_PREDICTION_BASE_URL` environment variable — still overrides `version=` if you need to point at a custom host: ```python # base_url / the env var win over version= client = SpatialiseSoilPrediction(api_key=api_key, base_url="https://my-host.example/") ``` ## 2. V2 observability: batch → job → patch-batch On V2, each **job** is processed as several **patch-batches**. Two new methods surface that hierarchy so you can show fine-grained progress before a job's COG is ready. They are additive — `create` and `retrieve_status` are unchanged. ```python # Per-job progress: how many patch-batches are done detail = client.batch.retrieve_job_status(job_id="job_xyz", batch_id="batch_abc123") if detail.total_patch_batches: done = detail.completed_patch_batches or 0 print(f"Job {detail.job_id}: {done}/{detail.total_patch_batches} patch-batches") # Iterate the (paginated) per-patch-batch statuses for pb in detail.patch_batches: print(f" patch-batch {pb.patch_batch_idx}: {pb.status}") if pb.status == "failed": print(f" failed: {pb.failure_reason}") # Page through patch-batches when there are more if detail.has_more: next_page = client.batch.retrieve_job_status( job_id="job_xyz", batch_id="batch_abc123", cursor=detail.next_cursor ) # Or inspect one patch-batch directly by index pb = client.batch.retrieve_patch_batch_status( patch_batch_idx=0, batch_id="batch_abc123", job_id="job_xyz" ) print(f"patch-batch {pb.patch_batch_idx}: {pb.status}, {pb.point_count} points") ``` > These endpoints return useful data only against a **V2** deployment. A client on the v1 host keeps working unchanged and simply doesn't call them. ## 3. Batch count fields now populated (no code change needed) Batch and status responses now read their counts from the API's real wire fields (`total_tasks` / `completed_tasks` / `failed_tasks` / `pending_tasks`), which the v0.2 models never populated. The public attributes you already use are **preserved as aliases**, so existing code is unaffected: ```python status = client.batch.retrieve_status("batch_abc123") # These continue to work exactly as before: status.total_jobs # == status.total_tasks status.completed_jobs # == status.completed_tasks status.failed_jobs # == status.failed_tasks status.pending_jobs # == status.pending_tasks ``` If you previously saw these come back as `0`/empty on some responses, they are now correctly populated. ## 4. Packaging note From v0.3.0 the SDK is **hand-maintained** (no longer generated by Stainless). This does not change the public API or how you install/use the library — it only affects how the package is built and released. ## Migration checklist * [ ] Upgrade: `pip install --upgrade spatialise`. * [ ] Targeting V2? Add `version="v2"` to your client (or set `base_url`). * [ ] Want per-job progress? Adopt `retrieve_job_status` / `retrieve_patch_batch_status` (V2 only). * [ ] No changes needed for `create` / `retrieve_status` or the batch count attributes — they are backward compatible. ## See also * [Quick Start & common tasks](/api-reference/readme.md) * [Rate limiting](/api-reference/guides/rate-limiting.md) * [Idempotency](/api-reference/guides/idempotency.md) * [Webhooks](/api-reference/guides/webhooks.md) * [Production patterns](/api-reference/guides/production-patterns.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://spatialise.gitbook.io/api-reference/whats-new-v0.3.0.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.