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
/areasPolygons 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.
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 ; 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.maxanddetails.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_setstringOptionalpattern ^[a-z0-9][a-z0-9-]{0,62}$
The model set to answer from, an
idfrom GET /model-sets. Absent: the set GET /model-sets names asdefault, the base dataset unless the server answers from a published set.model_set=defaultreaches 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 oncedefaultis 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'splan.id, or a comparison'sa.planandb.plan, also undersource.comparison) reaches it withoutmodel_set. - An explicit
model_setwins; naming resources of two sets in one request is a 400.
Request body
The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.
filestringRequiredFile
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.
crsstringOptionalAs crs in the JSON body: an EPSG code, as EPSG:2277 or 2277.
name_fieldstringOptionalAs name_field in the JSON body.
name_fieldsstringOptionalAs name_fields in the JSON body, as JSON text: ["name", "lease_no"].
name_separatorstringOptionalAs name_separator in the JSON body: the part's text as sent.
shapefilestringOptionalA zipped shapefile (.shp, .dbf and .prj; .cpg and .shx optional) in base64: RFC 4648, padded, with no line breaks or data: prefix. Where you can, upload the file itself as multipart/form-data instead.
geojsonobjectOptionalA GeoJSON FeatureCollection, Feature, Polygon or MultiPolygon. Coordinates in degrees are WGS 84 (RFC 7946); others need a crs member or crs, or are detected.
kmlstringOptionalA KML file's text (OGC KML 2.2, UTF-8): Placemark polygons in WGS 84.
kmzstringOptionalA KMZ (a zip holding a .kml) in base64: RFC 4648, padded, with no line breaks or data: prefix. Where you can, upload the file itself as multipart/form-data instead.
crsstring or integer or nullOptionalThe file's coordinate system as an EPSG code (EPSG:2277, epsg:2277 or 2277), overriding the file's own and detection.
One of EPSG:2275, EPSG:2276, EPSG:2277, EPSG:2278, EPSG:2279, EPSG:2257, EPSG:2258, EPSG:2259, EPSG:32137, EPSG:32138, EPSG:32139, EPSG:32140, EPSG:32141, EPSG:32112, EPSG:32113, EPSG:32114, EPSG:6578, EPSG:6588, EPSG:3081, EPSG:3082, EPSG:3083, EPSG:5070, EPSG:3857, EPSG:26913, EPSG:26914, EPSG:32613, EPSG:32614, EPSG:4326, EPSG:4269, EPSG:32037, EPSG:32038, EPSG:32039, EPSG:32040, EPSG:32041, EPSG:32012, EPSG:32013, EPSG:32014, EPSG:26713, EPSG:26714, EPSG:4267.
name_fieldstring or nullOptionalup to 100 characters
The field (any case) whose value names each area, read even past the property caps; 400 with details.fields when the file has no such field. Blank picks one.
name_fieldsarray of strings or nullOptional1 to 5 itemsItems 1 to 100 characters
Fields (any case) whose values, in this order with blanks left out, name each area, joined by name_separator; each read even past the property caps. 400 on name_fields[i] for a field the file lacks (with details.fields) or one that repeats an earlier field; 400 on name_fields with name_field.
name_separatorstring or nullOptionalup to 8 characters
What joins the name_fields values, used as sent: 0 to 8 characters, one space when absent; only with name_fields.
Responses
200 OK
The areas, in file order.
countintegerRequired≥ 1
Areas read.
name_fieldstring or nullRequiredThe field the names came from, or null.
fieldsarray of stringsRequiredThe attributes the areas carry, in file order.
crsobjectRequiredThe coordinate system the file was read in, and how sure that is.
ShowHide 6 child fields
codestringRequiredThe 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).
namestringRequiredIts name, as NAD83 / Texas Central (ftUS).
sourcestringRequiredrequest: 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 nullRequirednadcon_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 objectsRequiredWith detection: the other systems that fit, in preference order, under 1 ft apart listed once.
ShowHide 3 child fields in each item
codestring or nullRequiredIts EPSG code; null for an international-foot variant, which crs can't name.
namestringRequiredIts name.
offset_ftintegerRequired≥ 1
The farthest a sampled vertex lands from where it is read now, ft.
areasarray of objectsRequiredThe 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.
namestringRequiredFrom the name field or fields, else Area <id + 1>.
propertiesobjectRequiredThe file's attributes: numbers, text (cut at 200 characters), booleans, dates (YYYY-MM-DD) and nulls, at most 50, plus the asked name fields.
geometryobjectRequiredThe 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.
typeanyRequiredAlways
"Polygon"One part.
coordinatesarray of arraysRequiredItems at least 4 items
The outer ring, then its holes.
A multipolygon object
A multipolygon.
typeanyRequiredAlways
"MultiPolygon"Several parts.
coordinatesarray of arraysRequiredThe parts.
acresnumberRequiredArea, 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_datasetbooleanRequiredTrue when the area's bbox meets the dataset's (GET /dataset bbox); a warning counts the areas where it is false.
fillobject or nullRequiredThe 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]sRequired3 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 nullRequiredThe 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 objectsRequiredRecords 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.
reasonstringRequiredWhy it isn't an area: a null shape, deleted in the .dbf, not a polygon, no ring with area, off the globe.
warningsarray of stringsRequiredWhat 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 stringsOptionalOnly when the request sent name_fields: those fields as the file spells them, in the order sent; name_field is the first.
name_separatorstringOptionalOnly when the request sent name_fields: what joined their values.
Errors
| Status | When |
|---|---|
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean