Backend API

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

Get 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

Fetch the geometry of a particular boundary as a GeoJSON object. Optionally, clip the boundaries to a known 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

Fetch 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

Fetch 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

Create and store a plan in the Planscape database from a name, region name, and geoemtry. The plan is associated with the user, which can be 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

Delete one or more plans by ID. Only those plans owned by the 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, return the top-level information about the plan.

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

/planscape-backend/plan/list_plans_by_owner

Description

List plans by owner. If the owner is not present, returns all the plans that have owner=null.

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

Create a project within a plan. The project is owned by the user creating the project.

Usage

POST /plan/create_project { plan_id: 1, max_cost: 100, ...}

returns the ID of the created project.

Existing Projects