Skip to content
Developers
Get an API token

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

POST/wells/typecurve

Production 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.

Send a Novi API token as a bearer token on every request. Authentication
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_setstringOptional

    pattern ^[a-z0-9][a-z0-9-]{0,62}$

    The model set to answer from, an id from GET /model-sets. Absent: the set GET /model-sets names as default, the base dataset unless the server answers from a published set.

    • model_set=default reaches 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 once default is 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's plan.id, or a comparison's a.plan and b.plan, also under source.comparison) reaches it without model_set.
    • An explicit model_set wins; naming resources of two sets in one request is a 400.

Request bodyRequired

application/json

Which wells, and what to compute; every key is optional.

  • wellsarray of stringsOptional

    1 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 arrayOptional

    up to 50 itemsItems up to 100 characters

    Only these formations: a name, names separated by commas, or an array of names, case-insensitive.

  • qstringOptional

    up to 100 characters

    Only wells whose name or wellbore key contains this text, ignoring case.

  • operatorstringOptional

    up to 100 characters

    Only wells whose operator contains this text, ignoring case.

  • operatorsarray of stringsOptional

    up to 50 itemsItems up to 100 characters

    Only wells of these operators, at most 50.

  • countystring or arrayOptional

    up 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_minnumberOptional

    Only wells whose lateral_length is at least this, in ft.

  • lateral_length_maxnumberOptional

    Only wells whose lateral_length is at most this, in ft.

  • tvd_td_minnumberOptional

    Only wells whose tvd_td is at least this, in ft.

  • tvd_td_maxnumberOptional

    Only wells whose tvd_td is at most this, in ft.

  • cum_oil_12_minnumberOptional

    Only wells whose cum_oil_12 is at least this, in bbl.

  • cum_oil_12_maxnumberOptional

    Only wells whose cum_oil_12 is at most this, in bbl.

Show all 67 fields
  • cum_gas_12_minnumberOptional

    Only wells whose cum_gas_12 is at least this, in mcf.

  • cum_gas_12_maxnumberOptional

    Only wells whose cum_gas_12 is at most this, in mcf.

  • cum_boe_12_minnumberOptional

    Only wells whose cum_boe_12 is at least this, in BOE.

  • cum_boe_12_maxnumberOptional

    Only wells whose cum_boe_12 is at most this, in BOE.

  • cum_oil_life_minnumberOptional

    Only wells whose cum_oil_life is at least this, in bbl.

  • cum_oil_life_maxnumberOptional

    Only wells whose cum_oil_life is at most this, in bbl.

  • cum_gas_life_minnumberOptional

    Only wells whose cum_gas_life is at least this, in mcf.

  • cum_gas_life_maxnumberOptional

    Only wells whose cum_gas_life is at most this, in mcf.

  • cum_boe_life_minnumberOptional

    Only wells whose cum_boe_life is at least this, in BOE.

  • cum_boe_life_maxnumberOptional

    Only wells whose cum_boe_life is at most this, in BOE.

  • total_proppant_minnumberOptional

    Only wells whose total_proppant is at least this, in lb.

  • total_proppant_maxnumberOptional

    Only wells whose total_proppant is at most this, in lb.

  • total_fluid_minnumberOptional

    Only wells whose total_fluid is at least this, in bbl.

  • total_fluid_maxnumberOptional

    Only wells whose total_fluid is at most this, in bbl.

  • stage_count_minnumberOptional

    Only wells whose stage_count is at least this, in stages.

  • stage_count_maxnumberOptional

    Only wells whose stage_count is at most this, in stages.

  • first_year_minnumberOptional

    Only wells whose first_year is at least this, in years.

  • first_year_maxnumberOptional

    Only wells whose first_year is at most this, in years.

  • fluid_bbl_per_ft_minnumberOptional

    Only wells whose fluid_bbl_per_ft is at least this, in bbl/ft.

  • fluid_bbl_per_ft_maxnumberOptional

    Only wells whose fluid_bbl_per_ft is at most this, in bbl/ft.

  • proppant_lb_per_ft_minnumberOptional

    Only wells whose proppant_lb_per_ft is at least this, in lb/ft.

  • proppant_lb_per_ft_maxnumberOptional

    Only wells whose proppant_lb_per_ft is at most this, in lb/ft.

  • cum_boe_12_per_1000_ft_minnumberOptional

    Only wells whose cum_boe_12_per_1000_ft is at least this, in BOE per 1,000 ft of lateral.

  • cum_boe_12_per_1000_ft_maxnumberOptional

    Only wells whose cum_boe_12_per_1000_ft is at most this, in BOE per 1,000 ft of lateral.

  • cum_oil_12_per_1000_ft_minnumberOptional

    Only wells whose cum_oil_12_per_1000_ft is at least this, in bbl per 1,000 ft of lateral.

  • cum_oil_12_per_1000_ft_maxnumberOptional

    Only wells whose cum_oil_12_per_1000_ft is at most this, in bbl per 1,000 ft of lateral.

  • cum_gas_12_per_1000_ft_minnumberOptional

    Only wells whose cum_gas_12_per_1000_ft is at least this, in mcf per 1,000 ft of lateral.

  • cum_gas_12_per_1000_ft_maxnumberOptional

    Only wells whose cum_gas_12_per_1000_ft is at most this, in mcf per 1,000 ft of lateral.

  • first_prod_minstringOptional

    Format date

    Only wells whose first_prod is on or after this day, YYYY-MM-DD.

  • first_prod_maxstringOptional

    Format date

    Only wells whose first_prod is on or before this day, YYYY-MM-DD.

  • last_prod_minstringOptional

    Format date

    Only wells whose last_prod is on or after this day, YYYY-MM-DD.

  • last_prod_maxstringOptional

    Format date

    Only wells whose last_prod is on or before this day, YYYY-MM-DD.

  • frac_date_minstringOptional

    Format date

    Only wells whose frac_date is on or after this day, YYYY-MM-DD.

  • frac_date_maxstringOptional

    Format date

    Only wells whose frac_date is on or before this day, YYYY-MM-DD.

  • til_date_minstringOptional

    Format date

    Only wells whose til_date is on or after this day, YYYY-MM-DD.

  • til_date_maxstringOptional

    Format date

    Only wells whose til_date is on or before this day, YYYY-MM-DD.

  • areaobjectOptional

    The 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.

      • typeanyRequired

        Always "Polygon"

        One part.

      • coordinatesarray of arraysRequired

        at least 1 itemsItems at least 3 items

        The outer ring, then its holes.

    • A multipolygon object

      A multipolygon.

      • typeanyRequired

        Always "MultiPolygon"

        Several parts, taken together.

      • coordinatesarray of arraysRequired

        at least 1 itemsItems at least 1 items

        The parts.

  • polygonarray of [number, number]sOptional

    3 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_ftnumberOptional

    Default 0≥ 0, ≤ 5280

    Also take wells within this many feet of the area (0 takes only those inside).

  • matchstringOptional

    Default "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 numbersOptional

    4 items

    Only wells whose lateral midpoint is inside [west, south, east, north]. Not with area or polygon.

  • near[number, number]Optional

    Only wells within radius_mi of this point, [lng, lat], to the lateral midpoint. Not with area or polygon.

  • radius_minumberOptional

    Default 5> 0, ≤ 100

    With near: how far from it, miles, greater than 0 and at most 100; default 5.

  • streamsarray of stringsOptional

    1 to 4 itemsunique items

    Streams to compute; default all four.

    "oil""gas""water""boe"
  • measuresarray of stringsOptional

    1 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 integersOptional

    1 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 integersOptional

    1 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; quantiles then holds exactly q10, q25 and so on. Quantiles of wells' values (type 7, q10 the low end), not P-level bands. Default 10, 50 and 90.

  • min_wellsintegerOptional

    Default 5≥ 1, ≤ 1000

    Fewest 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_bystringOptional

    One 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 stringsOptional

    up 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_floorbooleanOptional

    Default false

    true: 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.

  • pooledbooleanOptional

    Default false

    true, 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.

  • excludedobjectRequired

    Wells 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 nullRequired

    The lateral every well was scaled to, ft; null without normalize_lateral_ft.

  • min_wellsintegerRequired

    ≥ 1

    Fewest wells for a mean and quantiles.

  • unitsobjectRequired

    Units: bbl, mcf, bbl and BOE, rates per day.

    ShowHide 5 child fields
    • oilstringRequired

      Oil volumes.

    • gasstringRequired

      Gas volumes.

    • waterstringRequired

      Water volumes.

    • boestringRequired

      BOE volumes.

    • ratestringRequired

      Rates are those units per day.

  • ip_daysarray of integersRequired

    The ip_days every series is parallel to.

  • curvesarray of objectsRequired

    One 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 nullRequired

      The 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.

    • streamsobjectRequired

      The asked streams.

      ShowHide 4 child fields
      • oilobjectOptional

        oil: the asked measures.

        ShowHide 2 child fields
        • cumobjectOptional

          One measure across wells, parallel to ip_days.

          ShowHide 3 child fields
          • wellsarray of integersRequired

            Items ≥ 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 numbersRequired

            Means.

          • pooledarray of numbersOptional

            With pooled: true only.

        • rateobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

      • gasobjectOptional

        gas: the asked measures.

        ShowHide 2 child fields
        • cumobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

        • rateobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

      • waterobjectOptional

        water: the asked measures.

        ShowHide 2 child fields
        • cumobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

        • rateobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

      • boeobjectOptional

        boe: the asked measures.

        ShowHide 2 child fields
        • cumobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

        • rateobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

    • namestringOptional

      On GET /plans/{id}/typecurve/{design} with group_by=pad, the pad's name when the plan gives one in pads[].name; absent otherwise. group stays 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_seriesobjectOptional

    With include: ["wells"]: each well's own series.

    ShowHide 4 child fields
    • wellbore_keyarray of stringsRequired

      The wells used, in key order.

    • well_namearray of stringsRequired

      Their names.

    • lateral_lengtharray of numbersRequired

      Their laterals, ft.

    • streamsobjectRequired

      The asked streams and measures.

      ShowHide 4 child fields
      • oilobjectOptional

        oil: the asked measures.

        ShowHide 2 child fields
        • cumarray of arraysOptional

          One per well, in wellbore_key order.

        • ratearray of arraysOptional

          One per well, in wellbore_key order.

      • gasobjectOptional

        gas: the asked measures.

        ShowHide 2 child fields
        • cumarray of arraysOptional

          One per well, in wellbore_key order.

        • ratearray of arraysOptional

          One per well, in wellbore_key order.

      • waterobjectOptional

        water: the asked measures.

        ShowHide 2 child fields
        • cumarray of arraysOptional

          One per well, in wellbore_key order.

        • ratearray of arraysOptional

          One per well, in wellbore_key order.

      • boeobjectOptional

        boe: the asked measures.

        ShowHide 2 child fields
        • cumarray of arraysOptional

          One per well, in wellbore_key order.

        • ratearray of arraysOptional

          One per well, in wellbore_key order.

Errors

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean