Skip to content
Developers
Get an API token

Keep areas by name

Keep the areas of a zipped shapefile, GeoJSON, KML or KMZ file by name.

Keep areas by name

POST/area-sets

Keep the areas of a zipped shapefile, GeoJSON, KML or KMZ file by name. The file is read exactly as POST /areas reads it, against the request's model set; the answer is 201 with the set's record, its areas, skipped records and warnings, and its ETag.

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

private (the default) answers only its signed-in creator, so a request without a signed-in user must send tenant (else 400); tenant answers every user of the tenant.

Retries

An Idempotency-Key replays the first answer under any model set: the set's current record, and its areas, skipped records and warnings as first answered. A replay of a set deleted since is 404.

Details

file keeps the uploaded part's name, bytes and SHA-256 (null from a JSON body). Area sets aren't linked to plans: keep the set ids with a plan, as in its saved views document. A server without a state store answers 409 "Area sets need a state store; this server keeps plans in memory".

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.

Header parameters

  • Idempotency-KeystringOptional

    pattern ^[A-Za-z0-9._:-]{1,128}$

    Makes a retry safe: send your own key (a UUID, or your request id) and the same key on every retry. Without the header, nothing changes.

    The same key and body (compared as JSON, key order ignored) within 24 hours replays what the first request made, with its id, in its current state, with Idempotent-Replayed: true, and starts nothing. A different body is a 409 (details.field Idempotency-Key).

    • Keys are per operation, and only a success records one: retry a 502, 503, 504 or a lost response with the same key.
    • With Redis, POST /saved/{collection}, /forecast-sources and /area-sets keep keys there, as do POST /plans and /exports on a server with a state store: every server task shares them and a restart keeps them. While Redis isn't answering, these answer 503.
      • A retry while the first request is still being made waits up to 30 s for it, then answers 409: retry shortly with the same key.
      • A key the first request hasn't recorded within a minute (its task stopped, or Redis failed as it finished) lapses; a retry then makes the resource again.
    • Otherwise keys live in the server process's memory, the latest 1,000 per operation: a restart (a deploy is one) forgets them, and a retry during the first request waits for it.
    • POST /forecasts with async: true and POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans with dry_run: true neither keeps nor replays its key.
    • A replay of a plan or export the server has dropped is a 404.

Request bodyRequired

The file, its name and visibility: uploaded as multipart/form-data, or in a JSON body.

  • filestringRequired

    File

    As in POST /areas; the part's file name is kept with the set.

  • namestringRequired

    The set's name, 1 to 100 characters.

  • crsstringOptional

  • name_fieldstringOptional

  • name_fieldsstringOptional

    As in POST /areas, as JSON text.

  • name_separatorstringOptional

  • visibilitystringOptional

    private or tenant, as in the JSON body.

Responses

201 Created

The set's record, its areas as read, and its ETag.

  • 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

The Idempotency-Key was already used with another request; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key. A server without a state store answers 409 "Area sets need a state store; this server keeps plans in memory".

413

The request body is over 10 MB.

503

A model worker or the subsurface grids aren't ready, or, with Redis, the Redis that keeps Idempotency-Key records isn't answering; retry shortly with the same key.

Shared errors400401403500What they mean