Skip to content
Developers
Get an API token

Read areas from a shapefile, GeoJSON, KML or KMZ

Polygons from a zipped shapefile, a GeoJSON file, or a Google Earth KML or KMZ as named WGS 84 areas, each with its acres, long axis and a ring ready to fill.

Read areas from a shapefile, GeoJSON, KML or KMZ

POST/areas

Polygons from a zipped shapefile, a GeoJSON file, or a Google Earth KML or KMZ as named WGS 84 areas, each with its acres, long axis and a ring ready to fill. Nothing is stored: send the file again to read it again.

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

Send the file as multipart/form-data, as curl -F file=@units.zip -F crs=EPSG:2277 <origin>/api/v1/areas. JSON-only clients, such as MCP tools, send shapefile or kmz (base64), geojson or kml in a JSON body; the answer is the same.

Shapefiles

The zip's first polygon layer is read (a warning names the others). Polygon, PolygonZ and PolygonM shapes are read in 2D: clockwise rings are outer rings and counterclockwise ones holes, each in the smallest outer ring holding it (a hole in none is read as an outer ring, with a warning). The .dbf's attributes become properties, decoded as the .cpg says, else UTF-8 when valid, else Windows-1252. Null shapes and records the .dbf marks deleted (ArcGIS hides them) are in skipped; other areas keep their record index as id.

GeoJSON

A FeatureCollection, Feature, Polygon or MultiPolygon; other geometries are in skipped.

KML and KMZ

Every Placemark at any depth is a record, numbered from 0, whose Polygons, directly or in a MultiGeometry, are its parts. Coordinates are lon,lat[,alt] tuples of at most 64 characters, altitude dropped; a Placemark with any other is in skipped, as are other geometries, and a MultiGeometry's other members are left out with a warning. Properties are name, description, and ExtendedData by name. A KMZ's KML is its root doc.kml (any case), else its first .kml, with a warning naming any others. Network links aren't fetched.

A DTD is a 400. An entity XML doesn't define (HTML's &nbsp;; any XML name of up to 40 characters) is kept as written, with a warning; in an element the reader uses, a bare & or any other text between & and ; is a 400.

Holes

A hole lies inside the ring it is cut from. One wholly outside it is read as an outer ring, a part of its own; one that crosses it or is as large is left out; each with a warning, and acres, parts and holes describe the area as read. Holes are checked in file order up to a fixed amount of checking per request; past it, that hole and every later one are taken as the file gives them.

Coordinate systems

The request's crs; else the file's own (its .prj or GeoJSON crs member; WGS 84 for GeoJSON in degrees and for KML); else the first supported system that puts up to 256 sampled vertices all within 0.5° of the dataset's bbox, in preference order: NAD83 state plane in US survey feet, then metres, NAD83(2011), the Texas-wide systems, CONUS Albers, Web Mercator, UTM, degrees, NAD27 last. When none does, degrees are read as WGS 84 with a warning, and other numbers are a 400 on crs.

crs.alternatives lists the other systems that fit, each with offset_ft, the farthest a vertex would move in it (international-foot variants have code: null); max_offset_ft is the largest, and a warning says the areas are only that sure. When it matters, send crs. A .prj that puts the areas off the dataset is still used, with a warning naming a system that fits. NAD27 is shifted to NAD83 with NOAA's NADCON conus grid, within about 0.2 m of NOAA's NCAT at Permian points; NAD83, NAD83(2011) and WGS 84 are taken as the same, within about 2 m.

Names

From name_field, else the first of name, unit_name, unitname, lease_name, leasename, padname, pad_name, dsu, unit, lease that 90% of areas fill, else the first text field whose name is at most 100 characters and whose values all differ, else Area <id + 1>. name_fields joins several fields' values instead, cut at 200 characters; names need not differ, and an area whose fields are all blank is Area <id + 1>. Send name_field or name_fields, not both.

Measures

acres and long_axis_azimuth_deg (as the Pad Optimizer takes it) are measured in flat-earth feet about each part.

Fill

fill.polygon is the largest part's outer ring, at most 500 corners, ready for POST /layouts/fill or a layout. To fill every part with the holes left out, send the area's geometry as area there instead.

Limits
  • The 10 MB request body.
  • 5,000 areas, 200,000 vertices and 20,000 rings, each a 400 with details.max and details.count.
  • 50 properties an area and 500 property names a file, later ones left out with a warning (the asked name fields are always read).
  • A zip of 64 entries (a KMZ 1,000, its KML at most 10 MB unzipped), stored or deflated, each at most 32 MB and 64 MB in all, not encrypted or ZIP64.
  • A .prj of at most 16 KB; a .cpg over 16 KB is ignored.
  • About a second of reading and geometry work, past which the file is a 400 as too complex, with details.max_work. The same file always gets the same answer.
Errors

400 with details.field naming the input: the file's field, crs (with details.supported), name_field or name_fields[i] (with details.fields for a field the file lacks), name_fields, name_separator, body (not JSON or valid multipart) or an unknown multipart part's name. A body over 10 MB is a 413.

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

The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.

  • filestringRequired

    File

    The zipped shapefile (.zip), GeoJSON, KML or KMZ file, as a file part; GeoJSON may also come as a text part (curl -F file=<units.geojson). A zip is told by its first bytes (PK\x03\x04); one holding a .kml and no .shp is a KMZ. A first character < after a BOM and whitespace is KML.

  • crsstringOptional

    As crs in the JSON body: an EPSG code, as EPSG:2277 or 2277.

  • name_fieldstringOptional

    As name_field in the JSON body.

  • name_fieldsstringOptional

    As name_fields in the JSON body, as JSON text: ["name", "lease_no"].

  • name_separatorstringOptional

    As name_separator in the JSON body: the part's text as sent.

Responses

200 OK

The areas, in file order.

  • countintegerRequired

    ≥ 1

    Areas read.

  • name_fieldstring or nullRequired

    The field the names came from, or null.

  • fieldsarray of stringsRequired

    The attributes the areas carry, in file order.

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

  • areasarray of objectsRequired

    The areas, in file order.

    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

    Records left out, in file order: the first 100, with a warning counting any more.

    ShowHide 2 child fields in each item
    • indexintegerRequired

      ≥ 0

      Record or feature index in the file.

    • reasonstringRequired

      Why it isn't an area: a null shape, deleted in the .dbf, not a polygon, no ring with area, off the globe.

  • warningsarray of stringsRequired

    What to check: other layers, the coordinate system's doubt, simplified fill rings, areas with holes or several parts, areas off the dataset.

  • name_fieldsarray of stringsOptional

    Only when the request sent name_fields: those fields as the file spells them, in the order sent; name_field is the first.

  • name_separatorstringOptional

    Only when the request sent name_fields: what joined their values.

Errors

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean