USEEIO-API

Base URL: /api, Version: 1.1, The USEEIO API Wiki on github provides more information on using the API.

A RESTful API that provides access to versions of the USEEIO model. Results are returned as JSON objects or csv files.

Schemes: http

Summary

Path	Operation	Description
/models	GET	Get the available models from the server.
/sectorcrosswalk.csv	GET	Provide a crosswalk of sector codes from the BEA and NAICS schemas. Field names are in a 'SchemaName_Year_SchemaLevel_Code' pattern, e.g. 'BEA_2012_Sector_Code'
/{model}/calculate	POST	Calculate the result for a given demand and perspective.
/{model}/demands	GET	Returns a list with all available demand vectors from a model
/{model}/demands/{demandID}	GET	Returns a demand vector from the model
/{model}/flows	GET	Get all flows of the model.
/{model}/flows/{flowID}	GET	Get flow information by ID.
/{model}/indicators	GET	Get all indicators of the model.
/{model}/indicators/{indicatorID}	GET	Get indicator information by ID.
/{model}/matrix/A	GET	Get the direct requirements matrix of the IO model.
/{model}/matrix/A_d	GET	Get the domestic direct requirements matrix of the IO model.
/{model}/matrix/B	GET	Get the satellite matrix of the IO model.
/{model}/matrix/B_dqi	GET	Get the data quality entries of the satellite matrix.
/{model}/matrix/C	GET	Get the characterization factors.
/{model}/matrix/D	GET	Get the direct impact assessment results.
/{model}/matrix/D_dqi	GET	Get the data quality results of the direct impact assessment results.
/{model}/matrix/L	GET	Get the Leontief inverse of the IO model.
/{model}/matrix/L_d	GET	Get the domestic Leontief inverse of the IO model.
/{model}/matrix/M	GET	Get the direct + indirect impact results.
/{model}/matrix/M_d	GET	Get the direct + indirect domestic impact results.
/{model}/matrix/N	GET	Get the direct + indirect impact results.
/{model}/matrix/N_d	GET	Get the direct + indirect domestic impact results.
/{model}/matrix/N_dqi	GET	Get the data quality results of the total impact assessment results.
/{model}/matrix/Phi	GET	Get the price type adjustment ratios by year.
/{model}/matrix/q	GET	Get the commodity output vector
/{model}/matrix/Rho	GET	Get the currency year adjustment factors.
/{model}/matrix/{name}	GET	Get a row or column of a matrix.
/{model}/sectors	GET	Get all sectors of the IO model.
/{model}/sectors/{sectorID}	GET	Get the information of the sector with the given ID.
/{model}/years	GET	Get all years with data for Phi and Rho matrices.

Paths

Get the available models from the server.

GET /models

application/json

200 OK: Successfully returned an array of model names.

Model

Provide a crosswalk of sector codes from the BEA and NAICS schemas. Field names are in a 'SchemaName_Year_SchemaLevel_Code' pattern, e.g. 'BEA_2012_Sector_Code'

GET /sectorcrosswalk.csv

All models sectors are associated with codes. These codes are derived from the BEA or NAICS. This crosswalk can be used to relate other data using these classifications.

text/csv; charset=utf-8

200 OK: Successfully returned the sector crosswalk.

Calculate the result for a given demand and perspective.

POST /{model}/calculate

application/json

The demand vector and perspective for the calculation.

Demand


model	The ID of the input-output model to use	path	string

application/json

200 OK: Successfully returned a calculation result.

Result

Returns a list with all available demand vectors from a model

GET /{model}/demands


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned an array of available demand vectors.

DemandInfo

Returns a demand vector from the model

GET /{model}/demands/{demandID}


model	The ID of the input-output model to use.	path	string
demandID	The ID of the demand vector.	path	string

application/json

200 OK: Successfully returned a demand vector for the given model.

DemandEntry

Get all flows of the model.

GET /{model}/flows


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned an array of flows in the given model.

Flow

Get flow information by ID.

GET /{model}/flows/{flowID}


model	The ID of the input-output model to use.	path	string
flowID	The ID of the flow.	path	string

application/json

200 OK: Successfully returned an array with data on the given flow in the given model.

Flow
404 Not Found: Flow not found.

Get all indicators of the model.

GET /{model}/indicators


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned an array of indicators in the given model.

Indicator

Get indicator information by ID.

GET /{model}/indicators/{indicatorID}


model	The ID of the input-output model to use.	path	string
indicatorID	The ID of the indicator.	path	string

application/json

200 OK: Successfully returned an array with data on the given indicator in the given model.

Indicator
404 Not Found: Indicator not found.

Get the direct requirements matrix of the IO model.

GET /{model}/matrix/A

The matrix A is a sector x sector matrix and contains in each column i the direct sector inputs that are required to produce 1 USD dollar of output from sector i.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the direct requirements matrix for the given model.

number[]

number
500 Internal Server Error: if the server failed to load the matrix file

Get the domestic direct requirements matrix of the IO model.

GET /{model}/matrix/A_d

The matrix A_d is a sector x sector matrix and contains in each column i the domestic direct sector inputs that are required to produce 1 USD dollar of output from sector i.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the domestic direct requirements matrix for the given model.

number[]

number
500 Internal Server Error: A_d matrix not present for the given model

Get the satellite matrix of the IO model.

GET /{model}/matrix/B

The satellite matrix B is a flow x sector matrix and contains in each column i the amount of a flow given in the reference unit of the respective flow per 1 USD output from sector i.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the satellite matrix for the given model.

number[]

number
500 Internal Server Error: if the server failed to load the matrix file

Get the data quality entries of the satellite matrix.

GET /{model}/matrix/B_dqi

The matrix B_dqi contains the corresponding data quality entries of the satellite matrix B in the same matrix dimensions of flows x sector. These entries are in the form of 5 data quality scores (values for each ranging from 1 to 5) for the five EPA LCA flow data quality indicators in this order: (Data reliability, Temporal correlation, Technological correlation, Technological correlation). For example '(3,1,1,4,5)'. For more information on the data quality indicators and score, see the US EPA 2016 Report 'Guidance on Data Quality Assessment for Life Cycle Inventory Data'.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the data quality entries for the satellite matrix for the given model.

string[]

string
500 Internal Server Error: B_dqi matrix not present for the given model

Get the characterization factors.

GET /{model}/matrix/C

In the matrix C, each column k contains the characterization factors of the different LCIA categories related to one reference unit of flow k.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the characterization factor matrix for the given model.

number[]

number
500 Internal Server Error: if the server failed to load the matrix file

Get the direct impact assessment results.

GET /{model}/matrix/D

The matrix D contains in each column i the impact assessment result that is related to the direct emissions and resources for 1 USD output from sector i. From the matrices B and C the direct impact matrix can be calculated via: D = C * B


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned a matrix of direct impact results for the given model.

number[]

number
500 Internal Server Error: if the server failed to load the matrix file

Get the data quality results of the direct impact assessment results.

GET /{model}/matrix/D_dqi

The matrix D_dqi contains the corresponding data quality entries of the direct impact results matrix D in the same matrix dimensions of impacts x sector. These entries are in the form of 5 data quality scores (values for each ranging from 1 to 5) for the five EPA flow data quality indicators in this order, (Data reliability, Temporal correlation, Technological correlation, Technological correlation). For example '(3,1,1,4,5)'. For more information on the data quality indicators and scores, see the US EPA 2016 Report 'Guidance on Data Quality Assessment for Life Cycle Inventory Data'.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned a matrix of data quality entries for the direct impact results for the given model.

string[]

string
500 Internal Server Error: D_dqi matrix not present for the given model

Get the Leontief inverse of the IO model.

GET /{model}/matrix/L

The Leontief inverse L is calculated via L = (I - A)^-1. L is also a sector x sector matrix and contains in each column i the total requirements of the respective sectors inputs to produce 1 USD of output from sector i.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

number[]

number
500 Internal Server Error: if the server failed to load the matrix file

Get the domestic Leontief inverse of the IO model.

GET /{model}/matrix/L_d

The domestic Leontief inverse L_d is calculated via L_d = (I - A_d)^-1. L_d is also a sector x sector matrix and contains in each column i the direct + indirect domestic requirements of the respective sectors inputs to produce 1 USD of output from sector i.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

number[]

number
500 Internal Server Error: L_d matrix not present for the given model

Get the direct + indirect impact results.

GET /{model}/matrix/M

The matrix M is a flow x sector matrix and contains in each column i the direct + indirect flow per 1 USD output of sector i. With the B and the total requirements L, the matrix M which contains the direct + indirect flow totals can be calculated via M = B * L.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

number[]

number
500 Internal Server Error: if the server failed to load the matrix file

Get the direct + indirect domestic impact results.

GET /{model}/matrix/M_d

The matrix M_d is a flow x sector matrix and contains in each column i the direct + indirect flow per 1 USD output of sector i. With the B and the total domestic requirements L_d, the matrix M_d which contains the direct + indirect flow totals can be calculated via M_d = B * L_d.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

number[]

number
500 Internal Server Error: M_d matrix not present for the given model

Get the direct + indirect impact results.

GET /{model}/matrix/N

The matrix N is a indicator x sector matrix and contains in each column i the direct and indirect impact result per 1 USD output of sector i. With the direct impacts D and the total requirements L, the matrix N can be calculated via N = D * L.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

number[]

number
500 Internal Server Error: if the server failed to load the matrix file

Get the direct + indirect domestic impact results.

GET /{model}/matrix/N_d

The matrix N_d is a indicator x sector matrix and contains in each column i the direct and indirect domestic impact result per 1 USD output of sector i. With the direct impacts D and the total domestic requirements L_d, the matrix N_d can be calculated via N_d = D * L_d.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

number[]

number
500 Internal Server Error: M_d matrix not present for the given model

Get the data quality results of the total impact assessment results.

GET /{model}/matrix/N_dqi

The matrix N_dqi contains the corresponding data quality entries of the direct + indirect impact results matrix N in the same matrix dimensions of impacts x sector. These entries are in the form of 5 data quality scores (values for each ranging from 1 to 5) for the five EPA flow data quality indicators in this order, (Data reliability, Temporal correlation, Technological correlation, Technological correlation). For example '(3,1,1,4,5)'. For more information on the data quality indicators and scores, see the US EPA 2016 Report 'Guidance on Data Quality Assessment for Life Cycle Inventory Data'.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned a matrix of data quality entries for the total impact results for the given model.

string[]

string
500 Internal Server Error: N_dqi matrix not present for the given model

Get the price type adjustment ratios by year.

GET /{model}/matrix/Phi

The matrix Phi is a sector x year matrix of producer:purchaser price type adjustment ratios that can be used to put model results in purchaser price. By default, all USEEIO model results are in producer price.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

string[]

string
500 Internal Server Error: if the server failed to load the matrix file

Get the commodity output vector

GET /{model}/matrix/q

The matrix q is a sector indexed single column matrix (or vector) with the annual commodity output in the model dollar year. Available only for commodity models.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

string[]

string
500 Internal Server Error: if the server failed to load the matrix file

Get the currency year adjustment factors.

GET /{model}/matrix/Rho

The matrix Rho is a sector x year matrix of sector-specific currency deflation ratios that can be used to put results into another currency year.


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned the matrix.

string[]

string
500 Internal Server Error: if the server failed to load the matrix file

Get a row or column of a matrix.

GET /{model}/matrix/{name}

Returns the row or column with the given index passed in the query parameter, from the given matrix. See the other matrix descriptions to understand. This function is currently only available for numeric matrices and not the data quality matrices, B_dqi, D_dqi, and U_dqi.


model	The ID of the input-output model to use.	path	string
name	The name of the matrix.	path	string
col	The zero-based index of the column.	query	integer
row	The zero-based index of the row.	query	integer

application/json

200 OK: Successfully returned an array for the given column or row of the given matrix and given model.

number
400 Bad Request: if the column or row index is not a valid integer
500 Internal Server Error: if the server failed to load the matrix file or column

Get all sectors of the IO model.

GET /{model}/sectors


model	The ID of the IO model to use.	path	string

application/json

200 OK: Successfully returned an array of sectors in the given model.

Sector

Get the information of the sector with the given ID.

GET /{model}/sectors/{sectorID}


model	The ID of the input-output model to use.	path	string
sectorID	The ID of the sector.	path	string

application/json

200 OK: Successfully returned an array with data on the given sector in the given model.

Sector
404 Not Found: Sector not found.

Get all years with data for Phi and Rho matrices.

GET /{model}/years


model	The ID of the input-output model to use.	path	string

application/json

200 OK: Successfully returned an array of years in the given model.

Year

Schema definitions

Demand: object

perspective: string , x ∈ { direct , intermediate , final }
demand: object[]: DemandEntry

DemandEntry: object

{
    "amount": 42.42,
    "sector": "112120/US"
}

sector: string: The sector ID.
amount: number

DemandInfo: object

The meta information of a demand vector ...

id: string
year: integer
type: string
system: string
location: string

Flow: object

id: string
index: integer: The matrix index of the flow.
flowable: string: The name of the flow, e.g., 'Sulfuric acid'.
context: string: A path-like set of context compartments in the form of directionality/environmental media/environmental compartment... e.g. 'emission/air/tropophere'
unit: string: a unit name, e.g. 'kg'
uuid: string: Unique hexadecimal ID for the flow

Indicator: object

id: string
index: integer: The matrix index of the indicator.
name: string: Display name of the indicator
code: string: 3 or 4 letter indicator code which is also as label in the user interface
unit: string: The reference unit of the indicator.

Model: object

id: string
name: string
location: string: Model region acryonyms.
description: string
sectorschema: string: The sector schema name of the model corresponding to schemas in sectorcrosswalk.csv.
hash: string: A SHA-256 bit hash of the model used as a model build identifier.

Result: object

indicators: string[]: List of indicator IDs (row index of the result matrix).

string
sectors: string[]: List of sector IDs (column index of the result matrix).

string
data: number[][]: number[]

number
totals: number[]: The result totals for the normalization.

number

Sector: object

id: string
index: integer: The matrix index of the sector.
name: string: Display name of the sector.
code: string: Sector code in the underlying input-output model.
location: string: ID/code of the sector location.

Year: object

index: integer: The matrix index of the Year.
id: string