Common Reference Data

Reference endpoints under /v3/common provide the lookup tables you need to build filters, map identifiers to readable names, and understand AquaCloud geography. Routes are read-only GET endpoints and share the standard v3 authentication: send Authorization: Bearer <token> and, for non-premium tiers, include x-client-secret.

All responses follow the shared schema used across v3 resources:

• data: the payload described per endpoint below (lists or objects).
• pagination: present on list endpoints that support paging (offset, limit, has_more).
• metadata: includes API bookkeeping fields (empty for most reference calls).

Pagination parameters

Only the site listing endpoint is paginated. It accepts:

Name	Type	Default	Details
offset	integer ≥ 0	0	Rows to skip.
limit	integer (0–2000)	1000	Maximum rows returned. Services fetch limit + 1 rows to populate has_more.

Endpoints

GET /v3/common/site

Lists AquaCloud and Fisheries Directorate sites with their geographic context.

Field	Type	Description
site_id	string	Official Fisheries Directorate site identifier.
site_name	string	Registered site name.
latitude / longitude	number	Coordinates when available.
placement	string	Placement classification (offshore/onshore).
production_area_id / production_area_name	integer / string	Production area metadata.
marine_type_code / marine_type_name	string	Marine typology code and friendly name.
marine_type_region_code / marine_type_region_name	string	Regional grouping for marine typology.
is_in_aquacloud	boolean	Whether the site participates in AquaCloud datasets.
last_registration_date	string (ISO datetime)	Timestamp of the most recent registration.

GET /v3/common/site/{site_id}

Fetch a single site record by Fisheries Directorate ID. Returns the same schema as a single element in the list endpoint.

GET /v3/common/production-area

Returns all production areas with display names and geometry references.

Field	Type	Description
area_id	integer	Production area identifier.
area_name	string	Registered production area name.
area_geojson	string	GeoJSON polygon for the area.
region_name	string	Optional region grouping.

GET /v3/common/aquacloud-areas

Lists AquaCloud area groupings that aggregate one or more production areas.

Field	Type	Description
area_id	string	AquaCloud area identifier.
name	string	Localized area name.
name_english	string	English display name.
production_area_ids	array of integers	Production areas that belong to the AquaCloud area.

GET /v3/common/farmers-in-aquacloud

Summary of farmers that currently contribute data.

Field	Type	Description
name	string	Farmer/company name.
number_of_farmers_in_dataset	integer	Number of aggregated entities represented.
production_area_ids	array of integers	Production areas where the farmer has data.
production_region_names	array of strings	Region labels with coverage.
is_active_with_data	boolean	Indicates if recent data is present.

GET /v3/common/farm-and-site-stats

High-level AquaCloud adoption metrics.

Field	Type	Description
signed_farmers	integer	Count of signed farmers.
active_farmers	integer	Farmers with recent data.
offshore_sites	integer	Offshore site count in AquaCloud.
onshore_sites	integer	Onshore site count.
recently_active_sites	integer	Sites with data in the latest period.

GET /v3/common/marine-typology-types

Returns marine typology codes for classifying sites.

Field	Type	Description
marine_type_code	string	Typology code.
marine_type_name	string	Human-friendly label.

GET /v3/common/marine-typology-regions

Lists marine typology regions used to group sites.

Field	Type	Description
marine_type_region_code	string	Region code.
marine_type_region_name	string	Region name.

GET /v3/common/generations

Returns generations available in AquaCloud datasets. The list is not paginated.

Field	Type	Description
generation	string	Generation code (e.g. H2023).
generation_name	string	Display name (e.g. Høst 2023).

GET /v3/common/farmers-per-po

Provides the number of farmers per production area, useful for context in benchmarking dashboards.

Field	Type	Description
production_area_id	integer	Production area identifier.
number_of_farmers	integer	Farmers contributing data in the area.

Internal helper

GET /v3/common/farmer/me is excluded from the public schema and intended for internal applications that need to resolve the authenticated farmer. It returns the same Farmer schema as the list endpoints.

Example request

GET /v3/common/site?offset=0&limit=500 HTTP/1.1
Host: api.aquacloud.ai
Authorization: Bearer <token>
x-client-secret: <client-secret>

The response will include the first 500 site records in data, pagination metadata indicating whether more rows remain, and an empty metadata object.