List the wells in a unit
Lists the existing wells in a unit, taking GET /wells' filters in a JSON body and answering with its response schemas, so a client that reads GET /wells reads this.
List the wells in a unit
/wells/searchLists the existing wells in a unit, taking GET /wells' filters in a JSON body and answering with its response schemas, so a client that reads GET /wells reads this. Each well gains area_distance_ft, and wells come inside first, then nearest.
Scope
Send area or polygon, not both. A well is in the unit when its lateral midpoint (the point GET /wells' bbox filters on) is inside the area, on its edge or within buffer_ft of it. With match: lateral, any part of its lateral counts, which picks up wells that cross the unit's edge.
- Holes are left out and a MultiPolygon's parts count together.
buffer_ftis measured to the nearest edge, a hole's included, on a flat earth about the well. - Rings need at least 3 corners and some area, and at most 200,000 vertices in all, as many as POST /areas reads (400 with
details.maxanddetails.count).areaandpolygonsay which other rings are a 400. - A scope that needs more work than one request may take (about a second) is a 400 "too complex" with
details.max_work, and the same scope always fares the same: simplify the outline, split it or send a smallerbuffer_ft. - Errors are 400 with
details.field.
Filters
GET /wells' query parameters work as they do there, sent as body fields, but for bbox, near and radius_mi: the scope replaces them. operators and keys are arrays, not comma lists, and an empty keys is a 400.
The answer
area_distance_ft is 0 inside the area or on its edge, else feet from it, rounded and at least 1, from the lateral midpoint (with match: lateral, the nearer of it and the lateral). Wells come inside first, then nearest, then by wellbore key; sort replaces that order. To page either format, send the same body again with cursor set to next_cursor. POST /units/summary sums up the same scope by formation and operator, with the grids.
Outlines
outlines takes 1 to 10 scopes in place of area, polygon, buffer_ft and match; errors name outlines[i].area, outlines[i].buffer_ft and so on. A well is kept when it is in every outline without exclude and in none with exclude: true, so an excluded outline's buffer_ft widens what it leaves out.
area_distance_ftis the largest of the well's distances to the outlines withoutexclude, and wells come in that order, then by wellbore key. One outline answers as the same scope sent alone.count, the page totals andcursorcover the kept wells.- A 400 names
outlinesfor none or more than 10, only excluded ones, more than 200,000 vertices over all of them (details.maxanddetails.count), or too much work together ("too complex",details.max_work). outlineswitharea,polygon,buffer_ftormatchis a 400 naming that field.
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
The scope, and GET /wells' filters and paging.
Send exactly one of: area, polygon or outlines.
areaobjectOptionalThe unit as a GeoJSON Polygon or MultiPolygon in WGS 84, with only type and coordinates: an area's geometry from POST /areas. Rings may wind either way and need not repeat their first point; holes are left out. Not with polygon. A hole that isn't inside its outline is a 400 on that ring. Holes are checked in order up to a fixed amount of checking per request; past it a hole is taken as sent.
ShowHide 2 variants
One of
A polygon object
A polygon.
typeanyRequiredAlways
"Polygon"One part.
coordinatesarray of arraysRequiredat least 1 itemsItems at least 3 items
The outer ring, then its holes.
A multipolygon object
A multipolygon.
typeanyRequiredAlways
"MultiPolygon"Several parts, taken together.
coordinatesarray of arraysRequiredat least 1 itemsItems at least 1 items
The parts.
polygonarray of [number, number]sOptional3 to 200001 items
The unit as one ring of corners, in order (closing point optional): an area's fill.polygon, or what POST /layouts/fill takes. Not with area. Edges that cross are a 400, tested on rings of up to 500 corners.
buffer_ftnumberOptionalDefault
0≥ 0, ≤ 5280Also take wells within this many feet of the area (0 takes only those inside).
matchstringOptionalDefault
"midpoint"midpoint: a well is in by its lateral midpoint; lateral: also by any part of its lateral, heel (else surface hole) to bottom hole.
"midpoint""lateral"outlinesarray of objectsOptional1 to 10 items
Several outlines instead of one scope: each its own area or polygon with its own buffer_ft and match. A well is kept when it is in every outline without exclude and in none with exclude: true; at least one must be without exclude. Not with area, polygon, buffer_ft or match.
ShowHide 5 child fields in each item
Send exactly one of:
areaorpolygon.areaobjectOptionalThe unit as a GeoJSON Polygon or MultiPolygon in WGS 84, with only type and coordinates: an area's geometry from POST /areas. Rings may wind either way and need not repeat their first point; holes are left out. Not with polygon. A hole that isn't inside its outline is a 400 on that ring. Holes are checked in order up to a fixed amount of checking per request; past it a hole is taken as sent.
Same fields as UnitArea.
polygonarray of [number, number]sOptional3 to 200001 items
The unit as one ring of corners, in order (closing point optional): an area's fill.polygon, or what POST /layouts/fill takes. Not with area. Edges that cross are a 400, tested on rings of up to 500 corners.
buffer_ftnumberOptionalDefault
0≥ 0, ≤ 5280Also take wells within this many feet of the area (0 takes only those inside).
matchstringOptionalDefault
"midpoint"midpoint: a well is in by its lateral midpoint; lateral: also by any part of its lateral, heel (else surface hole) to bottom hole.
"midpoint""lateral"excludebooleanOptionalDefault
falsetrue: leave out the wells in this outline, by its own match and buffer_ft. Absent or false: keep only the wells in it.
keysarray of stringsOptionalat least 1 itemsItems 1 to 200 characters
Only these wells: wellbore keys, exact, such as
SB329-01414, at most 50 distinct (a repeat counts once). Combines with the unit and every other filter.A key the dataset lacks matches nothing rather than failing. Past the cap is a 400 naming
keyswithdetails.maxanddetails.count; an empty array is a 400 (leavekeysout for every well).formationstring or arrayOptionalup to 50 itemsItems up to 100 characters
Only these formations: a name, names separated by commas, or an array of names, case-insensitive.
qstringOptionalup to 100 characters
Only wells whose name or wellbore key contains this text, ignoring case.
operatorstringOptionalup to 100 characters
Only wells whose operator contains this text, ignoring case.
fieldsstring or arrayOptionalup to 50 itemsItems up to 100 characters
Only these columns or properties, and area_distance_ft; wellbore_key is always there. A name, names separated by commas, or an array.
Format columns:
wellbore_key,well_name,operator,formation,mid_lon,mid_lat,shl_lon,shl_lat,heel_lon,heel_lat,bhl_lon,bhl_lat,cum_boe_12,first_year. Format geojson:wellbore_key,well_name,operator,formation,first_prod,lateral_length,tvd_td,cum_boe_12,shl_lon,shl_lat,heel_lon,heel_lat,bhl_lon,bhl_lat.Either format also takes
basin,subbasin,state,county,lateral_length,tvd_td,lat,lon,first_prod,last_prod,cum_oil_12,cum_gas_12,cum_boe_12,cum_oil_life,cum_gas_life,cum_boe_life,total_proppant,total_fluid,stage_count,frac_date,til_date,first_year,fluid_bbl_per_ft,proppant_lb_per_ft,cum_boe_12_per_1000_ft,cum_oil_12_per_1000_ft,cum_gas_12_per_1000_ft.These are GET /wells/{key}'s header fields,
first_year, per-ft completions, and 12-month BOE, oil (bbl) and gas (mcf) per 1,000 ft of lateral, after the default fields in that order.Coordinates are rounded to 5 decimals, volumes to whole units, per-ft values to 0.1, and dates are YYYY-MM-DD.
latandlonare the header's point; the map usesmid_lonandmid_lat.formatstringOptionalDefault
"columns"Response layout, as GET /wells: every well as parallel arrays, or a page of GeoJSON Points.
"columns""geojson"limitintegerOptionalDefault
100≥ 1, ≤ 10000The page size: format geojson 1 to 1,000 (default 100); format columns 1 to 10,000, which adds next_cursor, and every well in scope without it.
Show all 59 fields
cursorstring or nullOptionalnext_cursor from the previous page, with the same body, in either format.
sortstringOptionalOrder the wells by this field instead of inside first, then nearest: any name
fieldstakes except the coordinates and the distances. Wells without a value come last in either order; ties go by wellbore key, socursorpages are stable. An unknown name is a 400 withdetails.allowed."wellbore_key""well_name""operator""formation""cum_boe_12""first_year""first_prod""lateral_length""tvd_td""basin""subbasin""state""county""last_prod""cum_oil_12""cum_gas_12""cum_oil_life""cum_gas_life""cum_boe_life""total_proppant"9 more values
"total_fluid""stage_count""frac_date""til_date""fluid_bbl_per_ft""proppant_lb_per_ft""cum_boe_12_per_1000_ft""cum_oil_12_per_1000_ft""cum_gas_12_per_1000_ft"orderstringOptionalDefault
"desc"With
sort(ignored without it):desc, largest or latest first, orasc."asc""desc"countystring or arrayOptionalup to 50 itemsItems up to 100 characters
Only wells in these counties: exact names, case-insensitive; a name, names separated by commas, or an array of at most 50.
operatorsarray of stringsOptionalup to 50 itemsItems up to 100 characters
Only wells of these operators, at most 50; operator stays a substring match.
lateral_length_minnumberOptionalOnly wells whose
lateral_lengthis at least this, in ft.lateral_length_maxnumberOptionalOnly wells whose
lateral_lengthis at most this, in ft.tvd_td_minnumberOptionalOnly wells whose
tvd_tdis at least this, in ft.tvd_td_maxnumberOptionalOnly wells whose
tvd_tdis at most this, in ft.cum_oil_12_minnumberOptionalOnly wells whose
cum_oil_12is at least this, in bbl.cum_oil_12_maxnumberOptionalOnly wells whose
cum_oil_12is at most this, in bbl.cum_gas_12_minnumberOptionalOnly wells whose
cum_gas_12is at least this, in mcf.cum_gas_12_maxnumberOptionalOnly wells whose
cum_gas_12is at most this, in mcf.cum_boe_12_minnumberOptionalOnly wells whose
cum_boe_12is at least this, in BOE.cum_boe_12_maxnumberOptionalOnly wells whose
cum_boe_12is at most this, in BOE.cum_oil_life_minnumberOptionalOnly wells whose
cum_oil_lifeis at least this, in bbl.cum_oil_life_maxnumberOptionalOnly wells whose
cum_oil_lifeis at most this, in bbl.cum_gas_life_minnumberOptionalOnly wells whose
cum_gas_lifeis at least this, in mcf.cum_gas_life_maxnumberOptionalOnly wells whose
cum_gas_lifeis at most this, in mcf.cum_boe_life_minnumberOptionalOnly wells whose
cum_boe_lifeis at least this, in BOE.cum_boe_life_maxnumberOptionalOnly wells whose
cum_boe_lifeis at most this, in BOE.total_proppant_minnumberOptionalOnly wells whose
total_proppantis at least this, in lb.total_proppant_maxnumberOptionalOnly wells whose
total_proppantis at most this, in lb.total_fluid_minnumberOptionalOnly wells whose
total_fluidis at least this, in bbl.total_fluid_maxnumberOptionalOnly wells whose
total_fluidis at most this, in bbl.stage_count_minnumberOptionalOnly wells whose
stage_countis at least this, in stages.stage_count_maxnumberOptionalOnly wells whose
stage_countis at most this, in stages.first_year_minnumberOptionalOnly wells whose
first_yearis at least this, in years.first_year_maxnumberOptionalOnly wells whose
first_yearis at most this, in years.fluid_bbl_per_ft_minnumberOptionalOnly wells whose
fluid_bbl_per_ftis at least this, in bbl/ft.fluid_bbl_per_ft_maxnumberOptionalOnly wells whose
fluid_bbl_per_ftis at most this, in bbl/ft.proppant_lb_per_ft_minnumberOptionalOnly wells whose
proppant_lb_per_ftis at least this, in lb/ft.proppant_lb_per_ft_maxnumberOptionalOnly wells whose
proppant_lb_per_ftis at most this, in lb/ft.cum_boe_12_per_1000_ft_minnumberOptionalOnly wells whose
cum_boe_12_per_1000_ftis at least this, in BOE per 1,000 ft of lateral.cum_boe_12_per_1000_ft_maxnumberOptionalOnly wells whose
cum_boe_12_per_1000_ftis at most this, in BOE per 1,000 ft of lateral.cum_oil_12_per_1000_ft_minnumberOptionalOnly wells whose
cum_oil_12_per_1000_ftis at least this, in bbl per 1,000 ft of lateral.cum_oil_12_per_1000_ft_maxnumberOptionalOnly wells whose
cum_oil_12_per_1000_ftis at most this, in bbl per 1,000 ft of lateral.cum_gas_12_per_1000_ft_minnumberOptionalOnly wells whose
cum_gas_12_per_1000_ftis at least this, in mcf per 1,000 ft of lateral.cum_gas_12_per_1000_ft_maxnumberOptionalOnly wells whose
cum_gas_12_per_1000_ftis at most this, in mcf per 1,000 ft of lateral.first_prod_minstringOptionalFormat
dateOnly wells whose
first_prodis on or after this day, YYYY-MM-DD.first_prod_maxstringOptionalFormat
dateOnly wells whose
first_prodis on or before this day, YYYY-MM-DD.last_prod_minstringOptionalFormat
dateOnly wells whose
last_prodis on or after this day, YYYY-MM-DD.last_prod_maxstringOptionalFormat
dateOnly wells whose
last_prodis on or before this day, YYYY-MM-DD.frac_date_minstringOptionalFormat
dateOnly wells whose
frac_dateis on or after this day, YYYY-MM-DD.frac_date_maxstringOptionalFormat
dateOnly wells whose
frac_dateis on or before this day, YYYY-MM-DD.til_date_minstringOptionalFormat
dateOnly wells whose
til_dateis on or after this day, YYYY-MM-DD.til_date_maxstringOptionalFormat
dateOnly wells whose
til_dateis on or before this day, YYYY-MM-DD.
Responses
200 OK
The wells in scope, inside first.
formatstringRequiredAlways
"columns"Layout.
countintegerRequiredWells.
columnsobjectRequiredParallel arrays, one entry per well. With
fields, only the asked properties are present.ShowHide 41 child fields
wellbore_keyarray of stringsRequiredWellbore keys.
well_namearray of stringsOptionalWell names.
operatorarray of stringsOptionalCurrent operators.
formationarray of stringsOptionalFormations.
mid_lonarray of numbersOptionalLateral midpoint longitude.
mid_latarray of numbersOptionalLateral midpoint latitude.
shl_lonarray of numbersOptionalSurface hole longitude.
shl_latarray of numbersOptionalSurface hole latitude.
heel_lonarray of numbersOptionalHeel longitude (null when not reported).
heel_latarray of numbersOptionalHeel latitude.
bhl_lonarray of numbersOptionalBottom hole longitude.
bhl_latarray of numbersOptionalBottom hole latitude.
Show all 41 fields
cum_boe_12array of numbersOptionalFirst 12 months of production, BOE (gas at 6 mcf per bbl).
first_yeararray of integersOptionalYear of first production.
distance_miarray of numbersOptionalWith near only: great-circle miles from near to the lateral midpoint, rounded to 0.01; the wells come nearest first.
area_distance_ftarray of integersOptionalItems ≥ 0
POST /wells/search only: 0 inside the area or on its edge, else feet from it, rounded and at least 1.
basinarray of stringsOptionalBasin. Only when named in fields.
subbasinarray of stringsOptionalSub-basin. Only when named in fields.
statearray of stringsOptionalState. Only when named in fields.
countyarray of stringsOptionalCounty. Only when named in fields.
lateral_lengtharray of numbersOptionalLateral length, ft. Only when named in fields.
tvd_tdarray of numbersOptionalTVD, ft. Only when named in fields.
latarray of numbersOptionalThe header's latitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lat. Only when named in fields.
lonarray of numbersOptionalThe header's longitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lon. Only when named in fields.
first_prodarray of stringsOptionalFirst production, YYYY-MM-DD. Only when named in fields.
last_prodarray of stringsOptionalLast production, YYYY-MM-DD. Only when named in fields.
cum_oil_12array of numbersOptionalFirst 12 months oil, whole bbl. Only when named in fields.
cum_gas_12array of numbersOptionalFirst 12 months gas, whole mcf. Only when named in fields.
cum_oil_lifearray of numbersOptionalCumulative oil, whole bbl. Only when named in fields.
cum_gas_lifearray of numbersOptionalCumulative gas, whole mcf. Only when named in fields.
cum_boe_lifearray of numbersOptionalCumulative BOE, whole. Only when named in fields.
total_proppantarray of integersOptionalProppant, lb. Only when named in fields.
total_fluidarray of integersOptionalFluid, bbl. Only when named in fields.
stage_countarray of integersOptionalFrac stages. Only when named in fields.
frac_datearray of stringsOptionalFrac date, YYYY-MM-DD. Only when named in fields.
til_datearray of stringsOptionalTurn-in-line date, YYYY-MM-DD. Only when named in fields.
fluid_bbl_per_ftarray of numbersOptionalCompletion fluid per lateral ft, bbl/ft to 0.1: the header's novi_calc_fluid_per_length, the per-well value GET /completions/defaults and POST /units/summary take medians of. Only when named in fields.
proppant_lb_per_ftarray of numbersOptionalProppant per lateral ft, lb/ft to 0.1: the header's novi_calc_proppant_per_length, as fluid_bbl_per_ft. Only when named in fields.
cum_boe_12_per_1000_ftarray of numbersOptionalFirst 12 months of BOE per 1,000 ft of lateral (cum_boe_12 / lateral_length × 1,000, as POST /units/summary computes it), whole BOE. Only when named in fields.
cum_oil_12_per_1000_ftarray of numbersOptionalFirst 12 months of oil per 1,000 ft of lateral (cum_oil_12 / lateral_length × 1,000), whole bbl; null without a 12-month oil volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields.
cum_gas_12_per_1000_ftarray of numbersOptionalFirst 12 months of gas per 1,000 ft of lateral (cum_gas_12 / lateral_length × 1,000), whole mcf; null without a 12-month gas volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields.
next_cursorstring or nullOptionalWith limit or cursor: cursor for the next page, null on the last; count is still every matching well.
appliedobjectOptionalHow the server read
sort,order,county,operators, the_minand_maxranges and, when format=columns is paged,limitandcursor, as {"lateral_length_min": 9000, "sort": "cum_boe_12", "order": "desc"}. Absent when none of them was sent.ShowHide 2 variants in each value
Any of
number, string or boolean number, string or boolean or null
array of strings array of strings
Errors
| Status | When |
|---|---|
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean