openapi: 3.0.0
info:
  title: Trase Public API
  version: "1.1"
  contact:
    name: Trase Public API
    url: https://trase.earth/
    email: info@trase.earth
  termsOfService: https://trase.earth/terms-of-use.html
  license:
    name: MIT License
  description: >-
    This is a first version of the public API for [Trase](https://trase.earth/).


    # Introduction


    The Trase Public API allows to access trade flows data of forest risk commodities.


    # Entities


    The API will expose the following entities present in Trase:

    1. attributes: quantitative and qualitative attributes (indicators)

    2. commodities: forest risk commodities

    3. countries: source countries for commodities

    4. flows: models the list of nodes in a supply chain (path) from source to destination

    5. nodes: entities participating in the supply chain. Each has a "node type", e.g. MUNICIPALITY, EXPORTER, but they are also grouped in the system by a more generic "role":

        a. sources: source nodes, such as municipalities in Brazil or departments in Paraguay

        b. traders: exporters / 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


    We assume one of the typical scenarios is one where the point of entry into the data will be a source, an exporter, an importer or a destination. All of these entities are nodes, but int Trase we group them by "role" in the supply chain.


    In the first step, users would use the sources / exporters / importers / destinations endpoints, which allow to discover the identifiers of entities by searching by name and existing natural identifiers (e.g. iso code). For now we need to work around the fact that nodes in the system don't have standardised identifiers, which would allow to skip this step.


    Those endpoints will also allow to discover the availability of indicators. Then in the next step users can use those identifiers to pull data for a particular node.


    # Retrieving attribute values


    It is possible to retrieve full flows 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 (node attributes).


    # Sample usage - retrieving flow data for country / commodity


    Use the commodities endpoint to discover identifiers of available commodities. You can also at the same time retrieve ids of countries from which the commodities are sourced.


    /api/public/commodities?include=countries


    Countries can be retireved using the countries endpoint.


    Now using the attributes endpoint, find out what sttributes are available for Brazil beef:


    /api/public/attributes?commodity=BEEF&country=BR


    Volume data is available for years 2015-2017. Request flows 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:


    /api/public/nodes/{id of SORRISO}/data?year=2017
paths:
  /countries:
    get:
      responses:
        "200":
          description: ""
          content:
            text/html; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/country_with_commodities"
            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:
                  $ref: "#/components/schemas/commodity_with_countries"
            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:
                      $ref: "#/components/schemas/source_node_with_availability"
                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:
                      $ref: "#/components/schemas/destination_node_with_availability"
                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:
                      $ref: "#/components/schemas/exporter_node_with_availability"
                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:
                      $ref: "#/components/schemas/importer_node_with_availability"
                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:
                      $ref: "#/components/schemas/attribute_with_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/source_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."
      parameters:
        - $ref: "#/components/parameters/country_opt"
        - $ref: "#/components/parameters/commodity_opt"
      summary: List of node types as they appear in flow paths
  /top_nodes/sources:
    get:
      tags:
        - NEW
      responses:
        "200":
          description: ""
          content:
            text/html; charset=utf-8:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: array
                      items:
                        $ref: "#/components/schemas/top_place"
                  meta:
                    type: object
                    properties:
                      country:
                        $ref: "#/components/schemas/country"
                      commodity:
                        $ref: "#/components/schemas/commodity"
                      attribute:
                        $ref: "#/components/schemas/attribute"
                      total:
                        $ref: "#/components/schemas/total"
                      node_type:
                        $ref: "#/components/schemas/source_node_type"
                      nodes:
                        type: array
                        items:
                          $ref: "#/components/schemas/exporter_node"
                      start_year:
                        type: integer
                        example: 2003
                      end_year:
                        type: integer
                        example: 2017
                      n:
                        type: integer
                        example: 10
                required:
                  - data
                  - meta
      parameters:
        - $ref: "#/components/parameters/country_req"
        - $ref: "#/components/parameters/commodity_req"
        - $ref: "#/components/parameters/attribute_with_default"
        - $ref: "#/components/parameters/source_node_type_with_default"
        - $ref: "#/components/parameters/nodes_ids"
        - $ref: "#/components/parameters/start_year_with_default"
        - $ref: "#/components/parameters/end_year_with_default"
        - $ref: "#/components/parameters/n"
      description: "List of sourcing places for country - commodity combination ordered by total value of flow attribute."
      summary: List of sourcing places for country - commodity combination ordered by total value of flow attribute.
  /top_nodes/exporters:
    get:
      tags:
        - NEW
      responses:
        "200":
          description: ""
          content:
            text/html; charset=utf-8:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: array
                      items:
                        $ref: "#/components/schemas/top_trader"
                  meta:
                    type: object
                    properties:
                      country:
                        $ref: "#/components/schemas/country"
                      commodity:
                        $ref: "#/components/schemas/commodity"
                      attribute:
                        $ref: "#/components/schemas/attribute"
                      total:
                        $ref: "#/components/schemas/total"
                      node_type:
                        $ref: "#/components/schemas/exporter_node_type"
                      nodes:
                        type: array
                        items:
                          $ref: "#/components/schemas/source_node"
                      start_year:
                        type: integer
                        example: 2003
                      end_year:
                        type: integer
                        example: 2017
                      n:
                        type: integer
                        example: 10
                required:
                  - data
                  - meta
      parameters:
        - $ref: "#/components/parameters/country_req"
        - $ref: "#/components/parameters/commodity_req"
        - $ref: "#/components/parameters/attribute_with_default"
        - $ref: "#/components/parameters/exporter_node_type_with_default"
        - $ref: "#/components/parameters/nodes_ids"
        - $ref: "#/components/parameters/start_year_with_default"
        - $ref: "#/components/parameters/end_year_with_default"
        - $ref: "#/components/parameters/n"
      description: "List of exporters for country - commodity combination ordered by total value of flow attribute."
      summary: List of exporters for country - commodity combination ordered by total value of flow attribute.
  /top_nodes/importers:
    get:
      tags:
        - NEW
      responses:
        "200":
          description: ""
          content:
            text/html; charset=utf-8:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: array
                      items:
                        $ref: "#/components/schemas/top_trader"
                  meta:
                    type: object
                    properties:
                      country:
                        $ref: "#/components/schemas/country"
                      commodity:
                        $ref: "#/components/schemas/commodity"
                      attribute:
                        $ref: "#/components/schemas/attribute"
                      total:
                        $ref: "#/components/schemas/total"
                      node_type:
                        $ref: "#/components/schemas/importer_node_type"
                      nodes:
                        type: array
                        items:
                          $ref: "#/components/schemas/destination_node"
                      start_year:
                        type: integer
                        example: 2003
                      end_year:
                        type: integer
                        example: 2017
                      n:
                        type: integer
                        example: 10
                required:
                  - data
                  - meta
      parameters:
        - $ref: "#/components/parameters/country_req"
        - $ref: "#/components/parameters/commodity_req"
        - $ref: "#/components/parameters/attribute_with_default"
        - $ref: "#/components/parameters/importer_node_type_with_default"
        - $ref: "#/components/parameters/nodes_ids"
        - $ref: "#/components/parameters/start_year_with_default"
        - $ref: "#/components/parameters/end_year_with_default"
        - $ref: "#/components/parameters/n"
      description: "List of importers for country - commodity combination ordered by total value of flow attribute."
      summary: List of importers for country - commodity combination ordered by total value of flow attribute.
  /top_nodes/destinations:
    get:
      tags:
        - NEW
      responses:
        "200":
          description: ""
          content:
            text/html; charset=utf-8:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: array
                      items:
                        $ref: "#/components/schemas/top_place"
                  meta:
                    type: object
                    properties:
                      country:
                        $ref: "#/components/schemas/country"
                      commodity:
                        $ref: "#/components/schemas/commodity"
                      attribute:
                        $ref: "#/components/schemas/attribute"
                      total:
                        $ref: "#/components/schemas/total"
                      node_type:
                        $ref: "#/components/schemas/destination_node_type"
                      nodes:
                        type: array
                        items:
                          $ref: "#/components/schemas/importer_node"
                      start_year:
                        type: integer
                        example: 2003
                      end_year:
                        type: integer
                        example: 2017
                      n:
                        type: integer
                        example: 10
                required:
                  - data
                  - meta
      parameters:
        - $ref: "#/components/parameters/country_req"
        - $ref: "#/components/parameters/commodity_req"
        - $ref: "#/components/parameters/attribute_with_default"
        - $ref: "#/components/parameters/destination_node_type_with_default"
        - $ref: "#/components/parameters/nodes_ids"
        - $ref: "#/components/parameters/start_year_with_default"
        - $ref: "#/components/parameters/end_year_with_default"
        - $ref: "#/components/parameters/n"
      description: "List of destination places for country - commodity combination ordered by total value of flow attribute."
      summary: List of destination places for country - commodity combination ordered by total value of flow attribute.

servers:
  - url: https://staging.trase.earth/api/public
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
    nodes_ids:
      in: query
      name: nodes_ids
      description: Comma-separated list of numeric node ids to filter flows.
      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
    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
    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

    n:
      in: query
      name: n
      description: Number of elements to return
      schema:
        type: integer
  securitySchemes:
    apikey:
      type: apiKey
      name: api_key
      in: header
      description: >-
        We could start with an api key which would allow us to restrict or track
        API traffic.

        API key gives full access to every operation an API can perform but since we won't have any create/update/delete requests it's enough for the start.
  schemas:
    node:
      type: object
      description: Single node record.
      properties:
        id:
          type: integer
        name:
          type: string
          example: SORRISO
        node_type:
          type: string
          example: MUNICIPALITY
      required:
        - id
        - name
        - node_type
    source_node:
      allOf:
        - $ref: "#/components/schemas/node"
    exporter_node:
      allOf:
        - $ref: "#/components/schemas/node" 
        - type: object
          properties:
            name:
              example: CARGILL
            node_type:
              example: EXPORTER
    importer_node:
      allOf:
        - $ref: "#/components/schemas/node" 
        - type: object
          properties:
            name:
              example: CARGILL
            node_type:
              example: IMPORTER
    destination_node:
      allOf:
        - $ref: "#/components/schemas/node" 
        - type: object
          properties:
            name:
              example: CHINA
            node_type:
              example: COUNTRY
    node_with_availability:
      allOf:
        - $ref: "#/components/schemas/node"  
        - type: object
          properties:
            availability:
              type: array
              items:
                $ref: "#/components/schemas/availability"
    source_node_with_availability:
      allOf:
        - $ref: "#/components/schemas/node_with_availability"
        - type: object
          properties:
            geoId:
              type: string
    exporter_node_with_availability:
      allOf:
        - $ref: "#/components/schemas/node_with_availability"
        - $ref: "#/components/schemas/exporter_node"
    importer_node_with_availability:
      allOf:
        - $ref: "#/components/schemas/node_with_availability"
        - $ref: "#/components/schemas/importer_node"
    destination_node_with_availability:
      allOf:
        - $ref: "#/components/schemas/source_node_with_availability"
        - $ref: "#/components/schemas/destination_node"
    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
    country_with_commodities:
      allOf:
        - $ref: "#/components/schemas/country"
        - type: object
          properties:
            commodities:
              type: array
              items:
                $ref: "#/components/schemas/commodity"
    commodity:
      type: object
      description: Single commodity record
      properties:
        id:
          type: number
          example: 1
        name:
          type: string
          example: SOY
      required:
        - id
        - name
    commodity_with_countries:
      allOf:
        - $ref: "#/components/schemas/commodity"
        - type: object
          properties:
            countries:
              type: array
              items:
                $ref: "#/components/schemas/country"
    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
    attribute_with_availability:
      allOf:
        - $ref: "#/components/schemas/attribute"
        - type: object
          properties:
            availability:
              $ref: "#/components/schemas/availability"
          required:
            - availability
    node_type:
      type: object
      description: Node type
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
        role:
          type: string
      required:
        - id
        - name
        - role
    source_node_type:
      allOf:
        - $ref: "#/components/schemas/node_type"
        - type: object
          properties:
            name:
              type: string
              example: MUNICIPALITY
            role:
              type: string
              example: source
    exporter_node_type:
      allOf:
        - $ref: "#/components/schemas/node_type"
        - type: object
          properties:
            name:
              type: string
              example: EXPORTER
            role:
              type: string
              example: exporter
    importer_node_type:
      allOf:
        - $ref: "#/components/schemas/node_type"
        - type: object
          properties:
            name:
              type: string
              example: IMPORTER
            role:
              type: string
              example: importer
    destination_node_type:
      allOf:
        - $ref: "#/components/schemas/node_type"
        - type: object
          properties:
            name:
              type: string
              example: COUNTRY
            role:
              type: string
              example: destination
    top_node:
      type: object
      description: Node object in list ordered by total value of flow attribute.
      properties:
        id:
          type: integer
        name:
          type: string
          example: SORRISO
        value:
          type: number
        height:
          type: number
    top_place:
      allOf:
        - $ref: "#/components/schemas/top_node"
        - type: object
          properties:
            geoId:
              type: string
    top_trader:
      allOf:
        - $ref: "#/components/schemas/top_node"
    total:
      type: number
      description: Total value