Skip to content
Developers
Get an API token

Fill many areas with wells

Lays wells of one lateral length over many areas in one call, laying areas that touch as one piece of land.

Fill many areas with wells

POST/areas/fill

Lays wells of one lateral length over many areas in one call, laying areas that touch as one piece of land. Nothing is stored: send the wells to POST /plans, each with a formation, to forecast them.

Send a Novi API token as a bearer token on every request. Authentication
Areas

Send areas, lateral_length_ft, and spacing_ft or benches. azimuth_deg, setback_ft, setback_end_ft, wells_per_pad and formation work as in POST /layouts/fill.

Pieces of land

The areas not skipped are grouped part by part, and each group is laid on one grid. Two parts join when their edges run opposite ways within 1 ft of each other along an unbroken 100 ft, however each side's corners fall, or when they overlap. A shared corner, or points touching here and there, don't join. A MultiPolygon's parts may fall in different groups.

  • Two parts overlap when an edge of one crosses an edge of the other, their edges run the same way along such a stretch, or a corner of one lies inside the other (when every corner lies on the other's edges, an edge's midpoint).
  • In a group, a well runs across the lines between areas but never through a hole or outside the group, and land two areas cover is laid once.
  • setback_ft and setback_end_ft hold from the group's outer edges and holes only, not from edges its parts share. An edge inside an overlap isn't shared, so it still holds them.
Length

Along each line, an unbroken stretch of L ft, less its setbacks, holds k = floor(L / lateral_length_ft) wells of lateral_length_ft, toe to heel and centred, and none when k is 0. When the land left, L less k lengths, is at least min_lateral_ft, it takes k + 1 wells of L / (k + 1) instead. An L within a millionth of a foot of a whole number of lengths takes that many full wells.

  • With 2-mile laterals and no setbacks, three one-mile sections take one 2-mile well, centred; two 5,200 ft sections one of 10,400 ft; four, two of 10,400 ft.
  • With one-mile laterals and the default min_lateral_ft, a one-mile section less 330 ft end setbacks still takes one well, of 4,620 ft.
  • A well that measures over lateral_length_ft is shortened about its middle.
  • Lengths and setbacks are laid on a flat grid about the group's first corner, so far from it a well can measure a little short and pass a little closer to an edge: about 30 miles from it at about 32° N, a 5,280 ft well measured 24 ft short and a 330 ft setback 328.95 ft.
Azimuth

azimuth_deg sets every group's. Without it, each group runs along its largest part's longest outer edge or square to it, whichever way the group's outer corners span more feet; within 1 ft, along the edge. groups[].azimuth_deg gives each.

Order

Groups come in the order of their first part (areas in request order, then parts). Wells come group by group, then bench by bench, then line by line across the azimuth, heel to toe; pads number on across groups. Side gaps aren't evened out. The same request always answers the same bytes.

Skipped areas

Each is listed once in skipped, in request order, and counted in areas.skipped:

  • outside_dataset: its box misses GET /dataset bbox, as POST /areas' in_dataset: false says.
  • degenerate: a ring POST /layouts/fill's area would refuse: under 3 corners, a corner that isn't [lng, lat], no area, or a hole that isn't inside its outline.
  • too_small: its group lays no well, or no well runs through it.
  • over_limit: its group would pass the well limit or the fill work, or its holes need more checking than the request has left to show they lie inside their outlines.
Limits
  • At most 5,000 areas, 200,000 vertices in all, and max_wells wells: the lesser of GET /dataset limits.plan_wells and 10,000.
  • At most 35,000,000 of fill work. Per bench, each line a group lays costs its ring edges plus its setback edges (twice with setback_end_ft), plus 16 for each of those whose setback reaches the line; each part a laid well runs through costs 25.
  • Groups are laid in order with what is left, and a group past a limit is skipped whole while later groups still run. One whose lines times edges pass the work left counts no work; one that passes either limit while it is laid counts the work it did.
Errors

A body over 10 MB is a 413. Other errors are 400 with details.field:

  • a missing or out-of-range number;
  • spacing_ft with benches, or neither;
  • areas empty, over 5,000 entries, or over 200,000 vertices in all (details.max and details.count);
  • an area that isn't a Polygon or MultiPolygon;
  • a repeated id ("areas[i].id repeats areas[j].id");
  • areas too complex to group within one request's work (details.max_work).

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 areas, the lateral length and the layout.

Send exactly one of: spacing_ft or benches.

  • areasarray of objectsRequired

    1 to 5000 items

    The areas: at most 200,000 vertices in all.

    ShowHide 2 child fields in each item
    • areaobjectRequired

      The area as a GeoJSON Polygon or MultiPolygon in WGS 84 with only type and coordinates: an area's geometry from POST /areas, or your own. A ring POST /layouts/fill's area would refuse skips the area as degenerate.

      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.

    • idinteger or nullOptional

      ≥ 0, ≤ 2147483647

      Echoed in the answer; each once. Absent or null, the entry's index.

  • lateral_length_ftnumberRequired

    ≥ 1000, ≤ 30000

    The length each well aims for, ft (5,280 is a mile). Required.

  • min_lateral_ftnumber or nullOptional

    ≥ 1000, ≤ 30000

    The shortest well, ft, at most lateral_length_ft: a stretch takes as many wells of lateral_length_ft as fit, centred, or one more, all equal, when the land they leave is at least this long. Absent or null, 85% of lateral_length_ft to the foot, at least 1,000.

  • azimuth_degnumber or nullOptional

    ≥ -360, ≤ 360

    Every group's direction, degrees clockwise from north (wells drilled toward it). Absent or null, each group's long axis.

  • spacing_ftnumberOptional

    ≥ 100, ≤ 10000

    Distance between wells, ft.

  • benchesarray of objectsOptional

    1 to 10 items

    Instead of spacing_ft: benches filled together, each with its own spacing, offset and formation.

    ShowHide 4 child fields in each item

    Send exactly one of: spacing_ft or wells_per_section.

    • spacing_ftnumberOptional

      ≥ 100, ≤ 10000

      Distance between the bench's wells, ft. Not with wells_per_section.

    • wells_per_sectionnumberOptional

      ≥ 0.528, ≤ 52.8

      Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).

    • offset_ftnumber or nullOptional

      Default 0≥ -10000, ≤ 10000

      Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.

      Lines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.

    • formationstring or nullOptional

      The bench's formation (case-insensitive; GET /formations lists them): its wells carry it. Default the request's formation.

  • setback_ftnumber or nullOptional

    ≥ 0, ≤ 2640

    Feet the wells keep from each group's outer edges and holes, not from the lines between its areas, as POST /layouts/fill keeps them from an area's.

  • setback_end_ftnumber or nullOptional

    ≥ 0, ≤ 2640

    Feet each well's heel and toe keep from each group's outer edges and holes, as POST /layouts/fill keeps them from an area's.

  • wells_per_padinteger or nullOptional

    ≥ 1, ≤ 50

    Groups each group's wells into pads of this many, as POST /layouts/fill does; pads number on across groups, so each is unique in the answer.

  • formationstring or nullOptional

    The wells' formation (case-insensitive; GET /formations lists them), which each well then carries.

Responses

200 OK

The wells, group by group, and what was skipped.

  • countintegerRequired

    ≥ 0

    Wells.

  • lateral_length_ftnumberRequired

    Length used, ft.

  • min_lateral_ftnumberRequired

    Shortest well used, ft: as sent, or the default.

  • azimuth_degnumber or nullRequired

    The request's azimuth_deg, or null when each group ran along its own (groups[].azimuth_deg).

  • joinobjectRequired

    The distances that join parts into one piece of land.

    ShowHide 2 child fields
    • within_ftnumberRequired

      Edges and stretches this close count as touching, ft.

    • min_shared_ftnumberRequired

      The least shared stretch that joins two parts, ft.

  • max_wellsintegerRequired

    ≥ 1

    The most wells the answer holds: the lesser of GET /dataset limits.plan_wells and 10,000.

  • areasobjectRequired

    What became of the areas: sent is used plus the skipped counts.

    ShowHide 3 child fields
    • sentintegerRequired

      ≥ 1

      Areas sent.

    • usedintegerRequired

      ≥ 0

      Areas some well runs through.

    • skippedobjectRequired

      Skipped areas by reason.

      ShowHide 4 child fields
      • outside_datasetintegerRequired

        ≥ 0

        Areas skipped as outside_dataset.

      • degenerateintegerRequired

        ≥ 0

        Areas skipped as degenerate.

      • too_smallintegerRequired

        ≥ 0

        Areas skipped as too_small.

      • over_limitintegerRequired

        ≥ 0

        Areas skipped as over_limit.

  • groupsarray of objectsRequired

    The groups that laid wells, in order; wells[].group indexes it.

    ShowHide 4 child fields in each item
    • areasarray of integersRequired

      Items ≥ 0

      The group's areas' ids, in request order; a MultiPolygon whose parts fall in several groups is in each.

    • azimuth_degnumberRequired

      The group's azimuth, degrees: the request's azimuth_deg as sent, else measured on the group's flat grid to 0.001. Sent back as azimuth_deg, it lays the same wells.

    • firstintegerRequired

      ≥ 0

      Its first well's index in wells.

    • countintegerRequired

      ≥ 1

      Its wells.

  • skippedarray of objectsRequired

    Each skipped area once, in request order.

    ShowHide 3 child fields in each item
    • idintegerRequired

      ≥ 0

      The area's id.

    • reasonstringRequired

      outside_dataset: its box misses the dataset's; degenerate: a ring a fill refuses; too_small: no well runs through it; over_limit: its group would pass the well limit or the fill work, or its holes need more checking than one request has left.

      "outside_dataset""degenerate""too_small""over_limit"
    • detailstringOptional

      degenerate: the fault; over_limit: the limit.

  • wellsarray of objectsRequired

    Wells, group by group, then bench by bench.

    ShowHide 8 child fields in each item
    • shl[number, number]Required

      A point as [longitude, latitude] in WGS 84 degrees.

    • bhl[number, number]Required

      A point as [longitude, latitude] in WGS 84 degrees.

    • lateral_length_ftintegerRequired

      Lateral length, ft.

    • groupintegerRequired

      ≥ 0

      Its group's index in groups.

    • areasarray of integersRequired

      Items ≥ 0

      The areas it runs through, heel to toe.

    • formationstringOptional

      Its bench's formation, else the request's; only when one is known.

    • benchintegerOptional

      ≥ 0

      With benches: its bench's index.

    • padintegerOptional

      ≥ 0

      With wells_per_pad: its pad, from 0, unique across groups.

  • spacing_ftnumberOptional

    Spacing used; left out with benches.

  • setback_ftnumberOptional

    Setback used, ft; only when sent.

Show all 18 fields
  • setback_end_ftnumberOptional

    End setback used, ft; only when sent.

  • wells_per_padintegerOptional

    Wells per pad; only when sent.

  • padsintegerOptional

    ≥ 0

    With wells_per_pad: the pads, across groups.

  • wells_per_sectionnumberOptional

    With benches: their wells_per_section added up.

  • benchesarray of objectsOptional

    With benches: each bench as filled.

    ShowHide 5 child fields in each item
    • spacing_ftnumberRequired

      Spacing used, ft.

    • wells_per_sectionnumberRequired

      5,280 ft / spacing_ft, or as sent.

    • offset_ftnumberRequired

      Offset used, ft.

    • formationstring or nullRequired

      The bench's formation, or null when none was sent.

    • countintegerRequired

      ≥ 0

      Wells in the bench.

  • formationstringOptional

    The request's formation, as GET /formations names it; only when sent.

Errors

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean