Skip to content
Developers
Get an API token

Get an area set

An area set's record and its areas, each as POST /areas gave it, and the set's ETag.

Get an area set

GET/area-sets/{id}

An area set's record and its areas, each as POST /areas gave it, and the set's ETag.

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

in_dataset, and POST /areas' warning when an area lies outside, are worked out against this request's model set (GET /dataset bbox); skipped is empty.

Errors

A private set answers only its signed-in creator; another user's private set, a deleted one, another tenant's or an unknown id is 404. A server without a state store answers 409 "Area sets need a state store; this server keeps plans in memory".

Parameters

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

Responses

200 OK

The area set.

  • idstringRequired

    Format uuid

    Its id.

  • namestringRequired

    Its name, 1 to 100 characters.

  • countintegerRequired

    ≥ 1

    Areas in it.

  • acresnumberRequired

    Its areas' acres added up, rounded to 0.01.

  • bboxarray of numbersRequired

    4 items

    West, south, east and north of its areas' outer rings, WGS 84.

  • crsobjectRequired

    The coordinate system the file was read in, and how sure that is.

    ShowHide 6 child fields
    • codestringRequired

      The system read: an EPSG code, as EPSG:2277, or the .prj's name when no supported system matches it (it was read through the .prj itself).

    • namestringRequired

      Its name, as NAD83 / Texas Central (ftUS).

    • sourcestringRequired

      request: the request's crs; file: the .prj, the GeoJSON (crs member, or degrees per RFC 7946) or a KML (WGS 84); detected: the first supported system that puts the areas on the dataset.

      "request""file""detected"
    • datum_shiftstring or nullRequired

      nadcon_conus: NAD27, shifted to NAD83 with NOAA's NADCON conus grid; else null.

      "nadcon_conus"
    • max_offset_ftintegerRequired

      ≥ 0

      The largest alternative's offset_ft, or 0: how far the areas could be off if the file is in another system that also fits.

    • alternativesarray of objectsRequired

      With detection: the other systems that fit, in preference order, under 1 ft apart listed once.

      ShowHide 3 child fields in each item
      • codestring or nullRequired

        Its EPSG code; null for an international-foot variant, which crs can't name.

      • namestringRequired

        Its name.

      • offset_ftintegerRequired

        ≥ 1

        The farthest a sampled vertex lands from where it is read now, ft.

  • name_fieldstring or nullRequired

    The field the areas' names came from, or null.

  • fileobject or nullRequired

    The uploaded file; null from a JSON body.

    ShowHide 3 child fields
    • namestring or nullRequired

      The file part's name, or null without one.

    • bytesintegerRequired

      ≥ 0

      Its size.

    • sha256stringRequired

      Its SHA-256, hex.

  • visibilitystringRequired

    private: its signed-in creator only; tenant: every user of the tenant.

    "private""tenant"
  • created_bystring or nullRequired

    Its signed-in creator's email, or null.

  • created_atstringRequired

    Format date-time

    When it was kept.

  • updated_atstringRequired

    Format date-time

    When it last changed.

Show all 17 fields
  • areasarray of objectsRequired

    The areas, in file order; in_dataset against the request's model set.

    ShowHide 11 child fields in each item
    • idintegerRequired

      ≥ 0

      Its record (shapefile) or feature (GeoJSON) index in the file, from 0.

    • namestringRequired

      From the name field or fields, else Area <id + 1>.

    • propertiesobjectRequired

      The file's attributes: numbers, text (cut at 200 characters), booleans, dates (YYYY-MM-DD) and nulls, at most 50, plus the asked name fields.

    • geometryobjectRequired

      The area in WGS 84 (RFC 7946): rings closed (the last point repeats the first), outer rings counterclockwise and holes clockwise, coordinates at 1e-7°.

      ShowHide 2 variants

      One of

      • A polygon object

        A polygon.

        • typeanyRequired

          Always "Polygon"

          One part.

        • coordinatesarray of arraysRequired

          Items at least 4 items

          The outer ring, then its holes.

      • A multipolygon object

        A multipolygon.

        • typeanyRequired

          Always "MultiPolygon"

          Several parts.

        • coordinatesarray of arraysRequired

          The parts.

    • 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: an azimuth_deg for POST /layouts/fill.

    • partsintegerRequired

      ≥ 1

      Parts (outer rings).

    • holesintegerRequired

      ≥ 0

      Holes in all parts.

    • verticesintegerRequired

      ≥ 3

      Corners in all rings, closing points not counted.

    • in_datasetbooleanRequired

      True when the area's bbox meets the dataset's (GET /dataset bbox); a warning counts the areas where it is false.

    • fillobject or nullRequired

      The ring to fill with wells, or null when the simplified ring's edges cross, or it has fewer than 3 corners or no area.

      ShowHide 5 child fields
      • polygonarray of [number, number]sRequired

        3 to 500 items

        The largest part's outer ring, open (no closing point), at most 500 corners: send it as polygon to POST /layouts/fill, or in a layout. A layout from it alone ignores the area's other parts and its holes; to fill every part and leave the holes out, send the area's geometry as area instead.

      • simplified_frominteger or nullRequired

        The ring's corners before simplifying, or null when it was not simplified.

      • max_deviation_ftnumberRequired

        ≥ 0

        The farthest a corner dropped in simplifying lies from the edge that replaced it, ft; 0 when none was.

      • dropped_partsintegerRequired

        ≥ 0

        Parts of the area the ring leaves out.

      • dropped_holesintegerRequired

        ≥ 0

        Holes in its part the ring leaves out.

  • skippedarray of objectsRequired

    On create, the records POST /areas leaves out; on get, empty.

    ShowHide 2 child fields in each item
    • indexintegerRequired

      ≥ 0

      Record or feature index in the file.

    • reasonstringRequired

      Why it isn't an area.

  • warningsarray of stringsRequired

    On create, POST /areas' warnings; on get, the warning for areas outside the model set's bbox, if any.

  • name_fieldsarray of stringsOptional

    Only for a set made with name_fields: those fields as the file spells them, in the order sent; name_field is the first.

  • name_separatorstringOptional

    Only for a set made with name_fields: what joined their values.

Errors

StatusWhen
404

No such well, grid, plan or route.

409

A server without a state store answers 409 "Area sets need a state store; this server keeps plans in memory".

Shared errors400401403500503What they mean