pandarus-remote 1.1

No project description provided

Pandarus_remote is a web service for processing and managing data for regionalized life cycle assessment using pandarus. It is meant to be used by the brightway2-regional library.

Contents

• Installation

  • Requirements

• Running the web service

  • Environment variables

• API endpoints

  • /

  • /catalog

    • Response

  • /upload

    • Parameters

    • Responses

  • /intersection

    • Parameters

    • Responses

  • /intersection-file

    • Parameters

    • Responses

  • /calculate-intersection

    • Parameters

    • Responses

  • /remaining

    • Parameters

    • Responses

  • /calculate-remaining

    • Parameters

    • Responses

  • /rasterstats

    • Parameters

    • Responses

  • /calculate-rasterstats

    • Parameters

    • Responses

  • /status/<job_id>

    • Reponse

Installation

pandarus_remote can be installed using pip, but your life will be much easier if you use conda to get consistent dependencies:

conda config --add channels conda-forge
conda config --add channels cmutel
conda create -n pandarus python=3.9
conda activate pandarus
conda install pandarus_remote

Requirements

pandarus_remote requires the following Python libraries:

• appdirs

• docopt

• fiona

• flask

• pandarus

• peewee

• redis

• rasterio

• requests

• rq

In addition, pandarus_remote requires that Redis be installed.

Running the web service

A Redis server must be running on the local machine.

A worker process for rq should be started with the command rq worker.

Finally, run the flask application any way you want. For example, to run the test server (not in production!), do:

export FLASK_APP=/path/to/pandarus_remote/__init__.py
flask run

Environment variables

The following environment variables can be used to configure pandarus_remote:

• PANDARUS_EXPORT_FORMAT: A string specifying the Fiona driver to use, like “GPKG” or “GeoJSON”

• PANDARUS_CPUS: The number of CPUs to use when performing intersection calculations

API endpoints

The following API endpoints are supported:

/

Ping the server. Returns something like pandarus_remote web service, version (1, 0).

HTTP method: GET

/catalog

Get the list of spatial datasets and results currently available on the server.

HTTP method: GET

Response

• 200: Return a JSON payload of the form:

[
    'files': [
        ('file name', 'hex-encoded sha256 hash of file contents', 'type of file')
    ],
    'intersections': [
        ('input file 1 sha256 hash', 'input file 2 sha256 hash')
    ],
    'remaining': [
        ('input file 1 sha256 hash', 'input file 2 sha256 hash')
    ],
    'rasterstats': [
        ('vector file sha256 hash', 'raster file sha256 hash')
    ]
]

/upload

Upload a spatial data file. The provided file must be openable by fiona or rasterio.

HTTP method: POST

Parameters

Post the following required form data:

• name: File name

• sha256: SHA 256 hash of file

• band: Raster band number. This field is required; pass '' if single-band raster or vector dataset.

• layer: Vector layer name. This field is required; pass '' if single-layer vector or raster dataset.

• field: Vector field that uniquely identifies spatial features. This field is required; pass '' if raster dataset.

The file should be in the field file.

Responses

• 201: The file was uploaded and registered. Returns a JSON payload:

{
    'filename': 'some file name',
    'sha256': 'hex-encoded sha256 hash of file contents'
}

• 400: The request form was missing a required field

• 406: The input data was invalid (either the hash wasn’t correct or the file isn’t a readable geospatial dataset)

• 409: File already exists

• 413: The uploaded file was too large (current limit is 250 MB)

/intersection

Request the download of a pandarus intersections JSON data file for two spatial datasets. Both spatial datasets should already be on the server (see /upload), and the intersection should already be calculated (see /calculate-intersection).

HTTP method: POST

Parameters

Post the following form data:

• first: SHA 256 hash of first input file

• second: SHA 256 hash of second input file

Responses

• 200: The requested file will be returned

• 400: The request form was missing a required field

• 404: An intersections file for this combination was not found

/intersection-file

Request the download of the new geospatial vector file created when calculating the intersection of two spatial datasets. Both spatial datasets should already be on the server (see /upload), and the intersection should already be calculated (see /calculate-intersection).

HTTP method: POST

Parameters

Post the following form data:

• first: SHA 256 hash of first input file

• second: SHA 256 hash of second input file

Responses

• 200: The requested file will be returned

• 400: The request form was missing a required field

• 404: An intersections file for this combination was not found

/calculate-intersection

Calculate a pandarus intersections file for two vector spatial datasets. Both spatial datasets should already be on the server (see /upload). The second vector dataset must have the geometry type Polygon or MultiPolygon.

HTTP method: POST

Parameters

Post the following form data:

• first: SHA 256 hash of first input file

• second: SHA 256 hash of second input file

Responses

• 200: The requested intersections file will be calculated. Returns the URL of the job status resource (see /status) which can be polled to see when the calculation is finished.

• 400: The request form was missing a required field

• 404: One of the files were not found

• 406: Error in the files: Either the hashes were identical, or the files weren’t vector datasets, or the second file didn’t have the correct geometry type.

• 409: The requested intersection file already exists

/remaining

Request the download of the JSON data file from a remaining areas calculation. Both spatial datasets should already be on the server (see /upload), and the remaining areas should already be calculated (see /calculate-remaining).

HTTP method: POST

Parameters

Post the following form data:

• first: SHA 256 hash of first input file

• second: SHA 256 hash of second input file

Responses

• 200: The requested file will be returned

• 400: The request form was missing a required field

• 404: An remaining areas file for this combination was not found

/calculate-remaining

Calculate a pandarus remaining areas file for two vector spatial datasets. See the Pandarus documentation for more details on remaining areas. Both spatial datasets should already be on the server (see /upload), and their intersection should already be calculated.

HTTP method: POST

Parameters

Post the following form data:

• first: SHA 256 hash of first input file

• second: SHA 256 hash of second input file

Responses

• 200: The requested remaining areas file will be calculated. Returns the URL of the job status resource (see /status) which can be polled to see when the calculation is finished.

• 400: The request form was missing a required field

• 404: One of the files or the calculated intersection result were not found

• 409: The requested remaining areas file already exists

/rasterstats

Request the download of the JSON data file from a raster stats calculation. Both spatial datasets should already be on the server (see /upload), and the raster stats should already be calculated (see /calculate-rasterstats).

HTTP method: POST

Parameters

Post the following form data:

• vector: SHA 256 hash of vector input file

• raster: SHA 256 hash of raster input file

Responses

• 200: The requested file will be returned

• 400: The request form was missing a required field

• 404: An raster stats file for this combination was not found

/calculate-rasterstats

Calculate a pandarus raster stats file for two vector spatial datasets. See the Pandarus documentation for more details on raster stats. Both spatial datasets should already be on the server (see /upload), and their intersection should already be calculated.

HTTP method: POST

Parameters

Post the following form data:

• vector: SHA 256 hash of vector input file

• raster: SHA 256 hash of raster input file

Responses

• 200: The requested raster stats file will be calculated. Returns the URL of the job status resource (see /status) which can be polled to see when the calculation is finished.

• 400: The request form was missing a required field

• 404: One of the files was not found

• 406: One of the files had an incorrect data type

• 409: The requested remaining areas file already exists

/status/<job_id>

Get the status of a currently running job. Job status URLs are returned by the /calculate-intersection and /calculate-area endpoints.

HTTP method: GET

Reponse

• 200: Returns a text response giving the current job status. If the job is finished, the response will be finished.

• 404: The requested job id was not found