-
Notifications
You must be signed in to change notification settings - Fork 9
Backend API
The REST calls of the Planscape Django backend are documented here.
The APIs will use the following canonical region names:
| Internal name | Display name |
|---|---|
| sierra_cascade_inyo | Sierra Nevada |
| coastal_inland | Central Coast |
| southern_california | Southern California |
| north_coast_inland | Northern California |
The spelling and capitalization are important.
Boundary endpoints fetch data or metadata about fixed, known boundaries, e.g., county or watershed boundaries. The APIs return either JSON or GeoJSON objects.
Returns a JSON object with the names of all fixed boundaries stored in the Planscape database, except the 'task_force_regions' boundaries.
GET /planscape-backend/boundary/boundary/
returns an JSON object of the form
[{"id":14,"boundary\_name":"huc12"},
{"id":15,"boundary\_name":"huc10"}]
Fetches the geometry of a particular boundary as a GeoJSON object. If the "region_name" argument is given, it clips the boundaries to the region.
GET /planscape-backend/boundary/boundary_details/?boundary_name=huc12
returns an object of the form
{ "type":"FeatureCollection",
"features": [
{ "id":1529,
"type":"Feature",
"geometry": {
"type":"MultiPolygon",
"coordinates": [
[[[-119.99432866209,38.7097488371435],
...
]
}
}
]
}
GET /planscape-backend/boundary/boundary_details/?boundary_name=huc12®ion_name=sierra_cascade_inyo
returns an object of the same form, where the polygons are clipped to the region. The possible regions are listed above.
Condition endpoints fetch data or metadata about condition data layers.
Returns a JSON object with all of the conditions, structured into metrics, elements, pillars. This is the same configuration used in the backend.
GET planscape-backend/conditions/conditions/?region_name=sierra_cascade_inyo
returns a JSON object of the form
{ "region_name": "sierra_cascade_inyo",
"display_name": "Sierra Nevada",
"pillars": [
{ "pillar_name": "forest_resilience",
"display_name": "Forest Resilience",
"elements": [
{ "element_name": "forest_structure",
"display_name": "Forest Structure",
"metrics": [
{ "metric_name": "structure_departure", ... },
{ "metric_name": "structural_heterogeneity",
"current_conditions_only": true
},
{ "metric\_name": "large_tree_density" }
]
},
...
]
}
]
}
Returns a JSON object for a colormap definition by name.
GET /planscape-backend/conditions/colormap/?colormap=inferno
returns
{ "inferno": [
{"name": "excellent", "percentile": 100, "rgb": "#000004"},
{"name": "good", "percentile": 75, "rgb": "#57106e"},
{"name": "ok", "percentile": 50, "rgb": "#bc3754"},
{"name": "fair", "percentile": 25, "rgb": "#f98e09"},
{"name": "poor", "percentile": 0, "rgb": "#fcffa4"}
]
}
The Plan APIs support the planning journey, giving the frontend the ability to create plans, fetch plans by name or ID, modify geometry, share and lock plans, create projects, etc.
Creates and stores a plan in the Planscape database from a name, region name, and geoemtry. The plan is associated with the logged-in user, if logged in, or the "guest" user (null in the database) if the user is not logged in. Returns the ID of the created plan.
POST /plan/create {"name": "HH", "region_name": "Sierra Nevada", "geometry": ... }
returns the ID of the created plan.
Deletes one or more plans by ID. Only the plans owned by the logged-in user may be deleted. If the user is not logged in, only the plans owned by the "guest" user may be deleted.
POST /plan/delete/?id=1,2
returns the IDs of the deleted plans.
Given a plan ID, returns a JSON object with the top-level information about the plan. Return an error if the plan does not exist.
GET /plan/get_plan/?id=1
returns a JSON object of the form
{ "id": 1,
"owner": 2,
"name": "plan",
"region_name": "Sierra Nevada",
"public": false,
"locked": false,
"geometry": {
"features": [
{ "geometry": {
"type": "Polygon",
"coordinates": [[[1, 2], [2, 3], [3, 4], [1, 2]]]
}
}
]
}
}
Lists plans by owner, returning a JSON list. If the "owner" argument is not present and the user is logged in, the user is assumed to be the owner; otherwise, the plans for the "guest" user are returned.
GET /plan/list_plans_by_owner/?owner=2
returns a JSON object of the form
[ {"id": 1, "owner": 2, "name": "plan1", ...},
{"id": 2, "owner": 3, "name": "plan2", ...},
]
Creates a project within a plan, setting various parameters about the project. The project is owned by the user creating the project, which is either the logged-in user or the "guest" user. Returns the ID of the created project, or an error if either the plan does not exist, one of the priority names does not match a condition, or the condition_score_type is invalid.
POST /plan/create_project {
"plan_id": 1,
"max_cost": 100,
"priorites"="priority1, priority2",
"condition_score_type": 1
}
returns the ID of the created project.
Updates an existing project's parameters. Only the PUT interface is supported. Other request types will return an error.
Returns the ID of the updated project, or an error if the project does not exist, the constraints are incorrectly formatted, or priorities do not exist.
PUT /plan/update_project {
"id": 1,
"max_cost": 100,
"priorites"="priority1, priority2",
"condition_score_type": 1
}
returns the ID of the updated project.
Delete existing projects by ID.
Returns the ID of the deleted projects, or an error if the user does not own all of the projects.
POST /plan/delete_projects {
"project_ids": [1, 2]
}
returns the IDs of the deleted projects.
Creates a project area within a project. The project area is owned by the user creating the project, which is either the logged-in user or the "guest" user. Returns the ID of the created project area.
POST /plan/create_project_area {
"project_id": 1,
"geometry": {
"features": [{
"geometry": {
"type': 'Polygon', 'coordinates': [[[1, 2], [2, 3], [3, 4], [1, 2]]]
}
}]
}
}
returns the ID of the created project area.
Returns a JSON list containing the project areas within a project, or the empty list if the project has no project areas. Returns an error if the project is not owned by the user (i.e., the logged-in user or the "guest" user if not logged in), or the project does not exist.
GET /plan/get_project_areas/?project_id=1
returns the list of project areas within project 1.
Returns a JSON object containing computed mean scores for all known conditions in a plan's planning areas. If a mean value cannot be computed, no value is returned for that condition. Returns an error if the plan is not owned by the user, a planning area does not exist, or no conditions exist in the area.
GET /plan/get_scores/?id=1
returns a JSON object of the form
{'conditions':
[
{'condition': 'foo', 'mean_score': 5.0},
{'condition': 'bar'}
]
}