Compositions API (beta)

Geospatial compositions the process by which user defined functions (UDFs) are applied to geospatial and non-geospatial datasets to create new geospatial datasets. The UDFs can be simple operations like vector level addition or multiplication across layers or more complex like inference from an AI model. The input data can be raster or vector.

Example Workflow

First, add a new vector. This vector will contain the data to perform operations on. In the case of this example, it's wildfire loss data.

curl --location 'https://explorer.sustglobal.io/api/compositions/vector' \
     --header 'X-SustGlobal-Project: compose-demo' \
     --header 'X-SustGlobal-APIKey: ••••••'
     --header 'Content-Type: application/json' \
     --data '{
         "name": "wildfire_loss",
         "geojson": {"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-81.688246,40.999109],[-81.688491,40.988588],[-81.6818,40.988571]]]},"properties":{"loss_wildfire_bsln":0.00001,"loss_wildfire_2050":0.00004,}},
     }'

Next, add a new UDF. This UDF takes the wildfire loss in 2050 and subtracts the baseline wildfire loss. Note UDFs are written in JQ.

curl --location 'https://explorer.sustglobal.io/api/compositions/udf' \
     --header 'X-SustGlobal-Project: compose-demo' \
     --header 'X-SustGlobal-APIKey: ••••••'
     --header 'Content-Type: application/json' \
     --data '{
         "name": "wildfire_loss_delta",
         "equation": {
          "inputLayers": [
            "wildfire_loss"
          ],
          "operation": ".features.[].properties
                        | if .loss_wildfire_bsln == 0 then nan else
                            (.loss_wildfire_2050 - .loss_wildfire_bsln) / .loss_wildfire_bsln 
                           end
                        | [., 0.0] | max
                        | [., 2.0] | min"
         }
     }'

The return value will look something like this:

{
  "id": "4444444444",
  "name": "wildfire_loss_delta",
  "createDate": "2025-01-17",
  "updateDate": "2025-01-17"
}

Activate your UDF once you've created it. This will make the result vector available in your project. (Use the ID from the previous return value in the new url)

curl --location 'https://explorer.sustglobal.io/api/compositions/udf/4444444444/activate' \
     --header 'X-SustGlobal-Project: compose-demo' \
     --header 'X-SustGlobal-APIKey: ••••••'

The return value will look something like this:

{
  "id": "999999999",
  "name": "wildfire_loss_delta",
  "createDate": "2024-03-20",
  "updateDate": "2024-03-21",
  "status": "available"
}

Congrats! You can now use your new vector on any portfolios in your project.

curl --location 'https://explorer.sustglobal.io/api/compositions/vector/999999999/apply?portfolio=test-portfolio' \
     --header 'X-SustGlobal-Project: compose-demo' \
     --header 'X-SustGlobal-APIKey: ••••••'