Skip to content
Developers
Get an API token

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

POST/wells/search

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. Each well gains area_distance_ft, and wells come inside first, then nearest.

Send a Novi API token as a bearer token on every request. Authentication
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_ft is 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.max and details.count). area and polygon say 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 smaller buffer_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_ft is the largest of the well's distances to the outlines without exclude, and wells come in that order, then by wellbore key. One outline answers as the same scope sent alone.
  • count, the page totals and cursor cover the kept wells.
  • A 400 names outlines for none or more than 10, only excluded ones, more than 200,000 vertices over all of them (details.max and details.count), or too much work together ("too complex", details.max_work).
  • outlines with area, polygon, buffer_ft or match is a 400 naming that field.

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

The scope, and GET /wells' filters and paging.

Send exactly one of: area, polygon or outlines.

  • 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"
  • outlinesarray of objectsOptional

    1 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: area or polygon.

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

      Same fields as UnitArea.

    • 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"
    • excludebooleanOptional

      Default false

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

    at 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 keys with details.max and details.count; an empty array is a 400 (leave keys out for every well).

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

  • fieldsstring or arrayOptional

    up 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. lat and lon are the header's point; the map uses mid_lon and mid_lat.

  • formatstringOptional

    Default "columns"

    Response layout, as GET /wells: every well as parallel arrays, or a page of GeoJSON Points.

    "columns""geojson"
  • limitintegerOptional

    Default 100≥ 1, ≤ 10000

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

    next_cursor from the previous page, with the same body, in either format.

  • sortstringOptional

    Order the wells by this field instead of inside first, then nearest: any name fields takes except the coordinates and the distances. Wells without a value come last in either order; ties go by wellbore key, so cursor pages are stable. An unknown name is a 400 with details.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"
  • orderstringOptional

    Default "desc"

    With sort (ignored without it): desc, largest or latest first, or asc.

    "asc""desc"
  • 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.

  • operatorsarray of stringsOptional

    up to 50 itemsItems up to 100 characters

    Only wells of these operators, at most 50; operator stays a substring match.

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

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

Responses

200 OK

The wells in scope, inside first.

  • formatstringRequired

    Always "columns"

    Layout.

  • countintegerRequired

    Wells.

  • columnsobjectRequired

    Parallel arrays, one entry per well. With fields, only the asked properties are present.

    ShowHide 41 child fields
    • wellbore_keyarray of stringsRequired

      Wellbore keys.

    • well_namearray of stringsOptional

      Well names.

    • operatorarray of stringsOptional

      Current operators.

    • formationarray of stringsOptional

      Formations.

    • mid_lonarray of numbersOptional

      Lateral midpoint longitude.

    • mid_latarray of numbersOptional

      Lateral midpoint latitude.

    • shl_lonarray of numbersOptional

      Surface hole longitude.

    • shl_latarray of numbersOptional

      Surface hole latitude.

    • heel_lonarray of numbersOptional

      Heel longitude (null when not reported).

    • heel_latarray of numbersOptional

      Heel latitude.

    • bhl_lonarray of numbersOptional

      Bottom hole longitude.

    • bhl_latarray of numbersOptional

      Bottom hole latitude.

    Show all 41 fields
    • cum_boe_12array of numbersOptional

      First 12 months of production, BOE (gas at 6 mcf per bbl).

    • first_yeararray of integersOptional

      Year of first production.

    • distance_miarray of numbersOptional

      With near only: great-circle miles from near to the lateral midpoint, rounded to 0.01; the wells come nearest first.

    • area_distance_ftarray of integersOptional

      Items ≥ 0

      POST /wells/search only: 0 inside the area or on its edge, else feet from it, rounded and at least 1.

    • basinarray of stringsOptional

      Basin. Only when named in fields.

    • subbasinarray of stringsOptional

      Sub-basin. Only when named in fields.

    • statearray of stringsOptional

      State. Only when named in fields.

    • countyarray of stringsOptional

      County. Only when named in fields.

    • lateral_lengtharray of numbersOptional

      Lateral length, ft. Only when named in fields.

    • tvd_tdarray of numbersOptional

      TVD, ft. Only when named in fields.

    • latarray of numbersOptional

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

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

      First production, YYYY-MM-DD. Only when named in fields.

    • last_prodarray of stringsOptional

      Last production, YYYY-MM-DD. Only when named in fields.

    • cum_oil_12array of numbersOptional

      First 12 months oil, whole bbl. Only when named in fields.

    • cum_gas_12array of numbersOptional

      First 12 months gas, whole mcf. Only when named in fields.

    • cum_oil_lifearray of numbersOptional

      Cumulative oil, whole bbl. Only when named in fields.

    • cum_gas_lifearray of numbersOptional

      Cumulative gas, whole mcf. Only when named in fields.

    • cum_boe_lifearray of numbersOptional

      Cumulative BOE, whole. Only when named in fields.

    • total_proppantarray of integersOptional

      Proppant, lb. Only when named in fields.

    • total_fluidarray of integersOptional

      Fluid, bbl. Only when named in fields.

    • stage_countarray of integersOptional

      Frac stages. Only when named in fields.

    • frac_datearray of stringsOptional

      Frac date, YYYY-MM-DD. Only when named in fields.

    • til_datearray of stringsOptional

      Turn-in-line date, YYYY-MM-DD. Only when named in fields.

    • fluid_bbl_per_ftarray of numbersOptional

      Completion 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 numbersOptional

      Proppant 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 numbersOptional

      First 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 numbersOptional

      First 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 numbersOptional

      First 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 nullOptional

    With limit or cursor: cursor for the next page, null on the last; count is still every matching well.

  • appliedobjectOptional

    How the server read sort, order, county, operators, the _min and _max ranges and, when format=columns is paged, limit and cursor, 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

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean