Estimate TVD for well paths
How deep each well would land in its formation: its formation's structure top at the well plus the median depth below that top at which nearby same-formation wells land.
Estimate TVD for well paths
/tvd-estimatesHow deep each well would land in its formation: its formation's structure top at the well plus the median depth below that top at which nearby same-formation wells land. Forecasts make the same estimate when tvd_ft is blank.
Nearby wells
Only wells with production (a first_prod date) and a header tvd_td that isn't a multiple of 500 ft count; such a header is taken for a placeholder, except in a set whose depth pack says its wells are subsea.
- An estimate needs 3 of them. The search starts within about 2 miles and widens to about 4, then 8 miles (
sourcenames the distance;wells_scopestays nearby), then takes the formation-wide landing, which needs 3 too. - With no grid at the well, or neither landing, the estimate is the nearby wells' median TVD (
method: nearby_wells). Fewer than 3 within about 8 miles givestvd_ft: nulland anerror.
Checks
checks flags an estimate at or below the next formation's top (below_next_top) or nearby wells that land outside the zone (landing_far_from_formation); see checks. Estimates aren't clamped to the zone, except in a set labelled from its own structure grids (formation_labels in GET /model-sets) with a depth pack: there a structure_grid estimate above its formation's top or below its base lands a foot inside the nearer one, and source says so and gives the median.
Landing fraction
A well's landing_fraction lands it at that fraction of its formation's thickness, from the grids alone, as POST /forecasts lands one (see landing_fraction). Its answer adds formation_base_ft and thickness_ft; a well that can't be landed so gets tvd_ft: null and an error naming landing_fraction.
Depth packs
A depth pack can hold TVD-only structure and thickness grids for formations the set's own model doesn't grid. Estimates, landing fields and gun-barrel tops use them as they use the set's; nothing else reads them (GET /subsurface, GET /formations, a forecast's subsurface values and model inputs, exports).
Datum
Tops and TVDs are in the set's TVD datum.
- With a depth pack (the answer carries
tvd_datum), it is the wells' kelly bushing (KB), as header TVDs are: a top is the grid's subsea depth plus the KB elevation at the surface hole, and a nearby well's landing is its TVD less its own top. A pack can instead declare KB TVD structure grids. - Where the pack has no ground elevation, a nearby well is left out of the median, a well is estimated as one with no grid there, and an entered
landing_below_top_ftorlanding_fractiongetstvd_ft: nulland anerror. - Without a depth pack (no
tvd_datum), tops are the grid's own subsea depth.
Parameters
Query parameters
model_setstringOptionalpattern ^[a-z0-9][a-z0-9-]{0,62}$
The model set to answer from, an
idfrom GET /model-sets. Absent: the set GET /model-sets names asdefault, the base dataset unless the server answers from a published set.model_set=defaultreaches the base dataset; once the server retires it, a 400 naming the set answering instead.- An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in
details.allowed(published sets only oncedefaultis retired); a set that can't load, a 503 with the reason. - Plans and exports stay in their set: a call naming them (by path,
plan,ids,source.plan, a scenario'splan.id, or a comparison'sa.planandb.plan, also undersource.comparison) reaches it withoutmodel_set. - An explicit
model_setwins; naming resources of two sets in one request is a 400.
Request body
application/json
Well paths and formations, 1 to 1,000.
wellsarray of objectsRequired1 to 1000 items
Well paths.
ShowHide 4 child fields in each item
shl[number, number]RequiredA point as [longitude, latitude] in WGS 84 degrees.
bhl[number, number]RequiredA point as [longitude, latitude] in WGS 84 degrees.
formationstringRequiredTarget formation.
landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.
The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.
The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.
Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.
Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:
- its formation has no grid there or no place in the column;
- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
- top and base averaged over the ends are under a foot apart: the zone pinches out.
A well's inputs echo it when it was sent.
Responses
200 OK
One estimate per well, in request order.
estimatesarray of objectsRequiredOne per well.
ShowHide 14 child fields in each item
indexintegerRequiredRequest position.
formationstringRequiredFormation.
tvd_ftnumber or nullRequiredEstimated TVD, ft.
sourcestring or nullRequiredHow it was estimated.
methodstring or nullRequiredstructure_grid: grid top plus landing (or, with landing_fraction, that fraction of the thickness); nearby_wells: median TVD of nearby wells.
"structure_grid""nearby_wells"formation_top_ftintegerOptionalFormation top at the well, ft below the set's TVD datum (tvd_datum; without it, the grid's subsea depth).
landing_below_top_ftintegerOptionalMedian landing below the top, ft; not with landing_fraction.
formation_base_ftintegerOptionalWith landing_fraction: the formation's base at the well, in formation_top_ft's datum: the structure top of the next surface down the rock column with a grid there.
- It is averaged over the same ends as formation_top_ft (those both grids reach).
- When the set's depth pack names a thickness grid, it is formation_top_ft plus that grid instead.
- With a depth pack, a formation with no gridded formation below it at the well takes formation_top_ft plus its novi_thickness_avg grid.
- source names the surface or grid used.
thickness_ftintegerOptionalWith landing_fraction: base less top at the well, ft. tvd_ft is top + landing_fraction × thickness on the unrounded values, so it may be a foot off the sum of the rounded fields.
wells_usedintegerOptionalWells behind the landing or median.
wells_scopestringOptionalnearby (about 2 miles, or as source says when the search widened) or formation (formation-wide).
"nearby""formation"errorstringOptionalWhy there is no estimate.
checksarray of stringsOptionalPresent only when a check fires: the estimate may be off, so check it or send tvd_ft.
- below_next_top: tvd_ft is at or below the next formation top down at this well, so the well may land in the formation below. Check the TVD.
- That top is the shallowest structure top of another formation (a depth pack's TVD-only grids included) deeper than this one's here, in formation_top_ft's datum, ordered by the grids at the well, not GET /formations.
- The two are averaged over only the ends (shl, bhl) both grids reach; a grid sharing no end with this formation's is left out.
- landing_far_from_formation: structure_grid estimates with wells_scope nearby only, never on landing_fraction answers. Check the nearby wells.
- It fires when the nearby median landing before any move inside the zone (so it can differ from landing_below_top_ft) is outside the zone here, above the top or more than the thickness below it, and over that thickness from the formation-wide median of 3 or more wells.
- Thickness as landing_fraction measures it. A nearby landing inside the zone never fires it. Not checked without a formation-wide median or a thickness.
"below_next_top""landing_far_from_formation"- below_next_top: tvd_ft is at or below the next formation top down at this well, so the well may land in the formation below. Check the TVD.
landing_checkobjectOptionalWith landing_far_from_formation only: nearby_ft is outside the zone, below 0 or above thickness_ft, and differs from formation_ft by more than thickness_ft. Rounded from the values compared, so they may be a foot off either limit.
ShowHide 3 child fields
nearby_ftintegerRequiredNearby wells' median landing below the top before any move inside the zone, ft.
formation_ftintegerRequiredFormation-wide median landing below the top from 3 or more wells, ft.
thickness_ftintegerRequiredFormation thickness at the well, measured as landing_fraction measures it, ft.
tvd_datumobjectOptionalOptional: the TVD datum the set's depth pack puts tops in, present only for a model set with a depth pack. Absent: tops are the structure grid's own subsea depth. POST /gun-barrels with datum subsea adds subsea: true when it answers below sea level, as every answer does for a pack whose wells are subsea.
ShowHide 4 child fields
datumstringRequiredkb: tops and TVDs are ft below the kelly bushing, the datum of the set's header TVDs. subsea true overrides it: every depth in that answer is ft below sea level, whatever datum says.
"kb"kb_offset_ftnumber or nullRequiredThe KB height above ground, ft, added to the ground elevation; when the set's structure grids already are KB TVDs, as the pack declares it (null if it declares none); null when the set's well TVDs already are ft below sea level.
elevation_sourcestring or nullRequiredWhere the ground elevation comes from (as USGS 3DEP bare earth); null when the set's structure grids already are KB TVDs or its well TVDs already are ft below sea level.
subseabooleanOptionalPresent, and true, when the answer's depths are ft below sea level (TVDss); absent, they are in
datum. Label depths by subsea === true, not by datum, which stays kb in a subsea answer.Present on a POST /gun-barrels answer to datum subsea for a pack with ground elevation. Also on every POST /tvd-estimates and POST /gun-barrels answer for a pack whose wells' TVDs already are subsea, with or without datum subsea: tops are the grid's own subsea depth and every TVD (header, estimated or sent) stays as it is.
Errors
| Status | When |
|---|---|
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean