From public geodata to a honey-production estimate.

This is the practical handoff for another software team: which services SiBeela calls, how it calls them, how it turns their responses into parcels, and where each country's coverage stops.

Eduardo Marcos Alejos · Senior Programmer and Data Scientist · BeeLife — BeeLife European Beekeeping Coordination

Every example URL in this document is a public provider URL or a placeholder such as YOUR_BACKEND. The document contains no production server address, service-account identity, private key, access token, API key or billing identifier. Example coordinates and JSON values are illustrative.

The reusable integration recipe

For Sweden, France, Italy, Belgium and Germany, the browser calls the public feature service through SiBeela's Node endpoint GET /proxy?url=.... The proxy relays the response, caches successful URLs for 10 minutes, retries server errors and rejects private/internal destinations. Spain's preferred vector route is implemented directly in the backend.

const upstream = new URL('https://data.geopf.fr/wfs');
upstream.search = new URLSearchParams({
  SERVICE: 'WFS', VERSION: '2.0.0', REQUEST: 'GetFeature',
  TYPENAMES: 'RPG.LATEST:parcelles_graphiques',
  outputFormat: 'application/json', SRSNAME: 'EPSG:4326',
  COUNT: '500', startIndex: '0',
  BBOX: '2.30,48.80,2.40,48.90,EPSG:4326'
});
const response = await fetch('/proxy?url=' + encodeURIComponent(upstream));
if (!response.ok) throw new Error(`WFS HTTP ${response.status}`);
const geojson = await response.json();

The country's production adapter is selected by BeeLifeCountries. Both the grid and geometric prediction choices route non-Spanish countries to the same country adapter. Their WFS census is therefore the operative parcel connection for those countries.

How to make a request that can be reproduced

The provider's URL is only one part of a working connection. The layer name, CRS, BBOX order, output format, pagination and interpretation of the response are equally important. The examples below show the exact mechanics used by the adapters.

Concrete BBOX example

For an illustrative centre at latitude 48.8566, longitude 2.3522, radius 2.5 km, the approximation used by the adapters produces south 48.834077, west 2.317968, north 48.879123, east 2.386432. France sends 2.317968,48.834077,2.386432,48.879123,EPSG:4326. Wallonia and Emilia-Romagna reverse the coordinate pairs.

async function readPages({ baseUrl, typeName, outputFormat, bbox, pageSize = 500 }) {
  const all = [];
  for (let startIndex = 0; startIndex < 20000; startIndex += pageSize) {
    const q = new URLSearchParams({
      service: 'WFS', version: '2.0.0', request: 'GetFeature',
      typeNames: typeName, outputFormat, srsName: 'EPSG:4326',
      count: String(pageSize), startIndex: String(startIndex), bbox
    });
    const upstream = baseUrl + '?' + q.toString();
    const response = await fetch('/proxy?url=' + encodeURIComponent(upstream));
    if (!response.ok) throw new Error('Source HTTP ' + response.status);
    const page = await response.json();
    const features = Array.isArray(page.features) ? page.features : [];
    all.push(...features);
    if (features.length < pageSize) break;
  }
  return all;
}

This is a didactic template for GeoJSON-producing sources. German GML and ArcGIS REST need their separate parsers and query parameters, shown in the Germany chapter. Production code should add timeouts, cache, response-size controls, cancellation and provider-specific maximum pages.

The normalized parcel object

The web app converts remote schemas into comparable records. The example below is illustrative, not a captured API response; the keys match fields used by the model.

{
  "id": "FR_example-123", "countryCode": "FR",
  "source": "RPG Geoplateforme WFS",
  "lat": 48.851, "lng": 2.349,
  "displayName": "Colza hiver", "cropKey": "CZH",
  "usoCode": "TA", "cultivoEspecifico": "Colza hiver",
  "superficieNum": 1.8, "superficie": "1.80 ha",
  "regadio_secano": "SECANO",
  "valorApicola": 0.73
}

valorApicola is a local, season-sensitive ranking score, not measured honey yield. cropKey is the bridge to a country botanical catalogue. If a provider lacks an area value, some current adapters calculate it from geometry; Sweden, France and Italy can fall back to 1 ha. A receiving team should flag that as estimated rather than silently treating it as surveyed area.

Credentials, costs and safe handoff

The public geospatial URL templates are safe to explain. The ability to charge your account or consume your quota comes from credentials, project settings and access to your own backend. This guide deliberately contains none of those.

Visual connection: Leaflet requests SIGPAC WMS version 1.3.0 as transparent PNG. The layer names are AU.Sigpac:recinto, AU.Sigpac:cultivo_declarado and AU.Sigpac:e_paisaje. A clicked pixel can be queried with WMS GetFeatureInfo through /proxy.

Calculation connection: the browser calls its own backend GET /sigpac-parcels-in-radius. That backend requests HubCloud recinto and cultivo_declarado GeoJSON tiles at zoom 15, joins them by SIGPAC identity, loads cod_producto.json and cod_uso_sigpac.json for labels, clips polygons to the circle with Turf, and returns parcel area and crop data.

GET /sigpac-parcels-in-radius?lat=40.4637&lng=-3.7492&radiusKm=2.5&minAreaM2=1000&strategy=stratified&maxParcels=600&minPerStratum=20&seedMode=deterministic

Upstream tile template:
https://sigpac-hubcloud.es/mvt/{recinto|cultivo_declarado}@3857@geojson/15/{x}/{y}.geojson

Code tables:
https://sigpac-hubcloud.es/codigossigpac/cod_producto.json
https://sigpac-hubcloud.es/codigossigpac/cod_uso_sigpac.json

The endpoint returns parcels, sampling, counts, tile errors and clipped area. Default sampling is stratified when needed; strategy=all requests every matching parcel. The current backend caps the circle radius at 10 km and rejects requests that need more than 160 z15 tiles.

What each Spanish request contributes

The seven-part SIGPAC key is provincia:municipio:agregado:zona:poligono:parcela:recinto. The server uses it to join recinto and declared-crop tiles. The same complete polygon can be repeated in adjacent tiles, so it keeps the largest clipped intersection for each key rather than summing duplicates. Crop data is absent for some recintos; the model then uses a lower-confidence land-use profile or enrichment.

Catastro geometry:
GET https://ovc.catastro.meh.es/INSPIRE/wfsCP.aspx
  ?service=WFS&request=GetFeature&typenames=cp:CadastralParcel
  &srsname=EPSG:4326&bbox={south},{west},{north},{east},EPSG:4326
  &maxfeatures=800

SIGPAC WMS attribute lookup (the browser sends the URL through /proxy):
GET https://sigpac-hubcloud.es/wms
  ?service=WMS&version=1.3.0&request=GetFeatureInfo
  &layers=AU.Sigpac:recinto,AU.Sigpac:cultivo_declarado
  &query_layers=AU.Sigpac:recinto,AU.Sigpac:cultivo_declarado
  &info_format=text/html&crs=EPSG:3857
  &bbox={projectedWest},{projectedSouth},{projectedEast},{projectedNorth}
  &width=256&height=256&i=128&j=128

The GetFeatureInfo bounding box is in metres in EPSG:3857, centred on the queried point; its image pixel is 128/128. The backend Catastro fallback defaults to 800 features (hard cap 2,000) and clips them to the circle. The constant used by this fallback requests cultivo_declarado; an adjacent code comment calls it linea_declaracion, so the constant is authoritative here.

How a returned Spanish parcel enters the model

Response to handle: n_parcels_total_in_radius, n_parcels_returned, n_tile_errors, coverage_of_circle_pct, sampling and parcels. A non-zero tile-error count means the output may be incomplete even if the HTTP request succeeds. HTTP 413 means the chosen radius would request too many tiles. The server caches tiles for six hours and code tables for one day.

Regional route: /sigpac-regional-heatmap?lat=&lng=&radiusKm=&gridKm=&jobId= divides a larger circle into subareas and returns aggregated cells instead of thousands of parcel records. It is a separate Spain-only analysis path; the other country adapters do not expose that regional function.

WFS endpoint: http://epub.sjv.se/inspire/inspire/wfs. Query inspire:senaste_arslager_block; request application/json, EPSG:4326 and a longitude–latitude bounding box. The adapter asks for 500 features per page, up to 40 pages, through /proxy.

GET http://epub.sjv.se/inspire/inspire/wfs
  ?service=WFS&version=2.0.0&request=GetFeature
  &typeNames=inspire:senaste_arslager_block
  &outputFormat=application/json&srsName=EPSG:4326
  &count=500&startIndex=0
  &bbox={west},{south},{east},{north},EPSG:4326

Read agoslag as the land-use label, areal as hectares and blockid as the stable key. Swedish terms are mapped to a canonical cropKey, a broad usoCode, and a month-sensitive beekeeping score. Leaflet displays inspire:senaste_arslager_block and inspire:senaste_arslager_skifte from the matching WMS endpoint.

Fields, translation and pagination

The adapter caches by rounded centre and radius, fetches 500 records per page, pauses briefly between full pages, and stops at an empty/short page or after 40 pages. On a WFS failure it logs the error and returns the records already collected; therefore a non-empty result can still be incomplete. A receiving implementation should expose an incomplete flag rather than treating partial pages as a full census.

Remote feature.properties:
{ "blockid": "example-42", "agoslag": "oljeväxter", "areal": 2.4 }

Normalized parcel:
{ "id": "SE_example-42", "countryCode": "SE",
  "displayName": "oljeväxter", "cropKey": "raps",
  "usoCode": "TA", "superficieNum": 2.4,
  "source": "Jordbruksverket WFS" }

Map click: when a Swedish overlay is visible, a tiny BBOX around the clicked coordinate requests up to 10 features from the visible block and/or skifte types. That click lookup is separate from the 500-record prediction query.

The adapter queries https://data.geopf.fr/wfs via /proxy. Before parcel retrieval it fetches up to 500 entries from RPG.LATEST:codes_cultures to turn short crop codes into labels; a local code dictionary remains available if that call fails. Parcel pages are 500 features, up to 40 pages.

GET https://data.geopf.fr/wfs
  ?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetFeature
  &TYPENAMES=RPG.LATEST:parcelles_graphiques
  &outputFormat=application/json&SRSNAME=EPSG:4326
  &COUNT=500&startIndex=0
  &BBOX={west},{south},{east},{north},EPSG:4326

Map code_cultu to the crop code, cat_cult_p to category, surf_parc (or sf_adm_de) to hectares and id_parcel to identity. The crop code is the French cropKey used by the floral catalogue. WMS overlays at https://data.geopf.fr/wms-r/wms use LANDUSE.AGRICULTURE.LATEST and IGNF_RPG_PARCELLES-AGRICOLES-CATEGORISEES_2024.

Dictionary, fields and a record through the adapter

GET https://data.geopf.fr/wfs
  ?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetFeature
  &TYPENAMES=RPG.LATEST:codes_cultures
  &outputFormat=application/json&COUNT=500

The adapter caches requests by rounded location and radius. A full page triggers the next startIndex; a short page stops the loop. Errors can leave a partial result, so retain the fetched-page count and communicate incompleteness. RPG.LATEST and the WMS layer labelled 2024 need independent version checks: the visual layer's year does not prove the feature layer has the same vintage.

Remote feature.properties:
{ "id_parcel": "example-123", "code_cultu": "CZH",
  "cat_cult_p": "COLZA", "surf_parc": 1.8 }

Normalized parcel:
{ "id": "FR_example-123", "countryCode": "FR",
  "cropKey": "CZH", "superficieNum": 1.8,
  "source": "RPG Geoplateforme WFS" }

Map interaction: the WMS paints the visible RPG layer; a clicked location uses a small WFS BBOX to retrieve nearby feature attributes. For a new build, start with the provider's Géoplateforme WFS instructions and GetCapabilities, then confirm that the requested type and JSON format still exist.

The national Catasto WMS exposes CP.CadastralParcel for parcel outlines. The adapter explicitly substitutes EPSG:4258 in the generated tile URL. Cadastral outlines contain no dependable crop identity for this model.

For the estimate, query Emilia-Romagna WFS layer _020_uso_suolo_ed2023 through /proxy. The code uses WFS 2.0, outputFormat=geojson, 500-feature pages and a latitude–longitude bounding box. The query is attempted only when the chosen circle overlaps the configured Emilia-Romagna bounds.

GET http://servizigis.regione.emilia-romagna.it/wfs/uso_del_suolo
  ?service=WFS&version=2.0.0&request=GetFeature
  &typeNames=_020_uso_suolo_ed2023
  &outputFormat=geojson&srsName=EPSG:4326
  &count=500&startIndex=0
  &bbox={south},{west},{north},{east},EPSG:4326

Map DESCR to the land-use description, SIGLA to the class code, HECTARES to area and OBJECTID to identity. The text classifier makes the Italian cropKey; non-productive land is scored very low. The land-use overlay is itself drawn from WFS GeoJSON for the visible map area.

Connection roles and field mapping

Remote feature.properties:
{ "OBJECTID": 123, "SIGLA": "SEMIN", "DESCR": "Seminativi",
  "HECTARES": 2.7 }

Local interpretation:
{ "id": "IT_123", "displayName": "Seminativi",
  "superficieNum": 2.7, "source": "Regione Emilia-Romagna WFS",
  "evidence": "regional land-use class" }

Both requests use WFS 2.0, EPSG:4326, count=500 and startIndex; each regional loop allows up to 30 pages. Flanders also supplies GEWASGROEP and HFDTLT; Wallonia supplies GROUPE_CULT and CULT_COD. The adapter translates Dutch and French crop names into one Belgian crop catalogue and de-duplicates by region plus ID.

Flanders:
GET https://geo.api.vlaanderen.be/Landbgebrperc/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=Landbgebrperc:Lbgebrperc&outputFormat=application/json&srsName=EPSG:4326&count=500&startIndex=0&bbox={west},{south},{east},{north},EPSG:4326

Wallonia:
GET https://geoservices.wallonie.be/arcgis/services/WFS/SIGEC_PARC_AGRI_ANON/MapServer/WFSServer?service=WFS&version=2.0.0&request=GetFeature&typeNames=SIGEC_PARC_AGRI_ANON:Parcelles_agricoles___2023_&outputFormat=GEOJSON&srsName=EPSG:4326&count=500&startIndex=0&bbox={south},{west},{north},{east},EPSG:4326

For visual display, Flanders has ALV WMS layer LbGebrPerc2023. The Wallonia overlay is painted from returned WFS GeoJSON because the chosen MapServer does not expose a WMS in this implementation.

Normalize the two regional schemas separately

The adapter translates Dutch and French names to its own Belgian cropKey and usoCode; those keys point to web/data/melliferous_be.js. It queries both services rather than preselecting one region, so a circle near the regional boundary can receive both. The result contains an adapter-level census annotation; it is not proof that the providers returned a complete census when a page failed.

Flanders remote: { "UIDN": "example-fl", "LBLHFDTLT": "Koolzaad",
                   "GRAF_OPP": 18000 }
Flanders local:  { "countryCode": "BE", "superficieNum": 1.8,
                   "displayName": "Koolzaad", "region": "Vlaanderen" }

Wallonia remote: { "OBJECTID": "example-wa", "CULT_NOM": "Colza",
                   "SURF_HA": 1.8 }
Wallonia local:  { "countryCode": "BE", "superficieNum": 1.8,
                   "displayName": "Colza", "region": "Wallonie" }

Optional provider route: Digitaal Vlaanderen also publishes an OGC API Features collections endpoint. It is a possible modern alternative for a new client, not the route this repository currently calls.

The code defines a REGIONS table with geographical bounds and a preferred parcel source (falling back to a reference block). It selects regions intersecting the apiary's bounding box, reads at most 12 pages of 1,000 features per region, and normalizes WFS GeoJSON, WFS GML or ArcGIS REST output to WGS84 GeoJSON. Each row below is an actual configured source.

// JSON WFS (type, format and BBOX order come from the selected Land row)
GET {base}?service=WFS&version=2.0.0&request=GetFeature&typeNames={type}&outputFormat={format}&srsName=EPSG:4326&count=1000&startIndex=0&bbox={providerSpecificBbox}

// GML-only WFS (Bavaria, Brandenburg/Berlin, Saarland)
GET {base}?service=WFS&version=2.0.0&request=GetFeature&typeNames={type}&count=1000&startIndex=0&srsName=urn:ogc:def:crs:EPSG::4326&bbox={south},{west},{north},{east},urn:ogc:def:crs:EPSG::4326

// Saxony-Anhalt ArcGIS REST
GET {base}/query?where=1%3D1&outFields=*&f=geojson&outSR=4326&geometryType=esriGeometryEnvelope&inSR=4326&spatialRel=esriSpatialRelIntersects&geometry={west},{south},{east},{north}&resultRecordCount=1000&resultOffset=0

The adapter uses provider-specific field extractors, swaps Saxony's returned coordinates, parses GML for three providers and computes area from geometry when no usable area field exists. It turns German/INSPIRE crop labels into the German cropKey and monthly score. Its map overlays are drawn from normalized GeoJSON, rather than one country-wide WMS.

The decisions inside the dispatcher

Remote properties:
{ "ID": "example-7", "CODE_TXT": "Raps",
  "USE_TXT": "Ackerland", "AREA_HA": 1.6 }

Adapter output:
{ "id": "DE_NRW_P_example-7", "countryCode": "DE",
  "region": "Nordrhein-Westfalen", "cropKey": "raps",
  "usoCode": "TA", "superficieNum": 1.6,
  "source": "InVeKoS Nordrhein-Westfalen" }

The source choice is one per Land: prefer a configured parcel source, otherwise use the block source. The adapter does not merge a parcel layer with its block fallback, which avoids counting both representations for the same area. A page error stops only that source's loop; a full final page at the 12-page cap can leave undiscovered records. Expose source, fetched count and truncation/error state in a fresh implementation.

GML limit: the in-repository parser is deliberately small. It reads posList rings and simple properties, but may not preserve every complex GML geometry relationship. For a production reimplementation, use a full GML parser and validate a known polygon, area and axis order for each service.

Shared services that enrich the estimate

Supporting requests and their exact role

GET https://api.open-meteo.com/v1/forecast
  ?latitude={lat}&longitude={lng}
  &daily=temperature_2m_min,temperature_2m_max,temperature_2m_mean,
         relative_humidity_2m_mean,wind_speed_10m_max,precipitation_sum
  &timezone=auto&forecast_days=14

From a normalized parcel to kilograms

This is an estimate built from remote landscape data and local assumptions. The external APIs do not return measured nectar output or harvested honey. See web/honey_model.js for the full equations, species profiles and sensitivity bands.

Worked example: recreate a French query

This example is intentionally synthetic. It shows how another team can reproduce the connection and data transformation without any SiBeela credential, backend address or private observation.

const base = 'https://data.geopf.fr/wfs';
const q = new URLSearchParams({
  SERVICE: 'WFS', VERSION: '2.0.0', REQUEST: 'GetFeature',
  TYPENAMES: 'RPG.LATEST:parcelles_graphiques',
  outputFormat: 'application/json', SRSNAME: 'EPSG:4326',
  COUNT: '500', startIndex: '0',
  BBOX: '2.317968,48.834077,2.386432,48.879123,EPSG:4326'
});
const upstream = `${base}?${q}`;
const response = await fetch(
  'https://YOUR_BACKEND/proxy?url=' + encodeURIComponent(upstream)
);
if (!response.ok) throw new Error(`Source HTTP ${response.status}`);
const { features = [] } = await response.json();
console.log('Features in first page:', features.length);

The placeholder relay must be your own service. For direct server-to-server use, call the public provider URL without a browser proxy. The example's coordinates and records are teaching values; no production request result is embedded here.

Implementation checklist for another team

1. Choose a country and confirm the selected apiary is inside that adapter's actual analytical coverage.
2. Use WMS only for map images; use the listed feature endpoint for parcel and crop attributes.
3. Keep provider-specific typeNames, output format, bounding-box axis order, coordinate correction and field mapping. These details are especially important for Belgium, Italy and Germany.
4. Page through features and deduplicate on the provider's ID. Then test each polygon centre against the circle; a BBOX alone is rectangular.
5. Keep source name, original crop label, area, country, region, canonical cropKey and data-quality flags with each normalized parcel.
6. Use local floral mappings and phenology to turn land use into a potential estimate. Do not treat a land-use score as kilograms of honey by itself.
7. Prepare caching, timeouts, retry/backoff and a truthful “source unavailable” state. The country's public service can be slow, partial or temporarily offline.
8. If you use Earth Engine, configure your own service account. Keep secrets on the server and proxy HTTP-only sources through an HTTPS backend.
9. Protect any billable or quota-limited backend route with authentication, rate limits and request caps. Never give another team access to your existing Earth Engine project or deployed server.
10. Review the provider's attribution, reuse and rate-limit terms. Replace Wallonia's legacy layer after inspecting the new SIGeC schema; treat Emilia-Romagna's newer layer as a candidate until field mapping is verified.

Source-code map

These local files are the implementation behind the requests and limits above. The HTML example sibeela_explicacion_v2.html supplied the visual language of this guide.

Repository-based guide · 2026. Upstream endpoints, layer names, licensing and service availability should be checked again before deployment because third-party services can change.