Skip to content

agstack/OpenAgri-ReportingService

BranchesTags

Repository files navigation

Reporting Service

🇪🇺 "This service was created in the context of OpenAgri project (https://horizon-openagri.eu/). OpenAgri has received funding from the EU’s Horizon Europe research and innovation programme under Grant Agreement no. 101134083."

Description

The reporting service generates .pdf reports based on information present in datasets.
These datasets are required to conform to the OCSM (OpenAgri Common Semantic Model) as well as be JSON-LD compliant.

Roadmap

High-level next steps for the Reporting Service:

  • Implement PDF reports for irrigation fertilization
  • Integrate with additional 3rd party Open Street Maps API for satelite images
  • Update PDF reports design and tables to be more adaptive for different use cases

Requirements

  • git
  • docker
  • docker-compose

Docker version used during development: 27.0.3

Installation

There are two ways to install this service, via docker or directly from source.

Deploying from source

When deploying from source, use python 3:12.
Also, you should use a venv when doing this.

A list of libraries that are required for this service is present in the "requirements.txt" file.
This service uses FastAPI as a web framework to serve APIs, alembic for database migrations, fpdf2 for
.pdf generation, sqlalchemy for database ORM mapping and pytest for testing purposes.

Pre commit hook

When working with repo after "requirements.txt" is installed \

pip install -r requirements.txt (inside activated venv)

run:

pre-commit install

When pre-commit enabled and installed, after every commit ruff and black formatters
will be activated to resolve formatting of python files.

Deploying via docker

After installing docker you can run the following commands to run the application:

docker compose build
docker compose up

The application will be served on http://127.0.0.1:8009 (I.E. typing localhost/docs in your browser will load the swagger documentation)

Full list of APIs available you can check here

Documentation

GET

/api/v1/openagri-report/{report_id}/

Path Params

report_id

  • Type: uuid str
  • Description: UUID of the generated PDF file..

Response

Response is generated PDF file.

POST

/api/v1/openagri-report/irrigation-report/

Request Params

irrigation_id

  • Type: uudi str
  • Description: ID of irrigation operation for which PDF is generated (optional)

data

  • Type: UploadFile

  • Description: API processes the data directly to generate the report if data passed. This parameter is not required and when it is, must be provided as an UploadFile.

  • from_date

  • Type: date

  • Description: Optional date filter (from which data is filtered)

  • to_date

  • Type: date

  • Description: AOptional date filter (until which data is filtered)

  • parcel_id

  • Type: str

  • Description: Optional parcel filter.

Response

Response is uuid of generated PDF file.

POST

/api/v1/openagri-report/compost-report/

Request Params

calendar_activity_type

  • Type: str
  • Description: All Farm Calendar Observation Type values are possible as input (optional). If operation_id provided not used. (Compost Operation calendar_activity_type is used to get all Compost Operations)

operation_id

  • Type: uudi str

  • Description: ID of operation for which PDF is generated (optional)

  • from_date

  • Type: date

  • Description: Optional date filter (from which data is filtered). If operation_id provided not used.

  • to_date

  • Type: date

  • Description: Optional date filter (until which data is filtered). If operation_id provided not used.

  • parcel_id

  • Type: str

  • Description: Optional parcel filter (When operation id not used).

img.png

data

  • Type: UploadFile
  • Description: API processes the data directly to generate the report if data is passed. This parameter is not required and when it is, must be provided as an UploadFile.

Response

Response is uuid of generated PDF file.

Example usage

Compost and Irrigation Report APIs can be used with and without Gatekeeper support. If Gatekeeper is used, data file param can be ignored. When service is run without Gatekeeper data must be provided in .json file format.

/api/v1/openagri-report/animal-report/

Request Params

farm_animal_id

  • Type: uudi str
  • Description: ID of FarmAnimal record for which PDF is generated (optional)

animal_group

  • Type: Optional[str]
  • Description: The group or category the animal belongs to. This is an optional string field, and it can be left as None if not applicable.

name

  • Type: Optional[str]
  • Description: The name of the animal. It is an optional string field, and if no name is provided, it can be set to None.

parcel

  • Type: Optional[UUID4]
  • Description: A unique identifier for a parcel, represented as a UUID4. This is an optional field that can be left empty if not required.

status

  • Type: Optional[int]

  • Description: The status code associated with the animal or the transaction. It is an optional integer field. If not specified, it defaults to None.

  • from_date

  • Type: date

  • Description: Optional date filter (from which data is filtered)

  • to_date

  • Type: date

  • Description: AOptional date filter (until which data is filtered)

  • parcel_id

  • Type: str

  • Description: Optional parcel filter.

data

  • Type: UploadFile
  • Description: API processes the data directly to generate the report if data passed. This parameter is not required and when it is, must be provided as an UploadFile.

The Animal Report API can be used with or without Gatekeeper support:

With Gatekeeper: The data file parameter can be ignored. Without Gatekeeper: Data must be provided in JSON file format. If no data file is provided and Gatekeeper is not enabled, the API fetches data from an external Farm Calendar service. The request is made with the provided filters, and the system retrieves the necessary animal data.

If a valid JSON file is uploaded, the API processes the data directly to generate the report

Response

Response is uuid of generated PDF file.

POST

/api/v1/openagri-report/pesticides-report/

Request Params

pesticide_id

  • Type: uudi str
  • Description: ID of Pesticide operation for which PDF is generated (optional)

data

  • Type: UploadFile

  • Description: API processes the data directly to generate the report if data passed. This parameter is not required and when it is, must be provided as an UploadFile.

  • from_date

  • Type: date

  • Description: Optional date filter (from which data is filtered)

  • to_date

  • Type: date

  • Description: AOptional date filter (until which data is filtered)

  • parcel_id

  • Type: str

  • Description: Optional parcel filter.

Response

Response is uuid of generated PDF file.

POST

/api/v1/openagri-report/fertilization-report/

Request Params

fertilization_id

  • Type: uudi str
  • Description: ID of fert operation for which PDF is generated (optional)

data

  • Type: UploadFile

  • Description: API processes the data directly to generate the report if data passed. This parameter is not required and when it is, must be provided as an UploadFile.

  • from_date

  • Type: date

  • Description: Optional date filter (from which data is filtered)

  • to_date

  • Type: date

  • Description: AOptional date filter (until which data is filtered)

  • parcel_id

  • Type: str

  • Description: Optional parcel filter.

Response

Response is uuid of generated PDF file.

POST

/api/v1/openagri-report/standalone-observation-report/

This endpoint is intended for environments where no Farm Calendar service is available. Unlike the other endpoints, no authentication is required (no Bearer token), no Farm Calendar lookups are performed, and parcel/farm information must be supplied manually as multipart form fields. The observation payload must be a pure JSON-LD observation array (top-level [ ... ]), not the {"@graph": [...]} envelope used by the other endpoints.

The generated PDF is stored under a shared standalone/ folder (not scoped per user), and is retrieved via a dedicated unauthenticated GET endpoint (see below).

Request Params

data

  • Type: UploadFile (required)
  • Description: A JSON file whose top-level structure is an array of JSON-LD observation objects (e.g. [ {"@type": "Observation", ...}, ... ]). Each item is validated against the CropObservation schema.

title

  • Type: str
  • Description: Report title shown on the PDF (default: "Observation Report").

from_date

  • Type: date
  • Description: Optional reporting period start; only used in the header.

to_date

  • Type: date
  • Description: Optional reporting period end; only used in the header.

parcel_address

  • Type: str
  • Description: Free-text parcel address shown in the Farm Details section.

parcel_identifier

  • Type: str
  • Description: Parcel identifier shown in the Farm Details section.

parcel_area

  • Type: float
  • Description: Parcel area in m². Optional.

parcel_lat

  • Type: float
  • Description: Parcel latitude. When both parcel_lat and parcel_lng are provided, a Sentinel-2 satellite tile is embedded in the report (network permitting).

parcel_lng

  • Type: float
  • Description: Parcel longitude. See parcel_lat.

farm_name / farm_municipality / farm_administrator / farm_vat_id / farm_contact_person / farm_description

  • Type: str
  • Description: Manual farm fields displayed in the Farm Details section.

Response

Response is uuid of generated PDF file.

GET

/api/v1/openagri-report/standalone-observation-report/{report_id}/

Retrieve a previously generated standalone-observation PDF. No authentication required. Returns the PDF with status 200 when ready, or 202 while generation is still in progress.

report_id

  • Type: uuid str
  • Description: UUID returned by the standalone-observation POST.

Example usage 

# No --token needed for the standalone-observation endpoint:
python3 scripts/report_client.py --type standalone-observation \
    --file scripts/standalone_observation_data.json \
    --title "Compost B-42 Observations" \
    --from-date 2025-10-10 --to-date 2025-10-12 \
    --parcel-address "Country: GR | City: Athens | Postcode: 10000" \
    --parcel-identifier "PARCEL-B42" \
    --parcel-area 12500 \
    --parcel-lat 37.9838 --parcel-lng 23.7275 \
    --farm-name "Demo Farm" \
    --farm-municipality "Athens" \
    --farm-administrator "John Doe" \
    --farm-vat-id "EL123456789" \
    --farm-contact-person "Jane Roe" \
    --farm-description "Demonstration compost farm."

POST

/api/v1/openagri-report/field-notebook/

Generates a unified Field Notebook PDF aligned with European Field Notebook (farm diary) requirements. The report combines farm/parcel information, a forecasting pest-risk summary, and all agronomic activities (pest treatment, fertilization, irrigation) plus crop data and observations, in chronological order.

Requires Gatekeeper mode. Data is fetched from Farm Calendar via the proxy; requests without Gatekeeper enabled return HTTP 400.

Request Params

parcel_id

  • Type: str
  • Description: Optional parcel filter.

from_date

  • Type: date
  • Description: Optional date filter (from which data is filtered).

to_date

  • Type: date
  • Description: Optional date filter (until which data is filtered).

include_irrigation

  • Type: bool
  • Description: Include the Irrigation Activities section. Defaults to true.

include_fertilization

  • Type: bool
  • Description: Include the Fertilization Activities section. Defaults to true.

include_pesticides

  • Type: bool
  • Description: Include the Pest Treatment Activities section. Defaults to true.

include_observations

  • Type: bool
  • Description: Include the Crop Data & Observations section. Defaults to true.

certification

  • Type: QualityCertification (optional request body)
  • Description: Optional quality certification details rendered in the observations section. Fields (all optional): cert_type, cert_number, cert_issuing_body, cert_issue_date, cert_expiry_date, cert_notes.

Response

Response is uuid of generated PDF file, pollable via GET /{report_id}/.

Pytest

Pytest can be run on the same machine the service has been deployed to by moving into the app dir and running: 
pytest

This will run all tests and return success values for each api tested in the terminal.

These tests will NOT result in generated .pdf files.

Working examples

You can find working examples for animal, irrigation, compost, pesticides, fertilization and standalone-observation reports generation in the following pages:

Script

Contributing

We welcome first-time contributions!

See our Contributing Guide

You can also open an issue to discuss ideas.

Reporting Service is part of OpenAgri project, building tools for agriculture & climate data. Your contribution helps farmers and researchers.

License

This project code is licensed under the EUPL 1.2 license, see the LICENSE file for more details. Please note that each service may have different licenses, which can be found their specific source code repository.

About

The reporting service generates PDF documents that visualize agricultural data, depending on the specific data input

Topics

hacktoberfest

Resources

Readme

License

EUPL-1.2 license
Activity
Custom properties

Stars

7 stars

Watchers

2 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages