Keep areas by name
Keep the areas of a zipped shapefile, GeoJSON, KML or KMZ file by name.
Keep areas by name
/area-setsKeep 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.
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_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.
Header parameters
Idempotency-KeystringOptionalpattern ^[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.fieldIdempotency-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: trueand POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans withdry_run: trueneither keeps nor replays its key. - A replay of a plan or export the server has dropped is a 404.
Request body
The file, its name and visibility: uploaded as multipart/form-data, or in a JSON body.
filestringRequiredFile
As in POST /areas; the part's file name is kept with the set.
namestringRequiredThe set's name, 1 to 100 characters.
crsstringOptionalAs in POST /areas.
name_fieldstringOptionalAs in POST /areas.
name_fieldsstringOptionalAs in POST /areas, as JSON text.
name_separatorstringOptionalAs in POST /areas.
visibilitystringOptionalprivate or tenant, as in the JSON body.
namestringRequired1 to 100 characters
The set's name.
shapefilestringOptionalAs in POST /areas: a zipped shapefile in base64.
geojsonobjectOptionalAs in POST /areas: a GeoJSON FeatureCollection, Feature, Polygon or MultiPolygon.
kmlstringOptionalAs in POST /areas: a KML file's text.
kmzstringOptionalAs in POST /areas: a KMZ in base64.
crsstring or integer or nullOptionalAs in POST /areas: the file's coordinate system as an EPSG code.
name_fieldstring or nullOptionalup to 100 characters
As in POST /areas.
name_fieldsarray of strings or nullOptional1 to 5 itemsItems 1 to 100 characters
As in POST /areas.
name_separatorstring or nullOptionalup to 8 characters
As in POST /areas.
visibilitystringOptionalprivate (the default) answers only its signed-in creator; tenant every user of the tenant.
"private""tenant"
Responses
201 Created
The set's record, its areas as read, and its ETag.
idstringRequiredFormat
uuidIts id.
namestringRequiredIts name, 1 to 100 characters.
countintegerRequired≥ 1
Areas in it.
acresnumberRequiredIts areas' acres added up, rounded to 0.01.
bboxarray of numbersRequired4 items
West, south, east and north of its areas' outer rings, WGS 84.
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.
name_fieldstring or nullRequiredThe field the areas' names came from, or null.
fileobject or nullRequiredThe uploaded file; null from a JSON body.
ShowHide 3 child fields
namestring or nullRequiredThe file part's name, or null without one.
bytesintegerRequired≥ 0
Its size.
sha256stringRequiredIts SHA-256, hex.
visibilitystringRequiredprivate: its signed-in creator only; tenant: every user of the tenant.
"private""tenant"created_bystring or nullRequiredIts signed-in creator's email, or null.
created_atstringRequiredFormat
date-timeWhen it was kept.
updated_atstringRequiredFormat
date-timeWhen it last changed.
Show all 17 fields
areasarray of objectsRequiredThe 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.
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 objectsRequiredOn 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.
reasonstringRequiredWhy it isn't an area.
warningsarray of stringsRequiredOn create, POST /areas' warnings; on get, the warning for areas outside the model set's bbox, if any.
name_fieldsarray of stringsOptionalOnly for a set made with name_fields: those fields as the file spells them, in the order sent; name_field is the first.
name_separatorstringOptionalOnly for a set made with name_fields: what joined their values.
Errors
| Status | When |
|---|---|
| 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