Skip to content
Developers
Get an API token

Summarize a unit's wells, grids and completions

What a unit holds, in one request: its area, the existing wells inside and around it by formation, operator and year, each formation's grid ranges, and completion medians.

Summarize a unit's wells, grids and completions

POST/units/summary

What a unit holds, in one request: its area, the existing wells inside and around it by formation, operator and year, each formation's grid ranges, and completion medians. Use it before filling a unit.

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

A median leaves out wells without that value, and is null when none has it.

  • area: measured as POST /areas measures it, so the two agree.
  • wells: those in scope, inside the area and in the buffer, by formation, by operator (the top 10 by wells, then an Other row) and by first-production year.
  • formations: every formation, top to bottom, with its wells in scope and each subsurface grid's min, median and max over the cells (GET /subsurface/grids/{feature_name}'s lattice points) whose centres fall inside the area, not the buffer.
    • Over 2,500 cells in the area's bbox, the first inside each square of a 50 × 50 lattice over the bbox is used, and sampled is true.
    • grids is null for a formation without grids or with no cell inside. For an area smaller than a cell, sample a well path with GET /subsurface/sample.
  • completions: by formation, the median fluid (bbl/ft, to 0.1) and proppant (lb/ft, to 1) of the in-scope wells with both, or empty. The per-well values are those GET /completions/defaults takes medians of, without its 180-day online window, so these cover the unit's wells of every vintage.
Only some formations

formation (a name, names separated by commas, or an array) keeps only those formations' wells, formations and completions.

Before you fill it

The wells inside are the unit's existing wells, but forecasts and plans space each new well against every existing well within the spacing radius (GET /dataset spacing.search_radius_ft), inside the unit or not: send buffer_ft to see those around it. List the wells with POST /wells/search (same scope). Fill the unit with POST /layouts/fill (the same area, every part filled and holes left out, or an area's fill.polygon; and long_axis_azimuth_deg), or as a layout in POST /plans.

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 optionally formations.

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.

    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"
  • formationstring or arrayOptional

    up to 50 itemsItems up to 100 characters

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

Responses

200 OK

The unit.

  • areaobjectRequired

    The area, measured as POST /areas measures it.

    ShowHide 4 child fields
    • acresnumberRequired

      Area, acres, holes taken out.

    • long_axis_azimuth_degintegerRequired

      ≥ -90, ≤ 90

      The bearing of the largest part's longest edge, degrees from north, -90 to 90, as POST /areas reports it.

    • bboxarray of numbersRequired

      4 items

      [west, south, east, north] of the outer rings.

    • in_datasetbooleanRequired

      True when the bbox meets the dataset's (GET /dataset bbox).

  • wellsobjectRequired

    The wells in scope (inside and buffer together, unless counted apart).

    ShowHide 5 child fields
    • insideintegerRequired

      ≥ 0

      Wells in scope inside the area.

    • bufferintegerRequired

      ≥ 0

      Wells in scope outside the area, within buffer_ft.

    • by_formationarray of objectsRequired

      By formation, top to bottom; wells without one last.

      ShowHide 10 child fields in each item
      • formationstring or nullRequired

        Formation, or null for wells without one.

      • wellsintegerRequired

        ≥ 1

        Wells in scope: inside and within buffer_ft.

      • insideintegerRequired

        ≥ 0

        Of them, those inside the area (not in the buffer).

      • median_lateral_ftinteger or nullRequired

        Median lateral length, ft.

      • median_tvd_ftinteger or nullRequired

        Median TVD, ft.

      • median_cum_boe_12integer or nullRequired

        Median first 12 months of production, BOE.

      • total_cum_boe_12integer or nullRequired

        Their first 12 months of production added up, BOE.

      • median_cum_boe_12_per_1000_ftinteger or nullRequired

        Median of each well's 12-month BOE per 1,000 ft of lateral, BOE.

      • first_prod_earlieststring or nullRequired

        Format date

        Earliest first production.

      • first_prod_lateststring or nullRequired

        Format date

        Latest first production.

    • by_operatorarray of objectsRequired

      The 10 operators with the most wells (ties by name), then Other.

      ShowHide 3 child fields in each item
      • operatorstring or nullRequired

        Operator, Other on the last row when there are more, or null for wells without one.

      • wellsintegerRequired

        ≥ 1

        Wells in scope.

      • othersintegerOptional

        ≥ 1

        On the Other row only: how many operators it sums.

    • by_first_yeararray of objectsRequired

      By year, oldest first; wells without one last.

      ShowHide 2 child fields in each item
      • yearinteger or nullRequired

        Year of first production, or null.

      • wellsintegerRequired

        ≥ 1

        Wells in scope.

  • formationsarray of objectsRequired

    Every formation, top to bottom (only the asked ones with formation).

    ShowHide 6 child fields in each item
    • formationstringRequired

      Formation.

    • labelstringRequired

      Display name.

    • wellsintegerRequired

      ≥ 0

      Wells in scope landed in it: inside and within buffer_ft.

    • insideintegerRequired

      ≥ 0

      Of them, those inside the area (not in the buffer).

    • has_gridsbooleanRequired

      True when it has subsurface grids.

    • gridsobject or nullRequired

      By rock property (novi_structuraldepth, novi_thickness_avg, ...): the grid over the cells inside the area, or null when it has none there. Null without grids or with no cell inside.

      ShowHide 7 child fields in each value
      • feature_namestringRequired

      • unitstring or nullRequired

        ft, fraction, or null when unknown.

      • cellsintegerRequired

        ≥ 1

        Grid cells inside the area with a value, after any sampling.

      • sampledbooleanRequired

        True when a coarser lattice was used (more cells than the cap lie in the area's bbox).

      • minnumberRequired

        Smallest value, 5 significant digits.

      • mediannumberRequired

        Median value.

      • maxnumberRequired

        Largest value.

  • completionsarray of objectsRequired

    By formation, top to bottom; empty when no in-scope well has completions.

    ShowHide 4 child fields in each item
    • formationstring or nullRequired

      Formation, or null.

    • fluid_bbl_per_ftnumberRequired

      Median fluid, bbl/ft, to 0.1.

    • proppant_lb_per_ftnumberRequired

      Median proppant, lb/ft, to 1.

    • wellsintegerRequired

      ≥ 1

      In-scope wells with both.

  • warningsarray of stringsRequired

    What to check: nothing inside, the area off the dataset, the grids unavailable.

Errors

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean