openapi: 3.0.0 info: title: Trase Public API version: "1.1" contact: name: Trase Public API url: https://mongabay.trase.earth/ email: info@trase.earth termsOfService: https://mongabay.trase.earth/terms-of-use.html license: name: MIT License description: >- This is a DRAFT version 1.1 of the public API for [Trase](http://mongabay.trase.earth). # Introduction The Trase Public API allows access to trade flow data of the forest risk commodities hosted in Trase’s database. For a list of available commodities and country contexts please refer to the documentation on the Trase homepage: https://trase.earth/about # Entities The API will expose the following entities present in Trase: 1. attributes: quantitative and qualitative attributes associated with Trase data. These include, for example our flagship indicators for deforestation risk, along with other metrics relevant to social and environmental risk 2. commodities: the forest risk commodities covered by the Trase database 3. countries: source countries for commodities covered by the Trase database 4. flows: provides the list of nodes in a supply chain (path) from source to destination 5. nodes: provides entities participating in the supply chain. Each has a "node type" (see below), e.g. MUNICIPALITY, EXPORTER, but they are also grouped in the system by a more generic "role" as follows: a. sources: source nodes, such as municipalities in Brazil or departments in Paraguay b. traders: exporters or importers of commodities c. destinations: destination nodes, such as importing countries 6. node types: the types of nodes at particular positions in supply chains per country / commodity combination # Discovering node identifiers A typical scenario for API use is likely to be one where the point of entry into the data will be a commodity source, an exporter, an importer or a destination. All of these entities are nodes, but in Trase we group them by "role" in the supply chain. As a first step, users would therefore use the sources / exporters / importers / destinations endpoints, which allow discovery of the identifiers of entities by searching by name and existing natural identifiers (e.g. ISO code). At this stage, nodes in the Trase system do not have standardised identifiers, so this first step is necessary to allow cross-referencing of nodes against the points of interest from a user-perspective. Accessing information via these endpoints will also allow the user to discover the availability of indicators associated with these nodes. In the following step, users can use those identifiers to pull data for a particular node. # Retrieving attribute values It is possible to retrieve full flow data using the flows endpoint. It is also possible to retrieve data filtered by a particular node, which includes both values of attributes for flows in which the node participates (flow attributes), as well as values of some attributes which are not calculated from flows but are specific to the nodes themselves (node attributes). # Sample usage - retrieving flow data for country / commodity Use the commodities endpoint to discover identifiers of available commodities. At the same time, you can also retrieve ids of countries from which the commodities are sourced. /api/public/commodities?include=countries Countries can be retrieved using the countries endpoint. /api/public/countries?include=commodities Now by using the attributes endpoint, it is possible to find out what attributes are available for Brazil beef: /api/public/attributes?commodity=BEEF&country=BR Volume data is available for years 2015-2017 and it is possible to select particular years using the API. For example, to request data for 2016-2017: /api/public/flows?commodity=BEEF&country=BR&start_year=2016&end_year=2017&page=1 Data is paginated. # Sample usage - retrieving data about a node Discover the identifier of the sourcing place. /api/public/nodes/sources?country=BR&commodity=BEEF&name=SORRISO Data is available for years 2003-2017. Request data for 2017 using the id number of the node of interest (e.g. the id of SORRISO is 11113): /api/public/nodes/11113/data?year=2017 servers: - url: https://mongabay.trase.earth/api/public paths: /countries: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: array items: allOf: - $ref: "#/components/schemas/country" - type: object properties: commodities: type: array items: $ref: "#/components/schemas/commodity" application/json: examples: response: value: - id: 1 name: BRAZIL iso: BR commodities: - {} - {} - {} - {} - {} summary: List of sourcing countries description: > List of all sourcing countries in the system. Optionally include commodities sourced from these countries. parameters: - $ref: "#/components/parameters/commodities_ids" - in: query name: include description: Comma-separated list of nested associations to include, e.g. "commodities". schema: type: string /commodities: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: array items: allOf: - $ref: "#/components/schemas/commodity" - type: object properties: countries: type: array items: $ref: "#/components/schemas/country" application/json: examples: response: value: - name: SOY id: 1 countries: - {} - {} - {} - {} - {} - name: SOY id: 1 countries: - {} - {} - name: SOY id: 1 countries: - {} - {} - name: SOY id: 1 countries: - {} - {} - {} summary: List of commodities description: List of all commodities in the system. Optionally include countries from which commodities are sourced. parameters: - $ref: "#/components/parameters/countries_ids" - in: query name: include description: 'Comma-separated list of nested associations to include, eg: "countries"' schema: type: string /nodes: {} /nodes/sources: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: allOf: - $ref: "#/components/schemas/node_with_availability" - $ref: "#/components/schemas/node_geo_id" required: - data parameters: - $ref: "#/components/parameters/country_opt" - $ref: "#/components/parameters/commodity_opt" - $ref: "#/components/parameters/geo_id" - $ref: "#/components/parameters/node_type" - $ref: "#/components/parameters/name_prefix" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/per_page" description: "List of commodity sourcing places, which can be nodes of different node type (possible to filter down by node type) depending on the supply chain (path) definition in a given country - commodity combination." summary: List of commodity sourcing places /nodes/destinations: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: allOf: - $ref: "#/components/schemas/node_with_availability" - $ref: "#/components/schemas/node_geo_id" - $ref: "#/components/schemas/destination_node" required: - data description: "List of commodity destination places, which can be nodes of different node type (possible to filter down by node type) depending on the supply chain (path) definition in a given country - commodity combination." summary: List of commodity destination places parameters: - $ref: "#/components/parameters/commodity_opt" - $ref: "#/components/parameters/country_opt" - $ref: "#/components/parameters/geo_id" - $ref: "#/components/parameters/node_type" - $ref: "#/components/parameters/name_prefix" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/per_page" /nodes/exporters: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: allOf: - $ref: "#/components/schemas/node_with_availability" - $ref: "#/components/schemas/exporter_node" required: - data description: "List of commodity exporting traders, which can be nodes of different node type (possible to filter down by node type) depending on the supply chain (path) definition in a given country - commodity combination." summary: List of commodity exporters parameters: - $ref: "#/components/parameters/commodity_opt" - $ref: "#/components/parameters/country_opt" - $ref: "#/components/parameters/node_type" - $ref: "#/components/parameters/name_prefix" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/per_page" /nodes/importers: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: allOf: - $ref: "#/components/schemas/node_with_availability" - $ref: "#/components/schemas/importer_node" required: - data description: "List of commodity importing traders, which can be nodes of different node type (possible to filter down by node type) depending on the supply chain (path) definition in a given country - commodity combination." summary: List of commodity importers parameters: - $ref: "#/components/parameters/commodity_opt" - $ref: "#/components/parameters/country_opt" - $ref: "#/components/parameters/node_type" - $ref: "#/components/parameters/name_prefix" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/per_page" /attributes: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: allOf: - $ref: "#/components/schemas/attribute" - type: object properties: availability: $ref: "#/components/schemas/availability" required: - availability required: - data application/json: examples: response: value: data: - id: 444 name: SOY_DEFORESTATION_5_YEAR displayName: Soy deforestation risk (5 years) unit: ha unitType: area availability: - country: BR commodity: SOY years: - 2006 - 2007 - 2008 - 2009 - 2010 - 2011 - 2012 - 2013 - 2014 - 2015 - 2016 - 2017 - id: 36 name: CIF displayName: null unit: USD unitType: currency availability: - country: AR commodity: SOY years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: EC commodity: SHRIMP years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: CO commodity: COFFEE years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: BO commodity: SOY years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: CO commodity: WOOD PULP years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: CO commodity: SHRIMP years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: CO commodity: COCOA years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: CO commodity: BEEF years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: CO commodity: CRUDE PALM OIL years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: CO commodity: PALM KERNEL years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: AR commodity: CORN years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: AR commodity: COTTON years: - 2013 - 2014 - 2015 - 2016 - 2017 - country: AR commodity: WOOD PULP years: - 2013 - 2014 - 2015 - 2016 - 2017 summary: "List of all attributes in the system. Optionally include:" parameters: - $ref: "#/components/parameters/country_opt" - $ref: "#/components/parameters/commodity_opt" description: List of attributes (indicators), with their ids, names, display names, units and availability for country / commodity combinations in different years. "/nodes/{id}/data": get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: object required: - name - nodeType - geoId - availability - flowAttributes - nodeAttributes properties: name: type: string nodeType: type: string geoId: type: string unit: type: string availability: type: array items: $ref: "#/components/schemas/availability" flowAttributes: type: array items: type: object properties: commodity: type: string country: type: string flowId: type: integer values: type: array items: type: object properties: id: type: integer value: type: number year: type: integer required: - id - value - year required: - commodity - country - values nodeAttributes: type: array items: type: object properties: commodity: type: string country: type: string values: type: array items: type: object properties: id: type: integer year: type: integer value: type: number required: - id - year - value required: - commodity - country - values required: - data application/json: examples: response: value: data: name: ALTO ALEGRE DOS PARECIS nodeType: MUNICIPALITY geoId: BR-1100379 availability: - years: - 2012 - 2013 - 2014 - 2015 - 2016 - 2017 country: BR commodity: SOY nodeAttributes: - values: - id: 95 year: 2017 value: 0 - id: 80 year: 2017 value: 937.29 - id: 33 year: 2017 value: 2981 - id: 89 year: 2017 value: 0 country: BR commodity: SOY flowAttributes: - values: - id: 1 year: 2017 value: 502.2964572384 - id: 2 year: 2017 value: 214450.449453362 - id: 33 year: 2017 value: 105.217106928182 country: BR flowId: 54131240 commodity: SOY summary: Node properties and attribute values parameters: - name: id in: path description: Id of the node required: true schema: type: string - $ref: "#/components/parameters/year_req" description: Information about a node, including name, node type and geo id. It also includes the availability for country / commodity combinations in different years and node and flow attributes. /flows: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: type: object properties: year: type: integer path: type: array items: type: integer flowAttributes: type: array items: type: object properties: attributeId: type: integer value: oneOf: - type: string - type: number required: - value required: - year - path required: - data application/json: examples: response: value: data: - data: - year: 2017 path: - 11626 - 267 - 10684 - 11271 - 12460 - 28265 - 27757 - 212 flowAttributes: - attributeId: 37 value: 97.3052314237206 - attributeId: 14 value: 15756.3191550692 - attributeId: 8 value: 28.3523401584267 - attributeId: 39 value: 8149.54492168693 - attributeId: 2 value: 44.0096364875163 - attributeId: 5 value: 0 - attributeId: 44 value: 0.00604213363675935 - attributeId: 26 value: 0.00120842672735187 - attributeId: 45 value: 0 - attributeId: 52 value: 1.58696639969484 - attributeId: 18 value: 0.31739327993897 - year: 2017 path: - 11627 - 263 - 10176 - 9827 - 12458 - 28245 - 28246 - 53 flowAttributes: - attributeId: 37 value: 97.3048815004618 - attributeId: 14 value: 35826.684319655 - attributeId: 8 value: 19.3065241072345 - attributeId: 39 value: 0 - attributeId: 2 value: 0 parameters: - $ref: "#/components/parameters/commodity_req" - $ref: "#/components/parameters/country_req" - $ref: "#/components/parameters/attribute_with_default" - $ref: "#/components/parameters/start_year_with_default" - $ref: "#/components/parameters/end_year_with_default" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/per_page" description: List of flows, with their ids, paths and attributes associated to the nodes on the paths. summary: Flows data /node_types: get: responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: type: object properties: country: type: string commodity: type: string node_types: type: array items: $ref: "#/components/schemas/node_type" required: - country - commodity - node_types required: - data description: "This endpoint will allow users to understand the structure of flow paths in different country / commodity combinations. It will return an ordered list of objects with the following information: node type id, node type name, role." summary: List of node types as they appear in flow paths parameters: - $ref: "#/components/parameters/country_opt" - $ref: "#/components/parameters/commodity_opt" /top_nodes: get: tags: - PROPOSED - NOT IMPLEMENTED YET responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: type: array items: $ref: "#/components/schemas/node_with_value_and_height" meta: type: object properties: country: $ref: "#/components/schemas/country" commodity: $ref: "#/components/schemas/commodity" attribute: $ref: "#/components/schemas/attribute" node_type: $ref: "#/components/schemas/node_type" path_nodes: type: array items: $ref: "#/components/schemas/exporter_node" start_year: type: integer example: 2003 end_year: type: integer example: 2017 total: type: number example: 100 required: - data - meta parameters: - $ref: "#/components/parameters/country_req" - $ref: "#/components/parameters/commodity_req" - $ref: "#/components/parameters/attribute_with_default" - $ref: "#/components/parameters/node_type_req" - $ref: "#/components/parameters/path_nodes_ids" - $ref: "#/components/parameters/start_year_with_default" - $ref: "#/components/parameters/end_year_with_default" - $ref: "#/components/parameters/limit" description: "List of top nodes of given node type for country - commodity combination ordered by total value of flow attribute in requested year range." summary: List of top nodes of given node type for country - commodity combination ordered by total value of flow attribute in requested year range. /nodes/data: get: tags: - PROPOSED - NOT IMPLEMENTED YET responses: "200": description: "" content: text/html; charset=utf-8: schema: type: object properties: data: type: array items: type: array items: $ref: "#/components/schemas/node_with_values" meta: type: object properties: country: $ref: "#/components/schemas/country" commodity: $ref: "#/components/schemas/commodity" attribute: $ref: "#/components/schemas/attribute" node_type: $ref: "#/components/schemas/node_type" nodes: type: array items: $ref: "#/components/schemas/source_node" path_nodes: type: array items: $ref: "#/components/schemas/exporter_node" years: type: array items: type: integer example: [2016, 2017] required: - data - meta parameters: - $ref: "#/components/parameters/country_req" - $ref: "#/components/parameters/commodity_req" - in: query name: attribute_id description: Numeric flow attribute id, for which values will be returned. schema: type: string - $ref: "#/components/parameters/path_nodes_ids" - $ref: "#/components/parameters/nodes_ids" - $ref: "#/components/parameters/node_type" - $ref: "#/components/parameters/start_year_with_default" - $ref: "#/components/parameters/end_year_with_default" description: "Values of requested attribute for requested nodes (nodes_ids) in requested year range. It is possible to filter down values by nodes which should appear on same path (path_nodes_ids), which allows for example to retrieve value for a sourcing region filtered by an exporter." summary: Values of flow attributes for selected nodes. components: parameters: page: name: page in: query description: 1-based number of requested page for paginated resources schema: type: integer minimum: 1 default: 1 per_page: name: per_page in: query description: Number of objects per page for paginated resources schema: type: integer default: 100 country_opt: name: country in: query description: Country iso 2, e.g. BR schema: type: string commodity_opt: name: commodity in: query description: Commodity name, e.g. SOY schema: type: string commodity_req: in: query name: commodity description: Commodity name, e.g. SOY required: true schema: type: string country_req: in: query name: country description: Country ISO 2, e.g. BR required: true schema: type: string commodities_ids: in: query name: commodities_ids description: Comma-separated list of numeric commodity ids. schema: type: string countries_ids: in: query name: countries_ids description: Comma-separated list of numeric country ids. schema: type: string path_nodes_ids: in: query name: path_nodes_ids description: Comma-separated list of numeric node ids to filter flows. schema: type: string nodes_ids: in: query name: nodes_ids description: Comma-separated list of numeric node ids to return values for. When empty, all matching nodes returned, but node type needs to be provided. TODO check if that might require introducing pagination. schema: type: string geo_id: in: query name: geo_id description: Geo identifier, e.g. BR-5107925 schema: type: string node_type: name: node_type in: query description: Node type name, e.g. MUNICIPALITY schema: type: string node_type_req: name: node_type in: query description: Node type name, e.g. MUNICIPALITY required: true schema: type: string source_node_type_with_default: name: node_type in: query description: Node type name, e.g. MUNICIPALITY; when not provided, default source node type used (depending on data availability in country - commodity combination) schema: type: string exporter_node_type_with_default: name: node_type in: query description: Node type name, e.g. EXPORTER; when not provided, default exporter node type used (depending on data availability in country - commodity combination) schema: type: string importer_node_type_with_default: name: node_type in: query description: Node type name, e.g. IMPORTER; when not provided, default importer node type used (depending on data availability in country - commodity combination) schema: type: string destination_node_type_with_default: name: node_type in: query description: Node type name, e.g. COUNTRY; when not provided, default source node type used (depending on data availability in country - commodity combination) schema: type: string name_prefix: name: name in: query description: Node name prefix schema: type: string year_req: name: year in: query description: Year of data required: true schema: type: integer year_with_default: name: year in: query description: Year of data, when not provided last available year schema: type: integer start_year_with_default: in: query name: start_year description: Start year of data, when not provided no lower limit on year range applied. schema: type: integer end_year_with_default: in: query name: end_year description: End year of data, when not provided no upper limit on year range applied. schema: type: string attribute_with_default: in: query name: attribute_id description: Flow attribute id, when not provided defaults to trade volume schema: type: integer limit: in: query name: limit description: Number of elements to return schema: type: integer schemas: node: type: object description: Single node record. properties: id: type: integer name: type: string example: SORRISO required: - id - name node_geo_id: type: object properties: geo_id: type: string example: BR-5107925 required: - geo_id node_node_type: type: object properties: node_type: type: string example: MUNICIPALITY required: - node_type source_node: allOf: - $ref: "#/components/schemas/node" - $ref: "#/components/schemas/node_node_type" exporter_node: allOf: - $ref: "#/components/schemas/node" - $ref: "#/components/schemas/node_node_type" - type: object properties: name: example: CARGILL node_type: example: EXPORTER importer_node: allOf: - $ref: "#/components/schemas/node" - $ref: "#/components/schemas/node_node_type" - type: object properties: name: example: CARGILL node_type: example: IMPORTER destination_node: allOf: - $ref: "#/components/schemas/node" - $ref: "#/components/schemas/node_node_type" - type: object properties: name: example: CHINA node_type: example: COUNTRY node_with_availability: allOf: - $ref: "#/components/schemas/source_node" - type: object properties: availability: type: array items: $ref: "#/components/schemas/availability" required: - availability country: type: object description: Single country record. properties: id: type: number example: 1 name: type: string example: BRAZIL iso: type: string minLength: 2 maxLength: 2 example: BR required: - id - name - iso commodity: type: object description: Single commodity record properties: id: type: number example: 1 name: type: string example: SOY required: - id - name availability: type: object properties: commodity: type: string example: SOY country: type: string example: BR years: type: array items: type: integer description: Years of data available for country / commodity combination attribute: type: object description: Attribute (indicator) properties: id: type: integer example: 31 display_name: type: string example: 'Trade volume' unit: type: string example: 'Mt' tooltip_text: type: string example: '...' required: - id - display_name node_type: type: object description: Node type properties: id: type: integer example: 1 name: type: string example: MUNICIPALITY role: type: string example: source required: - id - name - role node_with_value_and_height: description: Node object in list ordered by total value of flow attribute for year range, with height to express percentage of total across all matching nodes. allOf: - $ref: "#/components/schemas/node" - $ref: "#/components/schemas/node_geo_id" - type: object properties: value: type: number example: 43 height: type: number example: 0.43 node_with_values: description: Node object with values of flow attributes per year. Values are returned in an array that matches the array of years in meta object. allOf: - $ref: "#/components/schemas/node" - type: object properties: values: type: array items: type: number example: [23.07, 38.5]