API Documentation

bonsai_api allows users to quickly query data from the BONSAI graph database. It is an application programming interface (API) based on representational state transfer (REST) services. It requires simple resource-oriented URLs, returns JSON-encoded responses and uses standard HTTP response codes. Queries on activities are using the GET method. Queries on LCA calculations are using the POST method. They do not require authentication.

Objective

The API should become the intermediary between the database, the LCA calculation module and the users. Upon completion, bonsai_api is destined to be queried by users’ own applications as well as providing data to the Bonsai graphical user interface.

How to use it?

From a Python environment, querying the first 5 activities in the BONSAI database, sorted by label, would look like:

import requests
r = requests.get('https://api.bonsai.uno/activities/', params = {'lim':5, "sort":"label"})
r.json()
Or from a console, for example using curl:
curl https://api.bonsai.uno/activities/?lim=5&sort=label

Both would print out:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

    [
      {"uri": "http://rdf.bonsai.uno/activitytype/core/eg", "label": "Electricity grid"},
      {"uri": "http://rdf.bonsai.uno/activitytype/core/em", "label": "Market for electricity"},
      {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_ALUM", "label": "Aluminium production"},
      {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_ALUO", "label": "Mining of aluminium ores and concentrates"},
      {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_ALUW", "label": "Re-processing of secondary aluminium into new aluminium"}
    ]

Summary of queries

Resource Operation Description
  GET /v1/ui/  
  GET /v1/ui/(path:filename)  
Activities list query GET /v1/activities/ Get list of available activities.
Flows list query GET /v1/activities/get_relations/(URI) Get list of flows related to a specified activity.
LCA results query POST /v1/do_lca/ Get impacts for a specified functional unit.
Search activities query GET /v1/activities/by_label/(substring) Get list of activities that match search criteria.
  GET /v1/activities/by_uri/(substring)  

API Details

GET /v1/activities/

Returns a list of activities contained in the BONSAI database.

Example request:

GET /v1/activities/ HTTP/1.1
Host: https://api.bonsai.uno
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
[
  {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_FAUX", "label": "Activities auxiliary to financial intermediation (67)"},
  {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_ORGA", "label": "Activities of membership organisation n.e.c. (91)"},
  {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_TAIR", "label": "Air transport (62)"}
]
Query Parameters:
 
  • sort – sorts by alphabetical order, based on URI or label. Possible values: sort=uri, sort=label.
  • lim – limits the length of results, of type integer (e.g., 10). Possible values: between 0 and 1000. Defaults to 100.
Response Headers:
 
Status Codes:
Returns:

flask.response_class
POST /v1/do_lca/

Returns a list of impacts for one or several functional units specified.

Example request:

POST /v1/do_lca/ HTTP/1.1
Host: https://api.bonsai.uno
Request Headers:
 
Request JSON Object:
 
  • URI (string) – specifies the URI of the activity
  • amount (number) – specifies the amount of the reference flow
  • unit (string) – specifies the unit of the reference flow
  • method (string) – specifies the impact method (e.g., “CML 2001”)
  • algorithm (string) – specifies the linking algorithm (e.g., “attributional”)

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
[
    {"uri": "http://rdf.bonsai.uno/someUri1", "label": "Electricity production, coal"}: {
      "Global Warming Potential 100a": [
          {"impact": 0.102, "unit": "kg CO2-eq."}
      ],
      "Acidification": [
          {"impact": 1.2e-5, "unit": "kg SO2-eq."}
      ]

    },
    {"uri": "http://rdf.bonsai.uno/someUri2", "label": "Electricity production, nuclear"}: {
      "Global Warming Potential 100a": [
          {"impact": 0.02, "unit": "kg CO2-eq."}
      ],
      "Acidification": [
          {"impact": 1.2e-2, "unit": "kg SO2-eq."}
      ]

    }
]
Response Headers:
 
Status Codes:
Returns:

flask.response_class
GET /v1/ui/

Home page of the OpenAPI Console UI.

Return:
GET /v1/activities/get_relations/(URI)

Returns a list of activity flows that are input of and output of the specified activity.

Example request:

GET /v1/activities/get_relations/http://rdf.bonsai.uno/activitytype/core/eg HTTP/1.1
Host: https://api.bonsai.uno
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
[
    {
      "isInputOf": [
        {
          "label": "some label",
          "uri": "some URI"
        }
      ],
      "isOutputOf": [
        {
          "label": "some other label",
          "uri": "some other URI"
        }
      ],
      "label": "Electricity grid",
      "uri": "http://rdf.bonsai.uno/activitytype/core/eg"
    }
  ]
Response Headers:
 
Status Codes:
Returns:

flask.response_class
GET /v1/activities/by_label/(substring)

Returns a list of one or several activities in the BONSAI database for which the label contains the specified substring.

Example request:

GET /v1/activities/by_label/alu HTTP/1.1
Host: https://api.bonsai.uno
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
  [
      {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_ALUO", "label": "Mining of aluminium ores and concentrates"}, {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_ALUW", "label": "Re-processing of secondary aluminium into new aluminium"}
  ]
Response Headers:
 
Status Codes:
Returns:

flask.response_class
GET /v1/activities/by_uri/(substring)

Returns a list of one or several activities in the BONSAI database for which the URI contains the specified substring.

Example request:

GET /v1/activities/by_uri/ALU HTTP/1.1
Host: https://api.bonsai.uno
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
  [
      {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_ALUO", "label": "Mining of aluminium ores and concentrates"}, {"uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_ALUW", "label": "Re-processing of secondary aluminium into new aluminium"}
  ]
Response Headers:
 
Status Codes:
Returns:

flask.response_class
GET /v1/ui/(path: filename)

Servers the static files for the OpenAPI Console UI.

Parameters:
  • filename – Requested file contents.
Return: