Introduction

The REST calls of the Planscape Django backend are documented here.

Common Names

Regions

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

Boundary endpoints fetch data or metadata about fixed, known boundaries, e.g., county or watershed boundaries. The APIs return either JSON or GeoJSON objects.

/planscape-backend/boundary/boundary

Description

Returns a JSON object with the names of all fixed boundaries stored in the Planscape database, except the 'task_force_regions' boundaries.

Usage

GET /planscape-backend/boundary/boundary/

returns an JSON object of the form

[{"id":14,"boundary\_name":"huc12"},
 {"id":15,"boundary\_name":"huc10"}]

/planscape-backend/boundary/boundary_details

Description

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.

Usage

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&region_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

Condition endpoints fetch data or metadata about condition data layers.

/planscape-backend/conditions/conditions

Description

Returns a JSON object with all of the conditions, structured into metrics, elements, pillars. This is the same configuration used in the backend.

Usage

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" }
          ]
        },
        ...
      ]
    }
  ]
}

/planscape-backend/conditions/colormap

Description

Returns a JSON object for a colormap definition by name.

Usage

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"}
  ]
}

Plan

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.

/planscape-backend/plan/create

Description

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.

Usage

POST /plan/create {"name": "HH", "region_name": "Sierra Nevada", "geometry": ... }

returns the ID of the created plan.

/planscape-backend/plan/delete

Description

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.

Usage

POST /plan/delete/?id=1,2

returns the IDs of the deleted plans.

/planscape-backend/plan/get_plan

Description

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.

Usage

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](/OurPlanscape/Planscape/wiki/[1,-2],-[2,-3],-[3,-4],-[1,-2)]
        }
      }
    ]
  }
}

/planscape-backend/plan/list_plans_by_owner

Description

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.

Usage

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", ...},  
]

/planscape-backend/plan/create_project

Description

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.

Usage

POST /plan/create_project { 
  "plan_id": 1,
  "max_cost": 100,
  "priorites"="priority1, priority2",
  "condition_score_type": 1
}

returns the ID of the created project.

/planscape-backend/plan/update_project

Description

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.

Usage

PUT /plan/update_project { 
  "id": 1,
  "max_cost": 100,
  "priorites"="priority1, priority2",
  "condition_score_type": 1
}

returns the ID of the updated project.

/planscape-backend/plan/delete_projects

Description

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.

Usage

POST /plan/delete_projects { 
  "project_ids": [1, 2]
}

returns the IDs of the deleted projects.

/planscape-backend/plan/create_project_area

Description

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.

Usage

POST /plan/create_project_area {
  "project_id": 1,
  "geometry": {
    "features": [{
      "geometry": {
        "type': 'Polygon', 'coordinates': [[1, 2], [2, 3], [3, 4], [1, 2](/OurPlanscape/Planscape/wiki/[1,-2],-[2,-3],-[3,-4],-[1,-2)]
      }
     }]
  }
} 

returns the ID of the created project area.

/planscape-backend/plan/get_project_areas

Description

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.

Usage

GET /plan/get_project_areas/?project_id=1

returns the list of project areas within project 1.

/planscape-backend/plan/get_scores

Description

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.

Usage

GET /plan/get_scores/?id=1

returns a JSON object of the form

{'conditions': 
 [
  {'condition': 'foo', 'mean_score': 5.0}, 
  {'condition': 'bar'}
 ]
}