# Well identity

Source: https://developers.novilabs.com/concepts/well-identity/

> API numbers, how each Novi product keys wells and wellbores, and how to match a pasted list.

Match wells across products and against your own lists. Each product keys wells its own way today: match on the API10 when you can, and normalize both sides first.

## API numbers

US wells carry an API number. You will see it as 10, 12 or 14 digits, with or without dashes.

| Form | What it identifies |
| --- | --- |
| API10 | The well: the 10-digit US regulatory identifier |
| API12 | The API10 plus two more digits |
| API14 | A single wellbore or completion |

<WellKey />

The first 10 digits of any form are the API10. To match a pasted list, strip everything that is not a digit, then keep the first 10 digits. Dashed forms, API10, API12 and API14 then all match.

```sql title="Novi UDM Data: match pasted API numbers"
SELECT w.WELL_KEY, w.WELL_NAME, w.NATIVE_ID, w.STATE, w.COUNTY
FROM NOVI_WELLS.WELL w
WHERE w.NATIVE_ID IN (
    SELECT LEFT(REGEXP_REPLACE(value, '[^0-9]', ''), 10)
    FROM TABLE(SPLIT_TO_TABLE('42-000-00001, 4200000002, 42000000030000', ','))
)
ORDER BY w.WELL_KEY;
```

```python title="The same rule in Python"
import re

def api10(value: str) -> str:
    return re.sub(r"[^0-9]", "", value)[:10]

print([api10(v) for v in ["42-000-00001", "4200000002", "42000000030000"]])
```

## How each product keys wells

| Product | Well | Wellbore | What to match on |
| --- | --- | --- | --- |
| Novi UDM Data (v4) | `WELL_KEY`, for example `US:API10:4212340567` | `WELLBORE_KEY`, for example `US:API10:4212340567:0` | `WELL.NATIVE_ID` holds the API10 |
| Novi Forecasts API, existing wells | Not keyed separately | `wellbore_key` from `GET /wells` | Read the key from the API. Its format is not published yet |
| Novi Forecasts API, planned wells | `key`, unique within one plan only. `well_uid`, 32 characters, the same on every read of that plan | Not used | `well_uid`. A plan run again gets a new id, so its wells get new `well_uid` values |
| Novi EVA API, MCP server | `Header.EntityName`: the API10 for US wells, the UWI or a local identifier elsewhere | Not used | `Header.EntityName` |
| Novi EVA API, REST | The identifiers you send in `wellList`, returned as you sent them | Not used | The identifier types it takes are not published yet. Its examples use 16-character Canadian UWIs, such as `100091802103W500` |

To join EVA results to Novi UDM Data for US wells, match `Header.EntityName` to `WELL.NATIVE_ID`. Both hold the API10. Normalize both sides to 10 digits first.

How Novi UDM Data builds `WELL_KEY` and `WELLBORE_KEY`: [Well identifiers](https://developers.novilabs.com/data/identifiers/).

## Well and wellbore

A well is the surface location and its regulatory record. A wellbore is a hole drilled from it. One well can have several wellbores.

| Product | Grain of a row |
| --- | --- |
| Novi UDM Data (v4) | Well-level attributes join on `WELL_KEY`. Production, completions, tests, spacing and forecasts are per wellbore and join on `WELLBORE_KEY`. Count wells with `COUNT(DISTINCT WELL_KEY)` |
| Novi Forecasts API | An existing well is a wellbore, keyed by `wellbore_key`. A planned well is one drawn lateral |
| Novi EVA API | One row per well, keyed by `Header.EntityName` |

## Plan wells in other tools

Planned wells have no API number. To keep them in step with another tool, key them on `well_uid`. Exports write it when you send `identity.well_id: "uid"`. See [Partner sync](https://developers.novilabs.com/forecasts/guides/partner-sync/).

## Planned

| Item | Status |
| --- | --- |
| Canadian wells in Novi UDM Data, keyed on `UWI-DLS`, for example `CA:UWI-DLS:00/02-13-069-09W5/0:0` | [Planned] |
| US wellbores in Novi UDM Data keyed on API14 | [Planned] |
