Build type curves from existing wells
Production type curves of existing wells: the spread of their actual cumulative volumes and daily rates at each ip_day (days since first production).
Build type curves from existing wells
/wells/typecurveProduction type curves of existing wells: the spread of their actual cumulative volumes and daily rates at each ip_day (days since first production). Use it for an analog type curve: a formation's recent wells, a unit's wells, or a forecast's contributing wells.
Wells
By key (wells), GET /wells' filters and ranges, a unit (area or polygon with buffer_ft and match, as POST /wells/search), bbox or near, all combined, except a unit with bbox or near. Without one of those three, wells without a location count too; with one, a keyed well without a location is counted in excluded.no_location.
What comes back
Per ip_day: how many wells reach it, their plain mean and the quantiles asked (q10, q50 and q90 by default). These are quantiles of wells: q10 is the 10th-percentile well, not Novi's per-well P10. Under min_wells wells, both are null. Wells align on ip_day, not peak, and count while their history reaches it, so the tail is fewer, older wells. A rate is the average daily rate over the step ending at the ip_day. BOE is oil + gas / 6, for wells with both; on a set serving only one of oil and gas, BOE is that one alone (gas / 6).
Normalizing
normalize_lateral_ft scales each well linearly to that lateral (1000: per 1,000 ft), leaving out and counting wells without one. min_lateral_ft leaves out shorter laterals, whose scaled volumes swell (excluded.short_lateral). pooled: true adds pooled: the wells' summed values over their summed laterals × normalize_lateral_ft, so a long lateral weighs more than in mean; null where mean is.
A fixed cohort
cohort_ip_day keeps only wells with every asked stream and measure at every 30-day ip_day up to it (BOE needs oil and gas), so a cumulative line can't fall as wells drop out. ip_days then defaults to every 30 days up to it (none when fewer than min_wells are left), and any sent must be multiples of 30 up to it (else a 400). Left-out wells are counted in excluded.short_history; groups are cut from the cohort.
First month
A well first producing in the dataset's first production month (GET /dataset first_production) may have produced earlier. exclude_floor: true leaves those wells out (excluded.floor) unless their til_date is in that month; GET /wells/{key}?include=floors marks them.
Exclusions
Floor, short lateral and short history apply after the other reasons, in that order; a well counts under the first, and each excluded key is present only when its option is sent.
More
group_by gives one curve per formation, operator or first-production year (the 12 largest). include: ["wells"] adds each well's series, up to 100 wells.
Limits
1,000 keys, 240 ip_days (1 or multiples of 30, up to 7,200), and a scope of 25,000 wells (400 with details.max and details.count: narrow it). On a set serving fewer than three streams, streams defaults to its own and BOE, and naming another is a 400.
Errors
400 with details.field. No match is a 200 with used: 0 and one empty curve, or no curves with group_by.
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
Which wells, and what to compute; every key is optional.
wellsarray of stringsOptional1 to 1000 itemsItems 1 to 200 characters
Only these wells, 1 to 1,000; a repeat counts once, and a key the dataset lacks is a 400 naming the first (
details.key). A key's well without a location is used unless bbox, near or a unit is sent; then it counts in excluded.no_location.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.
operatorsarray of stringsOptionalup to 50 itemsItems up to 100 characters
Only wells of these operators, at most 50.
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.
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.
Show all 67 fields
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.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"bboxarray of numbersOptional4 items
Only wells whose lateral midpoint is inside [west, south, east, north]. Not with area or polygon.
near[number, number]OptionalOnly wells within radius_mi of this point, [lng, lat], to the lateral midpoint. Not with area or polygon.
radius_minumberOptionalDefault
5> 0, ≤ 100With near: how far from it, miles, greater than 0 and at most 100; default 5.
streamsarray of stringsOptional1 to 4 itemsunique items
Streams to compute; default all four.
"oil""gas""water""boe"measuresarray of stringsOptional1 to 2 itemsunique items
Measures; default both.
"cum""rate"normalize_lateral_ftnumberOptional≥ 100, ≤ 20000
Scale each well's volumes and rates to this lateral length: × normalize_lateral_ft / its lateral_length, so 1000 gives per 1,000 ft of lateral and a planned well's length compares others to it. 100 to 20,000.
ip_daysarray of integersOptional1 to 240 itemsItems ≥ 1, ≤ 7200
The ip_days to compute, at most 240 (a repeat counts once in the answer); default every 30 days from 30 to the last ip_day at least min_wells wells reach, up to 7,200 (20 years); with cohort_ip_day, every 30 days from 30 to it, and only multiples of 30 up to it may be sent.
quantilesarray of integersOptional1 to 9 itemsunique itemsItems ≥ 1, ≤ 99
Quantiles across wells: whole percentiles 1 to 99, at most 9 different ones, as 10,25,50,75,90 for a box plot;
quantilesthen holds exactlyq10,q25and so on. Quantiles of wells' values (type 7, q10 the low end), not P-level bands. Default 10, 50 and 90.min_wellsintegerOptionalDefault
5≥ 1, ≤ 1000Fewest wells at an ip_day for its mean and quantiles; below it they are null and the count still shows. An analog overlay sends 1.
group_bystringOptionalOne curve per formation, operator or first-production year: the 12 with the most wells, the rest counted in groups_left_out.
"formation""operator""first_year"includearray of stringsOptionalup to 1 itemsunique items
Extras; wells takes at most 100 wells used (400 past it, with details.max and details.count).
"wells"cohort_ip_dayintegerOptional≥ 30, ≤ 7200multiple of 30
A fixed cohort, a multiple of 30: only wells with a value for every asked stream and measure at every 30-day ip_day from 30 to this one, so each series has the same wells there. Wells left out count in excluded.short_history.
ip_days then defaults to every 30 days to it; ip_days sent must be multiples of 30 up to it (400 on ip_days).
min_lateral_ftnumberOptional≥ 1, ≤ 20000
With normalize_lateral_ft only (without it, a 400): leave out wells whose lateral is shorter than this many ft, counted in excluded.short_lateral. 1 to 20,000.
exclude_floorbooleanOptionalDefault
falsetrue: leave out wells whose first production is in the dataset's first production month (GET /dataset first_production), unless their til_date is in that month too, counted in excluded.floor. Absent or false: no floor key.
pooledbooleanOptionalDefault
falsetrue, with normalize_lateral_ft only (without it, a 400 on pooled): each series also gets pooled, Σ value / Σ lateral × normalize_lateral_ft at each ip_day over the wells reaching it: their per-foot figure taken together, where mean and the quantiles scale each well first. Absent or false: no pooled key.
Responses
200 OK
The type curves.
wellsintegerRequired≥ 0
Wells matching the scope.
usedintegerRequired≥ 0
Of them, those used: on POST /wells/typecurve, with production, a lateral when normalizing, and not left out by exclude_floor, min_lateral_ft or cohort_ip_day; on GET /plans/{id}/typecurve/{design}, with a forecast for the design.
excludedobjectRequiredWells left out, and why: wells is used plus these. floor, short_lateral and short_history are present only with their options and count each well under the first that leaves it out, in that order.
ShowHide 7 child fields
no_productionintegerRequired≥ 0
Wells without production.
no_lateralintegerRequired≥ 0
With normalize_lateral_ft, wells with production but without a lateral.
no_locationintegerRequired≥ 0
With bbox, near or a unit: keyed wells (wells) without a location, which no spatial scope can place.
floorintegerOptional≥ 0
With exclude_floor: true, wells whose first production is in the dataset's first production month, without a til_date in it.
short_lateralintegerOptional≥ 0
With min_lateral_ft, wells with a shorter lateral.
short_historyintegerOptional≥ 0
With cohort_ip_day, wells without a value for every asked stream and measure at every 30-day ip_day to it.
no_forecastintegerOptional≥ 0
GET /plans/{id}/typecurve/{design} only: plan wells without a forecast for the design, as they couldn't be placed or the forecast failed.
normalize_lateral_ftnumber or nullRequiredThe lateral every well was scaled to, ft; null without normalize_lateral_ft.
min_wellsintegerRequired≥ 1
Fewest wells for a mean and quantiles.
unitsobjectRequiredUnits: bbl, mcf, bbl and BOE, rates per day.
ShowHide 5 child fields
oilstringRequiredOil volumes.
gasstringRequiredGas volumes.
waterstringRequiredWater volumes.
boestringRequiredBOE volumes.
ratestringRequiredRates are those units per day.
ip_daysarray of integersRequiredThe ip_days every series is parallel to.
curvesarray of objectsRequiredOne curve, or with group_by one per group, most wells first; with group_by and no wells used, empty.
ShowHide 4 child fields in each item
groupstring or integer or nullRequiredThe formation, operator or first-production year, or on a plan the pad key; null without group_by, or for the wells without that value.
wellsintegerRequired≥ 0
Wells in this curve.
streamsobjectRequiredThe asked streams.
ShowHide 4 child fields
oilobjectOptionaloil: the asked measures.
ShowHide 2 child fields
cumobjectOptionalOne measure across wells, parallel to ip_days.
ShowHide 3 child fields
wellsarray of integersRequiredItems ≥ 0
How many wells reach each ip_day: on POST /wells/typecurve without cohort_ip_day, later ip_days describe fewer, older wells; on GET /plans/{id}/typecurve/{design}, the wells used with a finite value for this stream and measure there.
meanarray of numbersRequiredMeans.
pooledarray of numbersOptionalWith pooled: true only.
rateobjectOptionalOne measure across wells, parallel to ip_days.
Same fields as TypeCurveSeries.
gasobjectOptionalgas: the asked measures.
ShowHide 2 child fields
cumobjectOptionalOne measure across wells, parallel to ip_days.
Same fields as TypeCurveSeries.
rateobjectOptionalOne measure across wells, parallel to ip_days.
Same fields as TypeCurveSeries.
waterobjectOptionalwater: the asked measures.
ShowHide 2 child fields
cumobjectOptionalOne measure across wells, parallel to ip_days.
Same fields as TypeCurveSeries.
rateobjectOptionalOne measure across wells, parallel to ip_days.
Same fields as TypeCurveSeries.
boeobjectOptionalboe: the asked measures.
ShowHide 2 child fields
cumobjectOptionalOne measure across wells, parallel to ip_days.
Same fields as TypeCurveSeries.
rateobjectOptionalOne measure across wells, parallel to ip_days.
Same fields as TypeCurveSeries.
namestringOptionalOn GET /plans/{id}/typecurve/{design} with group_by=pad, the pad's name when the plan gives one in
pads[].name; absent otherwise.groupstays the pad key.
groups_left_outintegerRequired≥ 0
With group_by, the groups past the largest; else 0.
cohort_ip_dayintegerOptional≥ 30
The cohort_ip_day sent; only with it.
well_seriesobjectOptionalWith include: ["wells"]: each well's own series.
ShowHide 4 child fields
wellbore_keyarray of stringsRequiredThe wells used, in key order.
well_namearray of stringsRequiredTheir names.
lateral_lengtharray of numbersRequiredTheir laterals, ft.
streamsobjectRequiredThe asked streams and measures.
ShowHide 4 child fields
oilobjectOptionaloil: the asked measures.
ShowHide 2 child fields
cumarray of arraysOptionalOne per well, in wellbore_key order.
ratearray of arraysOptionalOne per well, in wellbore_key order.
gasobjectOptionalgas: the asked measures.
ShowHide 2 child fields
cumarray of arraysOptionalOne per well, in wellbore_key order.
ratearray of arraysOptionalOne per well, in wellbore_key order.
waterobjectOptionalwater: the asked measures.
ShowHide 2 child fields
cumarray of arraysOptionalOne per well, in wellbore_key order.
ratearray of arraysOptionalOne per well, in wellbore_key order.
boeobjectOptionalboe: the asked measures.
ShowHide 2 child fields
cumarray of arraysOptionalOne per well, in wellbore_key order.
ratearray of arraysOptionalOne per well, in wellbore_key order.
Errors
| Status | When |
|---|---|
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean