query-api.yaml

openapi: 3.0.0
info:
  title: web map api
  version: '1.0'
  description: 'The information API of Greenstand for web map client, wallet app or others'
  contact:
    name: Greenstand Web Map API
    url: 'http://env.treetracker.org/web-map-api'
servers:
  - url: 'http://env.treetracker.org/web-map-api'
paths:
  '/trees/{treeId}.':
    parameters:
      - schema:
          type: string
        name: treeId
        in: path
        required: true
    get:
      summary: get tree info
      tags: []
      operationId: trees-treeId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tree'
      description: get single tree object by tree id
  /trees:
    parameters: []
    get:
      summary: get tree list by query parameters
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: total count of trees satifiying the query condition
                  trees:
                    type: array
                    items:
                      $ref: '#/components/schemas/tree'
                  offset:
                    type: integer
                  limit:
                    type: integer
      operationId: trees
      description: |-
        query trees by filters like planter, also consider pagination
        I think filter all tree by `active = true` is by default
      parameters:
        - schema:
            type: integer
          in: query
          name: offset
          description: 'The start offset of the list, if missing, default is 0'
        - schema:
            type: integer
            maximum: 1000
            minimum: 0
          in: query
          name: limit
          description: 'The limit length of the return list, if missing, default is 20'
        - schema:
            type: integer
          in: query
          name: planter_id
          description: Filter by planter id
        - schema:
            type: integer
          in: query
          name: organization_id
          description: Filter by org id
        - schema:
            type: string
          in: query
          name: startDate & endDate
          description: Filter by date range
        - schema:
            type: string
          in: query
          name: tag
          description: Filter by tag names
        - schema:
            type: string
          in: query
          name: order_by
  /trees/featured:
    get:
      summary: get featured tree list
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  total:
                    type: number
                  trees:
                    type: array
                    items:
                      $ref: '#/components/schemas/tree'
      operationId: get-trees-featured
      description: |-
        this is some good trees bookmarked by admin, short term we will consider using a static table/file to pick up and store these tree id somewhere.

        The use case for this is that on the welcome page of web map site, we want to show a gallery of beautiful trees.
  '/v2/captures/{captureId}.':
    parameters:
      - schema:
          type: string
        name: captureId
        in: path
        required: true
    get:
      summary: get capture info
      tags: []
      operationId: captures-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/capture'
      description: get single capture object by id
  /v2/captures:
    parameters: []
    get:
      summary: get capture list by query parameters
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  captures:
                    type: array
                    items:
                      $ref: '#/components/schemas/capture'
                  total:
                    type: integer
                    description: total count of captures satifiying the query condition
                  offset:
                    type: integer
                  limit:
                    type: integer
      operationId: captures
      description: |-
        query captures by filters like grower_account_id, device_identifier, or species_id, also consider pagination. Filter all captures by `status=active` and exclude deleted
      parameters:
        - schema:
            type: integer
          in: query
          name: offset
          description: 'The start offset of the list, if missing, default is 0'
        - schema:
            type: integer
            maximum: 1000
            minimum: 0
          in: query
          name: limit
          description: 'The limit length of the return list, if missing, default is 25'
        - schema:
            type: string
          in: query
          name: grower_account_id
          description: Filter by grower_account_id
        - schema:
            type: array
            items:
              type: string
              format: uuid
          in: query
          name: organization_ids
          description: Filter by org id(s)
        - schema:
            type: string
          in: query
          name: startDate
          description: Filter by date range
        - schema:
            type: string
          in: query
          name: endDate
          description: Filter by date range
        - schema:
            type: string
          in: query
          name: tag
          description: Filter by tag name
        - schema:
            type: string
          in: query
          name: id
          description: Filter by id of capture
        - schema:
            type: string
          in: query
          name: tree_id
          description: Filter by tree_id
        - schema:
            type: string
          in: query
          name: species_id
          description: Filter by species_id
        - schema:
            type: string
          in: query
          name: device_identifier
          description: Filter by device_identifier
        - schema:
            type: string
          in: query
          name: wallet
          description: Filter by wallet's name value
        - schema:
            type: string
          in: query
          name: token
          description: Filter by token's id
        - schema:
            type: string
          in: query
          name: status
          description: Filter by status, only 'status=active'
        - schema:
            type: string
          in: query
          name: sort
          description: Sort by order and order_by values
  /v2/grower_accounts/{grower_account_id}:
    parameters:
      - schema:
          type: string
        name: grower_account_id
        in: path
        required: true
    get:
      summary: get grower account info
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grower_account'
  /v2/trees/{tree_id}:
    parameters:
      - schema:
          type: string
        name: tree_id
        in: path
        required: true
    get:
      summary: get tree
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tree'
  /v2/trees/{tree_id}/captures:
    parameters:
      - schema:
          type: string
        name: tree_id
        in: path
        required: true
    get:
      summary: get capture
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  captures:
                    type: array
                    description: the captures of a tree
                    items:
                      $ref: '#/components/schemas/capture'
  /v2/stakeholder/{stakeholder_id}:
    parameters:
      - schema:
          type: string
        name: stakeholder_id
        in: path
        required: true
    get:
      summary: get stakeholder info
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stakeholder'
  '/raw_captures/{rawCaptureId}.':
    parameters:
      - schema:
          type: string
        name: rawCaptureId
        in: path
        required: true
    get:
      summary: get raw-capture info
      tags: []
      operationId: raw-captures-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/field_data'
      description: get single capture object by id
  /raw_captures:
    parameters: []
    get:
      summary: get capture list by query parameters
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  captures:
                    type: array
                    items:
                      $ref: '#/components/schemas/field_data'
                  total:
                    type: integer
                    description: total count of raw-captures satifiying the query condition
                  offset:
                    type: integer
                  limit:
                    type: integer
      operationId: raw-captures
      description: |-
        query raw-captures (field_data) by filters like grower_account_id, device_identifier, or species_id, also consider pagination. Filter all raw-captures by `status=unprocessed` and exclude deleted by default
      parameters:
        - schema:
            type: integer
          in: query
          name: offset
          description: 'The start offset of the list, if missing, default is 0'
        - schema:
            type: integer
            maximum: 1000
            minimum: 0
          in: query
          name: limit
          description: 'The limit length of the return list, if missing, default is 25'
        - schema:
            type: string
          in: query
          name: grower_account_id
          description: Filter by grower_account_id
        - schema:
            type: array
            items:
              type: string
              format: uuid
          in: query
          name: organization_ids
          description: Filter by org id(s)
        - schema:
            type: integer
          in: query
          name: reference_id
          description: Filter by legacy tree id
        - schema:
            type: string
          in: query
          name: startDate
          description: Filter by date range
        - schema:
            type: string
          in: query
          name: endDate
          description: Filter by date range
        - schema:
            type: string
          in: query
          name: tag
          description: Filter by tag name
        - schema:
            type: string
          in: query
          name: id
          description: Filter by id of capture
        - schema:
            type: string
          in: query
          name: tree_id
          description: Filter by tree_id
        - schema:
            type: string
          in: query
          name: species_id
          description: Filter by species_id
        - schema:
            type: string
          in: query
          name: device_identifier
          description: Filter by device_identifier
        - schema:
            type: string
          in: query
          name: wallet
          description: Filter by wallet's name value
        - schema:
            type: string
          in: query
          name: token
          description: Filter by token's id
        - schema:
            type: string
          in: query
          name: status
          description: Filter by status, only 'unprocessed', 'approved', or 'rejected'
        - schema:
            type: string
          in: query
          name: sort
          description: Sort by order and order_by values
  /countries/leaderboard:
    get:
      summary: leader board of country
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  total:
                    type: number
                  countries:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        name:
                          type: string
                        count:
                          type: integer
                          description: the count of planted tree in this country
      operationId: get-countries-leader
      description: |-
        Top planting-tree countries (leader board), we will show the leader board on the welcome page of web map site. we can query the DB with SQL like this (provided by Seb):
        ```
        SELECT
          count(trees.*),region.name
        FROM
          trees
        RIGHT JOIN region ON
        st_contains(region.geom,trees.estimated_geometric_location)
        where region.type_id = 10
        group by region.name;
        ```

        But it's slow so seba and I consider pre-query the db and store the result somewhere.
    parameters: []
  /countries:
    get:
      summary: get countries by coordinates
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    total: 1
                    countries: []
                properties:
                  total:
                    type: number
                    description: total result of countries
                  countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/country'
                required:
                  - total
                  - countries
      operationId: get-countries
      description: |
        get country by coordinates, currently, we use it to get the country name of a tree/location.
        if given the 'lat' and 'lon', we can query db by SQL:
        ```
        SELECT region.* FROM region, region_type
        WHERE region.type_id = region_type.id
        AND ST_Contains(region.geom, ST_GeomFromText('POINT (-13.215865333333333 8.34645033333333)',4326))
        AND  region_type.id = region.type_id AND region_type.type = 'country'
        ```
      parameters:
        - schema:
            type: number
          in: query
          name: lat
          description: the latitude of the location
        - schema:
            type: number
          in: query
          name: lon
          description: the longitude of the location
    parameters: []
  '/countries/{countryId}':
    get:
      summary: get one country
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  total:
                    type: number
                    description: total result of countries
                  countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/country'
      operationId: get-country-by-id
      description: |-
        get country by id, in some case I use this to fetch the center point and move the map view to go to country

        I suppose the countryId is the key of table `region` and type_id = 'country'

        No need to return get big column like metadata and multipolygon
      parameters:
        - schema:
            type: number
          in: query
          name: lat
          description: the latitude of the location
        - schema:
            type: number
          in: query
          name: lon
          description: the longitude of the location
    parameters:
      - schema:
          type: string
        name: countryId
        in: path
        required: true
  '/planters/{planterId}':
    parameters:
      - schema:
          type: string
        name: planterId
        in: path
        required: true
    get:
      summary: get planter by id
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/planter'
      operationId: get-planters-planterId
      description: |-
        get planter object by id

        'about' property: Seba says he might be able to populate this field, may be manually in the early stage
        'location?' property: I don't know if we can provide this infomation, the city/country of the planter, could be removed if impossible
  /planters:
    get:
      summary: get planter list by query parameter
      operationId: get-planters
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  planters:
                    type: array
                    items:
                      $ref: '#/components/schemas/planter'
      description: ''
      parameters:
        - schema:
            type: integer
          in: query
          name: offset
          description: 'The start offset of the list, if missing, default is 0'
        - schema:
            type: integer
            minimum: -15
            maximum: 1000
          in: query
          name: limit
          description: 'The limit length of the return list, if missing, default is 20'
        - schema:
            type: integer
          in: query
          name: organization_id
          description: Filter by org id
        - schema:
            type: string
          in: query
          name: keyword
          description: Filter by keyword
  '/organizations/{orgId}':
    parameters:
      - schema:
          type: string
        name: orgId
        in: path
        required: true
    get:
      summary: get organization by id
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/organization'
      operationId: get-organizations-orgId
      description: |-
        Ge organization by id

        about some fields:
        'photo_url' property:kind of like a cover photo, Seb says he will find a way to populate it, maybe manually in ealy stage

        'location?': I don't know if we can provide this infomation, the city/country of the org, could be removed if impossible

        'about':Seba says he might be able to populate this field, may be manually in the early stage

        mission: Seba says he might be able to populate this field, may be manually in the early stage
  /organizations:
    get:
      summary: get organization list by query parameters
      parameters:
        - schema:
            type: integer
          in: query
          name: offset
          description: 'The start offset of the list, if missing, default is 0'
        - schema:
            type: integer
            minimum: -15
            maximum: 1000
          in: query
          name: limit
          description: 'The limit length of the return list, if missing, default is 20'
        - schema:
            type: integer
          in: query
          name: grower_account_id
          description: Filter by grower_account_id
        - schema:
            type: string
          in: query
          name: planter_id
          description: Filter by planter id

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  organizations:
                    type: array
                    items:
                      $ref: '#/components/schemas/organization'
  /species:
    get:
      summary: get species list by filter/parameters
      operationId: get-species
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  species:
                    type: array
                    items:
                      $ref: '#/components/schemas/species'
      parameters:
        - schema:
            type: integer
          in: query
          name: offset
          description: 'The start offset of the list, if missing, default is 0'
        - schema:
            type: integer
            minimum: -15
            maximum: 1000
          in: query
          name: limit
          description: 'The limit length of the return list, if missing, default is 20'
        - schema:
            type: integer
          in: query
          name: organization_id
          description: Filter by org id
        - schema:
            type: string
          in: query
          name: grower_account_id
          description: Filter by planter id
      description: "mainly if we can provide this endpoint, then we can display a species list on org or planter page, but I don't know if it is too resource consumming to query DB"
  /transactions:
    get:
      summary: get token transaction list by filter/parameters
      operationId: get-transactions
      description: "about returning wallet name, it is a pretty common use case that we need to display the wallet name in the frontend, so we'd better join and return the name of wallet"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/transaction'
      parameters:
        - schema:
            type: integer
          in: query
          name: offset
          description: 'The start offset of the list, if missing, default is 0'
        - schema:
            type: integer
            minimum: -15
            maximum: 1000
          in: query
          name: limit
          description: 'The limit length of the return list, if missing, default is 20'
        - schema:
            type: string
          in: query
          name: token_id
          description: Filter by token id
        - schema:
            type: string
          in: query
          name: wallet_id
          description: Filter by wallet id
  '/tokens/{tokenId}':
    parameters:
      - schema:
          type: string
        name: tokenId
        in: path
        required: true
    get:
      summary: get token by id
      operationId: get-tokens-tokenId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token'
  /tokens:
    get:
      summary: get token list by filter/parameters
      operationId: get-tokens
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  tokens:
                    type: array
                    items:
                      $ref: '#/components/schemas/token'
      parameters:
        - schema:
            type: integer
          in: query
          name: offset
          description: 'The start offset of the list, if missing, default is 0'
        - schema:
            type: integer
            minimum: -15
            maximum: 1000
          in: query
          name: limit
          description: 'The limit length of the return list, if missing, default is 20'
        - schema:
            type: string
          in: query
          name: wallet
          description: 'Filter by wallet, the value can be wallet name or wallet id'
        - schema:
            type: boolean
          in: query
          name: withCapture
          description: "if we need show a token list, it's usually we need display the tree linked to the token, and the planter info, and I think make this configurable might be better, so I add this switcher"
        - schema:
            type: boolean
          in: query
          name: withPlanter
          description: "if we need show a token list, it's usually we need display the tree linked to the token, and the planter info, and I think make this configurable might be better, so I add this switcher"
      description: ''
  '/wallets/{walletIdOrName}':
    parameters:
      - schema:
          type: string
        name: walletIdOrName
        in: path
        required: true
    get:
      summary: get wallet by id or name
      operationId: get-wallets-walletIdOrName
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wallet'
      description: 'about retunning photo_url,it would be great if we can set a wallet avatar and show it on the wallet page, maybe we can create the column, and just pick some good case to manualy fill some photo into'
  /gis/location/nearest:
    get:
      summary: get nearest gis location by filter/parameters
      operationId: get-gis-location-nearest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location'
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 18
          in: query
          name: zoomlevel
          description: the map zoomlevel
        - schema:
            type: number
          in: query
          name: lat
          description: the latitude
        - schema:
            type: number
          in: query
          name: lon
          description: the longitude
  /gis/bounds:
    get:
      summary: get gis bounds by filter/parameters, e.g. give a planter id, get a bounds which contains all the trees in the planter
      operationId: get-gis-bounds
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bounds'
      parameters:
        - schema:
            type: string
          in: query
          name: planter
          description: get the bounds by the planter id
        - schema:
            type: string
          in: query
          name: wallet
          description: get the bounds by the wallet id or name
        - schema:
            type: string
          in: query
          name: organization
          description: get the bounds by the organization id
  /mock/trees/query/planter_id=940&limit=4:
    get:
      responses:
        '200':
          description: OK, Returns a list of trees associated with the specified planter ID, limited by the 'limit' parameter.
          content:
            application/json:
              examples:
                trees:
                  value:
                    total: 20
                    trees:
                      - $ref: examples/trees/186734.json
                      - $ref: examples/trees/186735.json
                      - $ref: examples/trees/186736.json
                      - $ref: examples/trees/186737.json
  /mock/trees/query/organization_id=1&limit=4:
    get:
      responses:
        '200':
          description: OK, Returns a list of trees associated with the specified organization ID, limited by the 'limit' parameter.
          content:
            application/json:
              examples:
                trees:
                  value:
                    total: 200
                    trees:
                      - $ref: examples/trees/186734.json
                      - $ref: examples/trees/186735.json
                      - $ref: examples/trees/186736.json
                      - $ref: examples/trees/186737.json
  /mock/trees/933042:
    get:
      responses:
        '200':
          description: Returns detailed information about a tree associated with the specified tree id
          content:
            application/json:
              examples:
                a-tree:
                  $ref: '#/components/examples/tree933042'
  /mock/trees/932946:
    get:
      responses:
        '200':
          description: Returns detailed information about a tree associated with the specified tree id
          content:
            application/json:
              examples:
                a-tree:
                  $ref: '#/components/examples/tree932946'
  /mock/trees/186734:
    get:
      responses:
        '200':
          description: Returns detailed information about a tree associated with the specified tree id
          content:
            application/json:
              example:
                $ref: examples/trees/186734.json
  /mock/trees/186735:
    get:
      responses:
        '200':
          description: Returns detailed information about a tree associated with the specified tree id
          content:
            application/json:
              example:
                $ref: examples/trees/186735.json
  /mock/trees/186736:
    get:
      responses:
        '200':
          description: Returns detailed information about a tree associated with the specified tree id
          content:
            application/json:
              example:
                $ref: examples/trees/186736.json
  /mock/trees/186737:
    get:
      responses:
        '200':
          description: Returns detailed information about a tree associated with the specified tree id
          content:
            application/json:
              example:
                $ref: examples/trees/186737.json
  /mock/trees/featured:
    get:
      responses:
        '200':
          description: Returns featured tree list
          content:
            application/json:
              examples:
                trees:
                  value:
                    trees:
                      - $ref: examples/trees/186734.json
                      - $ref: examples/trees/186735.json
                      - $ref: examples/trees/186736.json
                      - $ref: examples/trees/186737.json
  /mock/countries/leader:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              example:
                $ref: examples/countries/leader.json
  /mock/countries/6632544:
    get:
      responses:
        '200':
          description: Returns detailed information of a country associated with the specified country id
          content:
            application/json:
              example:
                $ref: examples/countries/6632544.json
  /mock/countries/6632386:
    get:
      responses:
        '200':
          description: Returns detailed information of a country associated with the specified country id
          content:
            application/json:
              example:
                $ref: examples/countries/6632386.json
  /mock/countries/6632375:
    get:
      responses:
        '200':
          description: Returns detailed information of a country associated with the specified country id
          content:
            application/json:
              example:
                $ref: examples/countries/6632375.json
  /mock/countries/6632357:
    get:
      responses:
        '200':
          description: Returns detailed information of a country associated with the specified country id
          content:
            application/json:
              example:
                $ref: examples/countries/6632357.json
  /mock/planters/5:
    get:
      responses:
        '200':
          description: Returns detailed information of a planter associated with the specified planter id
          content:
            application/json:
              examples:
                a-planter:
                  $ref: '#/components/examples/planter5'
  /mock/planters/940:
    get:
      responses:
        '200':
          description: Returns detailed information of a planter associated with the specified planter id
          content:
            application/json:
              example:
                $ref: examples/planters/940.json
  /mock/planters/query/organization_id=1&limit=4:
    get:
      responses:
        '200':
          description: Returns a list of planters associated with a specific organization, limited by the specified count.
          content:
            application/json:
              examples:
                organizations:
                  value:
                    total: 20
                    planters:
                      - $ref: examples/planters/940.json
  /mock/organizations/query/planter_id=940:
    get:
      responses:
        '200':
          description: Returns the organizations associated with a specified planter ID.
          content:
            application/json:
              examples:
                organizations:
                  value:
                    total: 2
                    organizations:
                      - $ref: examples/organizations/1.json
  /mock/organizations/1:
    get:
      responses:
        '200':
          description: Returns detailed information about a specific organization identified by its ID
          content:
            application/json:
              example:
                $ref: examples/organizations/1.json
  /mock/species/query/planter_id=940:
    get:
      responses:
        '200':
          description: Returns a list of species associated with a specific planter
          content:
            application/json:
              examples:
                species:
                  value:
                    total: 2
                    species:
                      - $ref: examples/species/1.json
                      - $ref: examples/species/2.json
  /mock/species/query/organization_id=1:
    get:
      responses:
        '200':
          description: Returns a list of species associated with a specific organization_id
          content:
            application/json:
              examples:
                species:
                  value:
                    total: 20
                    species:
                      - $ref: examples/species/1.json
                      - $ref: examples/species/2.json
  /mock/transactions/query/token=1:
    get:
      responses:
        '200':
          description: Returns a list of transactions associated with a specific token ID
          content:
            application/json:
              examples:
                transactions:
                  value:
                    total: 3
                    transactions:
                      - $ref: examples/transactions/1.json
                      - $ref: examples/transactions/2.json
  /mock/tokens/query/wallet=180Earth&withPlanter=true&withCapture=true:
    get:
      responses:
        '200':
          description: Returns tokens associated with a specific wallet, optionally including related planter and capture details.
          content:
            application/json:
              examples:
                tokens:
                  value:
                    total: 1
                    tokens:
                      - $ref: examples/tokens/1.json
                      - $ref: examples/tokens/2.json
                      - $ref: examples/tokens/3.json
                      - $ref: examples/tokens/4.json
  /mock/tokens/1:
    get:
      responses:
        '200':
          description: Returns tokens associated with a specific id
          content:
            application/json:
              example:
                $ref: examples/tokens/1.json
  /mock/tokens/2:
    get:
      responses:
        '200':
          description: Returns tokens associated with a specific id
          content:
            application/json:
              example:
                $ref: examples/tokens/2.json
  /mock/tokens/3:
    get:
      responses:
        '200':
          description: Returns tokens associated with a specific id
          content:
            application/json:
              example:
                $ref: examples/tokens/3.json
  /mock/tokens/4:
    get:
      responses:
        '200':
          description: Returns tokens associated with a specific id
          content:
            application/json:
              example:
                $ref: examples/tokens/4.json
  /mock/wallets/180Earth:
    get:
      responses:
        '200':
          description: Returns tokens associated with a specific name
          content:
            application/json:
              example:
                $ref: examples/wallets/180Earth.json
components:
  schemas:
    location:
      description: A location point
      type: object
      properties:
        centroid:
          type: string
          description: The center of the location
        'type':
          type: string
          enum:
            - tree
            - cluster
          description: The type of location
        count:
          type: integer
          description: The number of trees in the location, just available for clusters
    bounds:
      description: A bounding box
      type: object
      properties:
        bounds:
          type: array
          items:
            type: array
            items:
              type: number
            minItems: 2
            maxItems: 2
          minItems: 2
          maxItems: 2
          description: 2 points defining the bounding box
    tree:
      description: A single tree object
      type: object
      x-examples: {}
      title: ''
      properties:
        id:
          type: number
        latest_capture_id:
          type: number
        image_url:
          type: string
        lat:
          type: number
        lon:
          type: number
        estimated_geometric_location:
          type: string
        gps_accuracy:
          type: number
        morphology:
          type: string
        age:
          type: number
        created_at:
          type: string
        updated_at:
          type: string
        estimated_geographic_location:
          type: string
        status:
          type: string
        attributes:
          type: string
        species_id:
          type: number
        species_name:
          type: string
        species_description:
          type: string
        country_name:
          type: string
    country:
      description: ''
      type: object
      x-examples: {}
      properties:
        id:
          type: number
        name:
          type: string
          description: the name of the country
        centroid:
          type: string
          description: like POINT (-13.215865333333333 8.34645033333333)
    planter:
      description: the planter ojbect
      type: object
      x-examples: {}
      properties:
        id:
          type: number
        photo_url:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        about:
          type: string
          description: 'Seba says he might be able to populate this field, may be manually in the early stage'
        created_at:
          type: string
        location?:
          type: string
          description: "I don't know if we can provide this infomation, the city/country of the planter, could be removed if impossible"
        links:
          type: object
          properties:
            featured_trees:
              type: string
              description: |-
                Try HATEOAS here, in the app I'm using:
                /trees?planter_id=940&limit=4
            associated_organizations:
              type: string
              description: |-
                Try HATEOAS here, in the app I'm using:
                /organizations?planter_id=940
            species:
              type: string
              description: |-
                Try HATEOAS here, in the app I'm using:
                /species?planter_id=940
    organization:
      description: ''
      type: object
      x-examples:
        example-org:
          id: 1
          name: 180Earth
          photo_url: 'https://180.earth/wp-content/uploads/2020/01/Asset-1.png'
          location: 'Shirimatunda, Tanzania'
          created_at: 'November 11, 2019'
          about: 'Greenway is a Youth-Driven Environmental Protection Organization providing alternative solutions to single-use plastic and planting carbon-sucking trees for socio-economic development and reducing climate crisis. Our social work includes reforestation, landscape restoration, climate education, awareness campaign, conducting research, outreach activities, and collaborating with key stakeholders to implement sustainable solutions.'
          mission: 'To combat climate change, desertification, land degradation, carbon emission by inspiring healthier communities affected by severe climate disorder and modestly reducing pollution by 2050.'
      properties:
        id:
          type: number
        name:
          type: string
        logo_url:
          type: string
        photo_url:
          type: string
          description: 'kind of like a cover photo, Seb says he will find a way to populate it, maybe manually in ealy stage'
        location?:
          type: string
          description: "I don't know if we can provide this infomation, the city/country of the org, could be removed if impossible"
        created_at:
          type: string
        about:
          type: string
          description: 'Seba says he might be able to populate this field, may be manually in the early stage'
        mission:
          type: string
          description: 'Seba says he might be able to populate this field, may be manually in the early stage'
        links:
          type: object
          properties:
            featured_trees:
              type: string
              description: |-
                Try HATEOAS here, in the app I'm using:
                /trees?organization_id=1&limit=4
            associated_planters:
              type: string
              description: |-
                Try HATEOAS here, in the app I'm using:
                /planters?organization_id=1&limit=4
            species:
              type: string
              description: |-
                Try HATEOAS here, in the app I'm using:
                /species?organization_id=1
    species:
      title: species
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        count:
          type: integer
          description: "It would be great if we can display how many trees in this species has been planted by org or planter, but I don't know if it is too resource consumming to query DB"
    transaction:
      description: ''
      type: object
      x-examples:
        example-1:
          id: 1
          token_id: 1
          source_wallet_id: 1
          destination_wallet_id: 2
          source_wallet_name: apple
          destination_wallet_name: orange
          processed_at: '2018-02-28'
      properties:
        id:
          type: string
        token_id:
          type: string
        source_wallet_id:
          type: string
        destination_wallet_id:
          type: string
        source_wallet_name:
          type: string
          description: "it is a pretty common use case that we need to display the wallet name in the frontend, so we'd better join and return the name of wallet"
        destination_wallet_name:
          type: string
        processed_at:
          type: string
        claim:
          type: boolean
          description: if possible
        transfer_id:
          type: string
    token:
      description: ''
      type: object
      x-examples:
        example-1:
          id: 1
          wallet_id: 0248f77a-1531-11ec-82a8-0242ac130003
          capture_id: 186734
          capture_photo_url: 'https://treetracker-dev-images.s3.eu-central-1.amazonaws.com/2020.10.19.09.50.38_-5.508172399749922_38.98146973686408_6bebe71e-5369-4ae0-8c47-9eeff6599fb0_IMG_20201019_094615_7537040365910944885.jpg'
          planter_id: 940
          planter_first_name: 'Sebastian '
          planter_last_name: Gaertner
          planter_photo_url: 'https://treetracker-dev-images.s3.eu-central-1.amazonaws.com/2020.10.19.09.47.53_-5.508107173727935_38.981361706266256_39f0cc9d-0f13-4547-8142-150f15cabb67_IMG_20201019_094513_6614320100195503436.jpg'
          created_at: '2018-01-01'
      properties:
        id:
          type: number
        wallet_id:
          type: string
        capture_id:
          type: number
        capture_photo_url:
          type: string
        planter_id:
          type: number
        planter_first_name:
          type: string
        planter_last_name:
          type: string
        planter_photo_url:
          type: string
        created_at:
          type: string
    wallet:
      description: ''
      type: object
      x-examples:
        example-1:
          id: 0248f77a-1531-11ec-82a8-0242ac130003
          name: 180Earth
          token_in_wallet: 22
          photo_url: "'https://180.earth/wp-content/uploads/2020/01/Asset-1.png"
      properties:
        id:
          type: string
        name:
          type: string
        photo_url:
          type: string
          description: it would be great if we can set a wallet avatar and show it on the wallet page
    stakeholder:
      description: ''
      type: object
      properties:
        id:
          type: number
        'type':
          type: string
        org_name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        phone:
          type: string
        website:
          type: string
        logo_url:
          type: string
        map:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
        active:
          type: boolean
        entity_id:
          type: number
    capture:
      description: A tree photo capture and its associated data package, representing a tree at a given moment in time
      type: object
      properties:
        id:
          type: number
        lat:
          type: number
        lon:
          type: number
        time_created:
          type: string
        image_url:
          type: string
        grower_id:
          type: number
        growing_organization_id:
          type: number
        token_id:
          type: number
        approved:
          type: boolean
        wallet_id:
          type: number
        wallet_name:
          type: string
    grower_account:
      description: ''
      type: object
      properties:
        id:
          type: number
          format: uuid
        wallet:
          type: string
        person_id:
          type: number
          format: uuid
          nullable: true
        organization_id:
          type: number
          format: uuid
          nullable: true
        first_name:
          type: string
        email:
          type: string
          format: email
          nullable: true
        phone:
          type: string
          nullable: true
        image_url:
          type: string
        image_rotation:
          type: number
        status:
          type: string
        first_registration_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_name:
          type: string
          nullable: true
        location:
          type: string
          description: 'The spatial location represented as geometry(Point,4326).'
          nullable: true
        lon:
          type: number
          nullable: true
        lat:
          type: number
          nullable: true
        bulk_pack_file_name:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        about:
          type: string
          nullable: true
        reference_id:
          type: number
          nullable: true
        show_in_map:
          type: boolean
        links:
          type: object
          properties:
            featured_trees:
              type: string
            associated_organizations:
              type: string
            species:
              type: string
    field_data:
      description: ''
      type: object
      properties:
        id:
          type: number
        lat:
          type: number
        lon:
          type: number
        created_at:
          type: string
        captured_at:
          type: string
        image_url:
          type: string

  examples:
    tree933042:
      value:
        id: 933042
        photo_url: 'https://treetracker-production-images.s3.eu-central-1.amazonaws.com/2021.05.19.09.49.19_-4.881696978000001_38.37997515399998_47fc629b-27e9-4b58-b31a-3a35e5bbc3f0_IMG_20210518_121452_1024002290.jpg'
        verified: true
        token_id: d4bb294b-8c75-4e0f-af43-1cd9a35e1033
        impact_manager_id: 8599f832-145e-11ec-82a8-0242ac130003
        impact_producer_id: a0b6b70e-145e-11ec-82a8-0242ac130003
        created_at: '5/18/2021, 5:14:48 PM'
        lat: -4.881696978000001
        lon: 38.37997515399998
        species: Markhamia lutea
        planter_id: 5
    tree932946:
      value:
        id: 932946
        photo_url: 'https://treetracker-production-images.s3.eu-central-1.amazonaws.com/2021.05.11.18.37.00_-4.91963284_38.52757506_adc35f9c-b76e-4798-b587-70f5fba06b89_IMG_20210511_101502_-1595081185.jpg'
        verified: true
        token_id: c488301f-1117-48c3-8866-3c38f28d3f25
        created_at: '5/17/2021, 9:31:17 PM'
        lat: -4.882294219999999
        lon: 38.380733454
        species: eucalyptus
        planter_id: 5
        organization_id: 1
    planter5:
      value:
        id: 5
        photo_url: 'https://treetracker-production-images.s3.eu-central-1.amazonaws.com/2021.05.11.18.37.00_-4.91963284_38.52757506_adc35f9c-b76e-4798-b587-70f5fba06b89_IMG_20210511_101502_-1595081185.jpg'
        name: Issa H
    org1:
      value:
        id: 1
        name: 180Earth
        photo_url: 'https://180.earth/wp-content/uploads/2020/01/Asset-1.png'
        area: Shirimatunda
        country: Tanzania
        created_at: 'November 11, 2019'
        about: 'Greenway is a Youth-Driven Environmental Protection Organization providing alternative solutions to single-use plastic and planting carbon-sucking trees for socio-economic development and reducing climate crisis. Our social work includes reforestation, landscape restoration, climate education, awareness campaign, conducting research, outreach activities, and collaborating with key stakeholders to implement sustainable solutions.'
        mission: 'To combat climate change, desertification, land degradation, carbon emission by inspiring healthier communities affected by severe climate disorder and modestly reducing pollution by 2050.'