# Plans and wells

Source: https://developers.novilabs.com/forecasts/guides/plans-and-wells/

> Find existing wells, describe drawn wells, and run, read, save and delete development plans.

A plan forecasts many drawn
wells as one background job and stores the result.

## Model sets and the dataset

A model set is one basin's dataset with its oil, gas and water models.

- `GET /model-sets` lists your company's sets, the default first. Send `model_set=<id>` on any dataset call; without it,
  the default set answers.
- A plan or export stays in its set, so later calls on it need no `model_set`.
- `GET /dataset` gives the set's `as_of` date, `ip_days`, whether EUR and bands are available, and `limits` such as
  `limits.forecast_wells` and `limits.plan_wells`.
- `GET /formations` lists the formations. `include=target` marks the target zones, where you can plan a well.

## Existing wells

| Call | Returns |
| --- | --- |
| `GET /wells` | Wells for a map. `format=geojson` with `bbox`, `formation`, `q` (name or key), `operator` or `near` and a small `limit` returns a page of points |
| `GET /wells/{key}` | One well's header, by wellbore key |
| `GET /wells/{key}/production` | Its production history |
| `GET /wells/{key}/spacing` | Its spacing neighbors |
| `GET /wells/{key}/features` | The spacing features the models read for it |
| `GET /wells/{key}/predictions` | The model's stored prediction beside its actuals |
| `POST /wells/search` | Wells inside a unit's outline, with an optional buffer |
| `GET /wells/facets` | Counts by operator, formation or county, and a numeric field's spread |
| `POST /wells/typecurve` | A type curve of existing wells' production: counts, mean and quantiles by day |

Ask for the least data that answers the question.

## Drawn wells

A drawn well is a well you plan, in the same shape for `POST /forecasts`, `POST /plans` and exports.

| Field | Required | Meaning |
| --- | --- | --- |
| `shl` | yes | Surface hole location, `[lng, lat]` |
| `bhl` | yes | Bottom hole (toe), `[lng, lat]`. The lateral runs from `heel`, else `shl`, to `bhl`: 100 to 50,000 ft |
| `heel` | no | Where the lateral starts, when not at `shl` |
| `formation` | to forecast | Target formation, from `GET /formations` |
| `tvd_ft`, `landing_below_top_ft` or `landing_fraction` | no | Landing. Blank estimates TVD from the structure grid and nearby wells |
| `til_date` | no | First production date, `YYYY-MM-DD`. Orders parents and children in spacing |
| `fluid_bbl_per_ft`, `proppant_lb_per_ft` | no | This well's completion, over the design's |
| `pad`, `scenario` | no | Groups wells by pad. A scenario's wells never space against another scenario's |
| `name` | no | 1 to 60 characters |

These calls lay wells out for you, ready for a plan:

| Call | Does |
| --- | --- |
| `POST /layouts/fill` | Fills a polygon at a spacing and azimuth |
| `POST /areas` | Reads unit outlines from a zipped shapefile, GeoJSON, KML or KMZ |
| `POST /areas/fill` | Fills a whole file of areas |
| `POST /inventories/read` | Reads a well inventory file |

## Run a plan

`POST /plans` returns the plan and its id at once. Read it with `GET /plans/{id}?wait=25`: each call returns as soon as
the status changes from `running` to `done` or `error`, or after 25 seconds.

**curl**

```sh
curl -sS --fail-with-body -X POST \
  -H "Authorization: Bearer $NOVI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Hawk unit infill",
    "wells": [
      {"name": "Hawk 14-1H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957], "formation": "WOLFCAMP A", "til_date": "2027-03-01"},
      {"name": "Hawk 14-2H", "shl": [-101.928, 31.93], "bhl": [-101.928, 31.957], "formation": "WOLFCAMP A", "til_date": "2027-04-01"}
    ],
    "designs": [
      {"name": "Recent median"},
      {"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000}
    ],
    "eur": true
  }' \
  "$NOVI_API_BASE/plans"

# The answer has the plan's id. Each GET with wait=25 returns when the status changes, or after 25 s.
PLAN_ID="<the id from the response>"
curl -sS --fail-with-body \
  -H "Authorization: Bearer $NOVI_API_TOKEN" \
  "$NOVI_API_BASE/plans/$PLAN_ID?wait=25"
```

**Python**

```python
import os
import uuid

import requests

BASE = os.environ["NOVI_API_BASE"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"

body = {
    "name": "Hawk unit infill",
    "wells": [
        {"name": "Hawk 14-1H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957],
         "formation": "WOLFCAMP A", "til_date": "2027-03-01"},
        {"name": "Hawk 14-2H", "shl": [-101.928, 31.93], "bhl": [-101.928, 31.957],
         "formation": "WOLFCAMP A", "til_date": "2027-04-01"},
    ],
    "designs": [
        {"name": "Recent median"},
        {"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000},
    ],
    "eur": True,
}
r = session.post(f"{BASE}/plans", json=body,
                 headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=60)
r.raise_for_status()
plan = r.json()

while plan["status"] == "running":
    r = session.get(f"{BASE}/plans/{plan['id']}", params={"wait": 25}, timeout=60)
    r.raise_for_status()
    plan = r.json()

if plan["status"] == "error":
    raise SystemExit(plan["error"])

for total in plan["totals"]:
    design = plan["designs"][total["design"]]["name"]
    oil_eur = total.get("eur", {}).get("oil", {}).get("value")
    print(design, "wells:", total["wells_with_forecast"], "oil EUR (bbl):", oil_eur)

session.patch(f"{BASE}/plans/{plan['id']}", json={"saved": True}, timeout=60).raise_for_status()
```

The example is in the Midland basin. Take formations and coordinates from your own model set.

The request also takes:

- `designs`: each well is forecast once per design. An empty design takes the recent completions median.
- `eur: true` extends oil and gas forecasts to an EUR. `bands: true` adds Low (P10) and High (P90) curves, and
  `band_eur: true` an EUR for each, where `GET /dataset` says your set has them.
- `til_date` on the request dates every well that no narrower setting dates. In a dated plan, each planned well's
  forecast production is passed to the later wells it is a parent of, where the set's models read neighbors'
  production. `depletion_chain: false` turns that off.
- `scenarios`, `pads` and `formations` set values per scenario, pad and formation.
- `dry_run: true` checks and counts the plan without starting it.
- `from_plan: <id>` reruns a done plan's request on the set's current models.

A plan takes up to `limits.plan_wells` forecasts (wells × designs), up to 50,000. Your queued and running plans share a
cap, `limits.plan_unfinished_forecasts`: past it, wait for a plan to finish before you start another. See
[Errors and limits](https://developers.novilabs.com/forecasts/guides/errors-and-limits/#limits).

## Read a done plan

<Screenshot name="plan-results-summary" alt="A done plan's Plan Summary in Forecasts: oil at 3 years, oil and BOE EUR, and a table of each well's volumes and EUR." width={540} height={735} caption="Sample plan; numbers and timing are illustrative." />

| Call | Returns |
| --- | --- |
| `GET /plans/{id}` | Status, designs, and totals per design (and per scenario) |
| `GET /plans/{id}?include=wells` | Each well's inputs, TVD, forecasts per design and spacing, paged with `limit` and `cursor`. Filter with `formation`, `pad`, `scenario`, `q` or `wells`; rank with `sort` (`eur_boe`, `cum_oil` and more) |
| `GET /plans/{id}/stats` | Histogram and quantiles of a metric across the wells |
| `GET /plans/{id}/rollup` | Oil, gas and water by pad and by landing zone |
| `GET /plans/{id}/checks` | Wells with inputs outside the models' training data, by input |
| `GET /plans/{id}/curves` | Every well's cumulative curves to EUR. See [Forecasts and curves](https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/) |
| `GET /plans/{id}/wells/{index}/explanations/{design}` | A well's drivers per day and the training wells it leans on |
| `GET /plans/{id}/typecurve/{design}` | A type curve from the plan's own forecasts |

## Keep, share or delete

- **Unsaved plans are deleted 90 days after they are made.** `PATCH /plans/{id}` with `{"saved": true}` keeps one
  until someone deletes it; `{"saved": false}` starts a new 90 days. `name` renames it.
- `GET /plans` lists your company's plans in a model set, newest first, 20 a page by default, up to 100. Filter with
  `q`, `status`, `saved` and `created_by=me`.
- `POST /plans/{id}/shares` makes a link to a done plan; `DELETE /plans/{id}/shares/{share_id}` revokes it.
- `DELETE /plans/{id}` stops a running plan or deletes a done one and its shares, leaving no record. `unless=saved`
  deletes it only if it isn't saved or shared.

> **Legacy Forecasts:**
> `GET /plans?origin=all` adds your company's Legacy Forecasts[^legacy] as read-only plans, whose `origin.engine` is
> `fe`. They support `GET /plans/{id}` (with `include=wells`), `GET /plans/{id}/wells/{index}`, `GET /plans/{id}/curves`
> and exports. Other plan reads and any change, such as a rename or a delete, are not supported.

[^legacy]: Legacy Forecasts are dynamic imports from Forecast Engine v1.
