Skip to content
Developers
Get an API token

Well identity

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

View MarkdownOpen in Claude(opens in a new tab)

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.

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
Anatomy of a Novi UDM Data wellbore key: an API10 exampleThe wellbore key US:API10:4212340567:0 has four parts: COUNTRY, US, an ISO 3166-1 alpha-2 code; NATIVE_ID_TYPE, API10 in the US; NATIVE_ID, 4212340567, the API10 in 10 digits with no hyphens; and SEQUENCE_NUMBER, 0, an ordinal starting at 0. In this API10 example the first three parts, US:API10:4212340567, match the WELL_KEY; all four are the WELLBORE_KEY. Join wellbores to wells on WELLBORE.WELL_KEY, not by trimming the key. API numbers come as API10, the well; API12, the API10 plus two more digits; and API14, a single wellbore or completion. The first 10 digits of every form are the API10, so to match, strip everything that is not a digit and keep the first 10.WELLBORE_KEYWELL_KEY in this exampleUS:API10:4212340567:0SEQUENCE_NUMBEROrdinal, starting at 0NATIVE_IDThe API10: 10 digits, no hyphensNATIVE_ID_TYPEAPI10 in the USCOUNTRYISO 3166-1 alpha-2 codeAPI numbersAPI104212340567The wellAPI124212340567API10 plus two more digitsAPI144212340567A single wellbore or completionFirst 10 digits: the API10To match, strip everything that is not a digit and keep the first 10.Join wellbores to wells on WELLBORE.WELL_KEY, not by trimming the key.Anatomy of a Novi UDM Data wellbore key: an API10 exampleThe wellbore key US:API10:4212340567:0 has four parts: COUNTRY, US, an ISO 3166-1 alpha-2 code; NATIVE_ID_TYPE, API10 in the US; NATIVE_ID, 4212340567, the API10 in 10 digits with no hyphens; and SEQUENCE_NUMBER, 0, an ordinal starting at 0. In this API10 example the first three parts, US:API10:4212340567, match the WELL_KEY; all four are the WELLBORE_KEY. Join wellbores to wells on WELLBORE.WELL_KEY, not by trimming the key. API numbers come as API10, the well; API12, the API10 plus two more digits; and API14, a single wellbore or completion. The first 10 digits of every form are the API10, so to match, strip everything that is not a digit and keep the first 10.WELLBORE_KEYWELL_KEY in this exampleUS:API10:4212340567:012341COUNTRYISO 3166-1 alpha-2 code2NATIVE_ID_TYPEAPI10 in the US3NATIVE_IDThe API10: 10 digits, no hyphens4SEQUENCE_NUMBEROrdinal, starting at 0API numbersAPI104212340567API124212340567API144212340567First 10 digits: the API10API10: The wellAPI12: API10 plus two more digitsAPI14: A single wellbore or completionTo match, strip everything that is not a digit andkeep the first 10.Join wellbores to wells on WELLBORE.WELL_KEY,not by trimming the key.

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.

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;
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"]])
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.

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

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.

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