Feeding

The feeding endpoints expose specific feed rate (SFR) analytics for benchmarking sites and farmer groups in AquaCloud. All routes are read-only GET endpoints under the /v3/feeding prefix and share the same authentication model as the other v3 resources: send an Authorization: Bearer <token> header and, for non-premium farmers, include the x-client-secret header issued for your integration.

A successful call returns a JSON payload with a data array, optional pagination object, and metadata describing the request. When no records match the filters the API responds with 204 No Content.

Common query parameters

Name	Type	Default	Details
from_date	date	Today − 4 weeks	Flexible date parsing (ISO, 31/01/2024, mai 2024, week 34 2024, today, etc.). When partially specified, the first day of the period is used.
to_date	date	Today	Same parsing rules as from_date; partial values resolve to the last day of the period.
areas	list of strings	All areas	Comma-separated AquaCloud area names (Norwegian or English) or IDs. Use % to explicitly request all areas.
generations	list of strings	All generations	Comma-separated generation codes (e.g. H2023) or localized names (e.g. Høst 2023).
weight_range_start	integer (0–15000)	0	Minimum individual fish weight in grams to include in the aggregation.
weight_range_end	integer (0–15000)	15000	Maximum individual fish weight in grams to include in the aggregation.
exclude_self	boolean	false	Excludes the authenticated farmer group from the benchmark set when true.
offset	integer ≥ 0	0	Number of rows to skip for pagination.
limit	integer (0–1000)	1000	Maximum number of rows returned. The service internally fetches limit + 1 items to set pagination.has_more.

Response envelope

Every endpoint returns:

• data: the list of SFR records described per endpoint.
• pagination: includes offset, limit, and has_more when paging is applicable.
• metadata: contains a request_id, API version, and (when relevant) the farmer group key excluded via exclude_self.

Endpoints

GET /v3/feeding/sfr_temperature_by_region_and_week

Returns specific feed rate benchmarks grouped by area and week, including the ambient temperature for each week.

Response fields in data:

Field	Type	Description
feeding_week	string	ISO date string representing the Monday of the reported week.
temperature	number	Average recorded sea temperature for the area and week.
aquacloud_area_name	string	Human-readable AquaCloud area name.
production_area_ids	array of integers	Internal production area identifiers associated with the row.
specific_feed_rate	number	Benchmark SFR calculated across the filtered dataset.
site_count	integer	Number of sites contributing to the benchmark row.
farmer_specific_feed_rate	number	SFR calculated for the authenticated farmer group (when included).
farmer_site_count	integer	Number of the farmer’s sites contributing to the row.

Typical usage is to trend SFR versus temperature for selected areas or generations while constraining the biomass range via weight_range_start/weight_range_end.

GET /v3/feeding/sfr-by-weeknumber-and-year

Delivers week-based SFR time series, aggregating the dataset down to calendar week and year.

Response fields in data:

Field	Type	Description
year	integer	Calendar year of the observation.
week	integer	ISO week number (1–53).
specific_feed_rate	number	Benchmark SFR for the week after filters are applied.

Use this endpoint to build historical SFR charts or to compare current performance against previous years with identical filter sets.

GET /v3/feeding/sfr-days-per-temperature

Provides the distribution of feeding days per temperature bucket for the selected filters.

Response fields in data:

Field	Type	Description
avg_temperature	number	Mean sea temperature for the bucket.
aquacloud_area_name	string	AquaCloud area represented by the bucket (if applicable).
count	integer	Total feeding days in the bucket.
rate_of_days_by_temperature	number	Share of feeding days (0–1) that falls within the temperature bucket.

This endpoint is useful for identifying the temperature ranges in which most feeding activity occurs, and for comparing distributions between the farmer group and the broader benchmark when exclude_self is false.

Example request

GET /v3/feeding/sfr_temperature_by_region_and_week?areas=Midt&from_date=2024-01-01&to_date=2024-03-31&weight_range_start=500&weight_range_end=6500&limit=200 HTTP/1.1
Host: api.aquacloud.io
Authorization: Bearer <token>
x-client-secret: <client-secret>

A matching response with content will include the weekly SFR records in data, pagination details when more than 200 rows exist, and a metadata.request_id you can log for support.