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
/area-sets/{id}An area set's record and its areas, each as POST /areas gave it, and the set's ETag.
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
idstringRequiredFormat
uuidArea set id from POST /area-sets or GET /area-sets.
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.
Responses
200 OK
The area set.
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 | A server without a state store answers 409 "Area sets need a state store; this server keeps plans in memory". |
Shared errors400401403500503What they mean