API Reference

Authentication

Login

• URL: /auth/login
• Method: POST
• Request Body:

{
  "username": "your_username",
  "password": "your_password"
}

• Response:

{
  "access_token": "JWT_TOKEN"
}

• Error Responses:
  • 401 Unauthorized: If the username or password is incorrect.

Include this token in the Authorization header for subsequent requests:

Authorization: Bearer JWT_TOKEN

---

Image Upload & Plant Detection

Analyze Multiple Plants

• URL: /analyze/multiple/
• Method: POST
• Request Body:
  • files (list of files): List of files containing plant data.
  • gps_coordinates (string): GPS coordinates in JSON format.

Example:

{
  "coordinates": [
    { "lat": 51.123, "lng": 4.123 },
    { "lat": 51.123, "lng": 4.123 }
  ]
}

• Authentication: Required (JWT token in the Authorization header)
• Response Model: SupplyResponseMultiple
• Response Fields:
  • images (list of objects): List of images sent by user.
    • image_uuid (string): The ID to use for any followup requests for this image specifically (this is the UUID of the image we use in our database).
    • image_name (string): The original name of the image.
    • inference_date (ISODate): The date & time of the analysis.
    • plants (list of objects): List of plants analyzed.
      • plant_id (string): The id of the plant, generated by MongoDB and converted to a string.
      • plant_name (string): The scientific name of the plant.
      • nectar_volume (int): The mean nectar volume of one flower/detection on the plant.
      • flower_count (int): The number of flowers of this plant detected in the image.
    • nectar_volume (int): The total nectar volume of all plants in the image
  • total_nectar_volume (int): The sum of the nectar volume of all plants in all images.

Example:

{
  "images": [
    {
      "image_uuid": "uuid-1",
      "image_name": "image1.jpg",
      "inference_date": "2024-06-01T10:00:00Z",
      "plants": [
        {
          "plant_id": "...",
          "plant_name": "...",
          "nectar_volume": 12,
          "flower_count": 3
        }
      ],
      "nectar_volume": 36
    }
  ],
  "total_nectar_volume": 36
}

• Error Responses:
  • 400 Bad Request:
    • If the GPS coordinates format is invalid.
    • If there are no coordinates provided.
    • If the number of coordinates doesn't match the number of images.
    • If the EXIF date of the image can't be converted.
    • If an expected key of the detected plant is missing.
    • If the nectar volume of the plant is negative.
  • 401 Unauthorized:
    • If the JWT token in the authentication header is incorrect.
  • 403 Forbidden:
    • If there was no authentication header in the request.
  • 404 Not Found:
    • If the plant with the detection id is not found.
  • 500 Internal Server Error:
    • If any unexpected exceptions occur when generating the response.

---

Analyze Single Plant

• URL: /analyze/single/
• Method: POST
• Request Body:
  • file (file): File containing plant data.
  • gps_coordinate (string): GPS coordinate in JSON format.
• Authentication: Required (JWT token in the Authorization header)
• Response Model: SupplyResponseSingle
• Response Fields:
  • image_uuid (string): The ID to use for any followup requests (like /info/detections/image_uuid) for this image specifically (this is the UUID of the image we use in our database).
  • image_name (string): The original name of the image.
  • inference_date (ISODate): The date & time of the analysis.
  • plants (list of objects): List of plants analyzed.
    • plant_id (string): The id of the plant, generated by MongoDB.
    • plant_name (string): The name of the plant.
    • nectar_volume (int): The mean nectar volume of one flower/detection on the plant.
    • flower_count (int): The number of flowers of this plant detected in the image.
  • nectar_volume (int): The total nectar volume of all plants in the image
• Error Responses:
  • 400 Bad Request:
    • If the GPS coordinates format is invalid.
    • If there are no coordinates provided.
    • If the number of coordinates doesn't match the number of images.
    • If the EXIF date of the image can't be converted.
    • If an expected key of the detected plant is missing.
    • If the nectar volume of the plant is negative.
  • 401 Unauthorized:
    • If the JWT token in the authentication header is incorrect.
  • 403 Forbidden:
    • If there was no authentication header in the request.
  • 404 Not Found:
    • If the plant with the detection id is not found.
  • 500 Internal Server Error:
    • If any unexpected exceptions occur when generating the response.

---

Detections

Get All Image Detections

• URL: /info/detections/{image_uuid}
• Method: GET
• Path Parameter:
  • image_uuid (string): The ID of the image to fetch detections for (must be a valid MongoDB ObjectId).
• Query Parameter:
  • creator_type (string, optional): Filter detections by the type of creator.
    • Accepted values: "all" (default), "original_dataset", "expert", "model".
• Authentication: Required (JWT token in the Authorization header)
• Response Model: List[ImageDetections]
• Response Fields (for each item in the list):
  • image_uuid (string): The ObjectId of the image the detections are linked to, converted to string.
  • creator (string): The username of the user.
  • creator_type (string): What role created the detection (can be 'expert', 'model', or 'original_dataset').
  • detection_date (ISODate): Timestamp of the validation.
  • detections (list of objects): List of plant detections with the following fields:
    • plant_uuid (string): The ObjectId of the detected plan, converted to string.
    • plant_name (string): =the scientific name of the detected plant.
    • detections (list of objects): Each detection includes:
      • bounding_box (object):
        • center_x (float): X-coordinate of the bounding box center (relative, 0.0–1.0).
        • center_y (float): Y-coordinate of the bounding box center (relative, 0.0–1.0).
        • width (float): Width of the bounding box (relative).
        • height (float): Height of the bounding box (relative).
      • confidence_score (float): Model's confidence in the detection (0.0–1.0).
• Error Responses:
  • 400 Bad Request:
    • If image_uuid is not a valid ObjectId.
    • If an unexpected type is used in detection processing.
  • 401 Unauthorized:
    • If the JWT token is missing or invalid.
  • 403 Forbidden:
    • If no authentication header is provided.
  • 422 Unprocessable Entity:
    • If detection data from the database fails to match the expected format.
    • If any field contains invalid values.
  • 500 Internal Server Error:
    • If any unknown or unhandled exception occurs during processing.
    • If MongoDB operations fail unexpectedly.

Get Latest Image Detections

• URL: /info/detections/latest/{image_uuid}
• Method: GET
• Path Parameter:
  • image_uuid (string): The ID of the image to fetch the latest detection for (must be a valid MongoDB ObjectId).
• Query Parameter:
  • creator_type (string, optional): Filter the most recent detection by creator type.
    • Accepted values:
      • "all" (default): Fetches the most recent detection regardless of creator type.
      • "original dataset"
      • "expert"
      • "model"
• Authentication: Required (JWT token in the Authorization header)
• Response Model: ImageDetections
• Response Fields:
  • image_uuid (string): The ObjectId of the image, converted to string.
  • creator (string): The user or system that submitted the detection.
  • creator_type (string): Type of the creator: "original dataset", "expert", or "model".
  • detection_date (ISODate): Timestamp of when the detection was made.
  • plants (list of objects): Each plant entry contains:
    • plant_uuid (string): The unique ID of the plant.
    • plant_name (string): The scientific name of the plant.
    • detections (list of objects): Each with:
      • bounding_box:
        • center_x (float)
        • center_y (float)
        • width (float)
        • height (float)
      • confidence_score (float): Confidence score of the detection (range: 0.0–1.0)

Example:

{
  "image_uuid": "uuid-1",
  "detections": [
    {
      "plant_name": "Plantus Exampleus",
      "detections": [
        {
          "bounding_box": {
            "center_x": 0.5,
            "center_y": 0.5,
            "width": 0.2,
            "height": 0.3
          },
          "confidence_score": 0.92
        }
      ]
    }
  ]
}

• Error Responses:
  • 400 Bad Request:
    • If image_uuid is not a valid ObjectId format.
  • 401 Unauthorized:
    • If the JWT token is missing or invalid.
  • 403 Forbidden:
    • If the request is not authenticated.
  • 404 Not Found:
    • If no detections are found for the specified image and creator type.
  • 422 Unprocessable Entity:
    • If detection data from the database fails to match the expected format.
  • 500 Internal Server Error:
    • If an unexpected error occurs during processing or MongoDB operations.

---

Validate Image Detections

Get Unvalidated Images

• URL: /validate/unvalidated/
• Method: GET
• Query Parameters:
  • limit (int): Maximum number of unvalidated images to return. Must be greater than or equal to 1. Default is 1.
• Authentication: Required (JWT token in the Authorization header)
• Response Model: List[ImageResponse]
• Response Fields:
  • images (list of objects): List of images that haven't been validated at least once.
    • image_uuid (string): The image uuid converted to a string.
    • image_name (string): The filename of the image.
    • image_source (string): The origin of the image (e.g. 'BuzzWatch', 'EWD', 'iNaturalist').
    • coordinates (object): gps coordinates of the image.
      • lat (float): latitude coordinates of the image.
      • lng (float): longitude coordinates of the image.
    • image_date (ISODate): The date and time when the image was taken.
    • validated (boolean): Whether the image has been validated.
• Error Responses:
  • 401 Unauthorized:
    • If the JWT token in the authentication header is incorrect.
  • 403 Forbidden:
    • If there was no authentication header in the request.
  • 422 Unprocessable Entity:
    • If data validation of the retrieved documents fails.
  • 500 Internal Server Error:
    • If a database error occurs.
    • If any unexpected exception occurs during processing.

---

Validate Image

• URL: /validate/single/{image_uuid}
• Method: POST
• Path Parameter:
  • image_uuid (string): The ID of the image to validate, generated by MongoDB ObjectId in string format.
• Request Body:
  • detections (string): A JSON string representing the detected plants and their boundingbox info.
• Authentication: Required (JWT token in the Authorization header)
• Response Model: ImageDetections
• Response Fields:
  • image_uuid (string): The ObjectId of the image the detections are linked to, converted to string.
  • creator (string): The username of the user.
  • creator_type (string): What role created the detection (in this case will always be 'expert').
  • detection_date (ISODate): Timestamp of the validation.
  • detections (list of objects): List of plant detections with the following fields:
    • plant_uuid (string): The ObjectId of the detected plan, converted to string.
    • plant_name (string): =the scientific name of the detected plant.
    • detections (list of objects): Each detection includes:
      • bounding_box (object):
        • center_x (float): X-coordinate of the bounding box center (relative, 0.0–1.0).
        • center_y (float): Y-coordinate of the bounding box center (relative, 0.0–1.0).
        • width (float): Width of the bounding box (relative).
        • height (float): Height of the bounding box (relative).
      • confidence_score (float): Model's confidence in the detection (0.0–1.0).
• Error Responses:
  • 400 Bad Request:
    • If detections is not valid JSON.
    • If there is a type mismatch in the detection fields.
    • If required attributes are missing.
    • If the image_uuid is not a valid MongoDB ObjectId.
  • 401 Unauthorized:
    • If the JWT token is invalid or missing.
  • 403 Forbidden:
    • If no authentication header is provided.
  • 404 Not Found:
    • If no image exists with the provided image_uuid.
  • 422 Unprocessable Entity:
    • If the detections payload fails schema validation or is missing.
  • 500 Internal Server Error:
    • If an unexpected exception occurs while validating the image.

---

Information

Get Plant Dictionary

• URL: /info/plants/dictionary/
• Method: GET
• Description:
  Retrieves a dictionary mapping scientific plant names to their corresponding UUIDs.
• Authentication: Required (JWT token in the Authorization header)
• Response Model: Dict[str, str]
• Response Fields:
  • Keys (string): Scientific name of the plant.
  • Values (string): Corresponding MongoDB ObjectId of the plant.
• Error Responses: 400 Bad Request: - If data processing fails due to a type mismatch. 401 Unauthorized: - If the JWT token is missing or invalid. 403 Forbidden: - If the request is not authenticated. 422 Unprocessable Entity: - If invalid data values are encountered in plant documents. 500 Internal Server Error: - If a database operation fails or an unexpected server error occurs.

Get Plant Info

• URL: /info/plants/{plant_id}
• Method: GET
• Path Parameter:
  • plant_id (string): The ID of the plant to fetch information for (must be a valid MongoDB ObjectId).
• Authentication: Required (JWT token in the Authorization header)
• Response Model: PlantModel
• Response Fields:
  • scientific_name (string): The scientific name of the plant.
  • latin_synonyms (List of str): List of Latin synonyms for the plant.
  • dutch_synonyms (List of str): List of Dutch synonyms for the plant.
  • source (List of str): List of sources from where we have images of this plant.
  • index_ewd (int, optional): Index for the plant in the EWD database.
  • index_iNat (int, optional): Index for the plant in the iNaturalist database.
  • count (int): The totzl amount of images for that plant.
  • taxon_id (int): The taxon ID associated with the plant.
  • ancestry (string, optional): The ancestry information for the plant.
  • rank (object): The rank of the plant.
    • rank_level (int): The rank id of the plant.
    • rank (string): The rank of the plant (e.g., species, genus).
  • growth_form (List of str): List of growth forms (e.g., herb, shrub, tree).
  • pollen_colour (List of str, optional): List of pollen colors for the plant.
  • nectar_value (int): The nectar value of the plant.
  • pollination_value (int, optional): The pollination value of the plant.
  • blooming_start (int): The start month of the blooming period.
  • blooming_end (int): The end month of the blooming period.
  • blooming_periods (List of str): List of blooming periods.
  • abundance (object):
    • duinen (int): Abundance value for dunes.
    • kempen (int): Abundance value for the Kempen region.
    • leem (int): Abundance value for the Leem region.
    • maas (int): Abundance value for the Maas region.
    • polder (int): Abundance value for the polder region.
    • zand (int): Abundance value for the zand region.
• Error Responses:
  • 400 Bad Request:
    • If the plant_id is not a valid ObjectId format.
  • 401 Unauthorized:
    • If the JWT token is missing or invalid.
  • 403 Forbidden:
    • If the request is not authenticated.
  • 404 Not Found:
    • If no plant is found with the given plant_id.
  • 422 Unprocessable Entity:
    • If the plant data fails validation.
  • 500 Internal Server Error:
    • If an unexpected error occurs during the database operation or processing

---

End-to-End API Workflow

1. Login to receive JWT token.
2. Upload image(s) and GPS data via /analyze/multiple/.
3. Receive list of image UUIDs and plant detection data.
4. For each image UUID, call /info/detections/latest/{image_id}.
5. Display image overlays and plant details in your UI.