Migration Guide: Observation API V4 to V5

Migration Guide: Observation API V4 to V5

Overview

This guide provides comprehensive information for migrating from the InfoFlora Observation API V4 to V5. The V5 release (January 27, 2025) introduces significant improvements including enhanced filtering capabilities, Darwin Core alignment, and streamlined request/response formats.

This guide covers the following endpoint categories: Observations (including releves and supplements), Documents, Neophytes, Taxonomy, Users (people and projects), and Vocabulary.

Change Log Summary

Added

Filter operations for query parameters (eq, neq, gt, gte, lt, lte, in, not_in, wildcards, null checks)
Optional with_total parameter for list endpoints
New required field basis_of_record for observations
Darwin Core term references in property descriptions
Read-only fields: geodetic_datum, decimal_longitude, decimal_latitude

Changed

All endpoint paths from /v4/ to /v5/
Removed success property from GET responses
Removed unnecessary wrapper objects from POST/PUT payloads
Renamed multiple properties to align with Darwin Core specifications

Removed

success property from response objects
Deprecated fields removed from write schema: taxon_expert, introduced_expert, municipality_expert, srid
municipality_id removed from write schema (still returned read-only in GET responses)
Unnecessary data wrapper in request payloads
Always-present total counts (now opt-in via with_total parameter)
Removed deprecated geometry parameters: geometry (use footprint_wkt instead)
Removed legacy array-style filter parameters: taxa, projects, observers, ids, cantons, municipalities (use filter operations instead)
Removed deprecated endpoints: /cantons and /municipalities (use /administrative_units)
Deprecated: POST /v4/observations/{id}/neophytes and POST /v4/observations/{id}/supplements (use PUT instead)

Breaking Changes

1. Base URL Path Change

V4: /rest/v4/...
V5: /rest/v5/...

All endpoint paths have been updated to use the v5 version prefix.

2. Response Envelope Changes

V4 Response Structure:

{
  "success": true,
  "data": { ... }
}

V5 Response Structure:

{
  "data": { ... }
}

The success property has been removed from all GET responses. Success and failure are indicated by HTTP status code.

3. POST/PUT Request Body Format

V4: Some endpoints wrapped payload data in a “data” object or specific property wrappers.

V5: The unnecessary wrapper objects have been removed from all POST and PUT payloads. Request bodies now directly contain the resource properties.

4. Geometry Filter Parameter Changes

V4: Geometry filtering used geometry, bbox, and srid parameters.
V5:

footprint_wkt is supported (WKT format, WGS84/EPSG:4326) and replace geometry
bbox is deprecated and incompatible with footprint_wkt
srid is removed from every endpoint excepted : GET /observations, GET /releves

V4:

GET /v4/observations?bbox=7.0,47.0,8.0,48.0&srid=4326

V5:

GET /v5/observations?footprint_wkt[eq]=POLYGON((7.0 47.0, 8.0 47.0, 8.0 48.0, 7.0 48.0, 7.0 47.0))

5. Deprecated Array-Style Filter Parameters Removed

Many V4 endpoints accepted array-style comma-separated parameters. These have been removed in V5 in favor of filter operations.

V4 Parameter (comma-separated list)	V5 Equivalent (filter operation)
`taxa=11018,11019`	`taxon_id[in]=11018,11019`
`projects=1,2`	`dataset_id[in]=1,2`
`observers=10,20`	`recorded_by_id[in]=10,20`
`ids=100,200`	`occurrence_id[in]=100,200`
`after=2024-01-01`	`event_date[gte]=2024-01-01`
`before=2024-12-31`	`event_date[lte]=2024-12-31`
`validation_statuses=100,200`	`validation[in]=100,200`
`cantons=CH-BE,CH-VD`	`location_id[in]=...` (use administrative unit IDs)
`municipalities=13,26`	`location_id[in]=13,26`

Query Parameter Filter Operations

One of the major improvements in V5 is the introduction of comprehensive filter operations for query parameters. See Request and Response Format for more details.

Filter Usage Examples

Basic filter:

GET /v4/observations?taxa=11018
GET /v5/observations?taxon_id[eq]=11018

Multiple filters:

GET /v4/observations?taxa=11018,11019&after=2024-01-01
GET /v5/observations?taxon_id[in]=11018,11019&event_date[gte]=2024-01-01

Null check:

GET /v5/observations?verbatim_identification[is_not_null]
GET /v5/observations?verbatim_identification[is_not_null]=true

Wildcard search:

GET /v5/observations?occurrence_remarks[iw_eq]=*foo*

Important Notes

Not all operations are available for all fields
Check the parameter description in the API documentation for allowed operations
List separators: Default operation is eq. If your filter use separators , or ~ you must specify operation in or not_in

Total Values in List Responses

V4 Behavior

Total counts were always returned in the response.

V5 Behavior

By default, responses with lists of objects are returned WITHOUT totals.

To retrieve totals, you must explicitly request them using the with_total query parameter:

GET /v5/observations?with_total=true

When with_total=true:

X-Total header: Total number of items in the database
X-Filtered-Total header: Number of items matching the current filters

Default value: false

Migration Impact

If your application relies on total counts:

Action Required: Add with_total=true to all list endpoint requests
Performance Benefit: If you don’t need totals, omit this parameter to improve response times. If you only need totals, prefer a HEAD request with the with_total=true query parameter.

POST and PUT Payload Format Changes

V4 Format

Some endpoints required wrapping the payload in a data or specific property object:

POST /v4/observations
{
  "observation": {
    "project_id": 12345,
    "date": "2024-01-15T10:00:00+01:00",
    "taxon_id": 11018,
    ...
  }
}

V5 Format

All unnecessary wrapper objects have been removed:

POST /v5/observations
{
  "dataset_id": 12345,
  "event_date": "2024-01-15T10:00:00+01:00",
  "taxon_id": 11018,
  ...
}

Migration Steps

Review all POST and PUT request payloads in your code
Remove any data or resource-name wrapper objects
Update property names according to the mapping table below
Test all create and update operations

Property and Parameter Renaming

A significant number of properties have been renamed to align with Darwin Core specifications.

Observation Schema Property Mapping

V4 Property	V5 Property	Darwin Core Term
`project_id`	`dataset_id`	dwc:datasetID
`releve_type`	`event_type`	dwc:eventType
`date`	`event_date`	dwc:eventDate
`observers`	`recorded_by_id`	dwc:recordedByID
`taxon_orig`	`verbatim_identification`	dwc:verbatimIdentification
`determinavit_cf`	`identification_qualifier`	dwc:identificationQualifier
`determinavit`	`identified_by`	dwc:identifiedBy
`introduced`	`degree_of_establishment`	dwc:degreeOfEstablishment
`locality_descript`	`verbatim_locality`	dwc:verbatimLocality
`x`	`decimal_longitude`	dwc:decimalLongitude
`y`	`decimal_latitude`	dwc:decimalLatitude
`geometry`	`footprint_wkt`	dwc:footprintWKT
`xy_type`	`georeference_protocol`	dwc:georeferenceProtocol
`xy_precision`	`coordinate_uncertainty_in_meters`	dwc:coordinateUncertaintyInMeters
`presence`	`occurrence_status`	dwc:occurrenceStatus
`srid`	`geodetic_datum`	dwc:geodeticDatum

New Required Fields

V5 introduces new required fields:

V5 Property	Description	Vocabulary Field Name
`basis_of_record`	Specific nature of the record	`basis_of_record`

Deprecated Fields

The following V4 fields are deprecated and removed from the write schema in V5:

taxon_expert
introduced_expert
municipality_expert
srid (replaced by geodetic_datum, which is read-only)

Note: municipality_id was deprecated in V4 write operations and is no longer accepted in POST/PUT payloads in V5, but it is still returned in GET responses as a computed read-only field.

Vocabulary Field Name Changes

When looking up vocabulary values, note that fieldname in V4 becomes field_name in V5.

Example:

V4: fieldname = 'releve_type'
V5: field_name = 'releve_type'

Query Parameter Mapping

Query parameters have also been renamed to match the new property names:

V4 Parameter	V5 Parameter
`project_id`	`dataset_id`
`date`	`event_date`
`taxon_orig`	`verbatim_identification`

Response Format Changes

See Request and Response Format for more details.

Single Resource Response

V4:

{
  "success": true,
  "data": {
    "id": 123,
    "project_id": 12345,
    "date": "2024-01-15T10:00:00+01:00",
    ...
  }
}

V5:

{
  "data": {
    "id": 123,
    "dataset_id": 12345,
    "event_date": "2024-01-15T10:00:00.000+01:00",
    ...
  }
}

List Response

V4:

{
  "success": true,
  "data": [
    { ... },
    { ... }
  ]
}

Headers:

X-Total: 1000
X-Filtered-Total: 50

V5 (without totals):

{
  "data": [
    { ... },
    { ... }
  ]
}

V5 (with totals - using with_total=true):

{
  "data": [
    { ... },
    { ... }
  ]
}

Headers:

X-Total: 1000
X-Filtered-Total: 50

Category-Specific Migration

The following sections detail migration steps organized by endpoint category.

Observations

All observation endpoints follow the standard /v4/ → /v5/ path change. Additionally, several endpoints have been modified or removed.

Endpoint Mapping

V4 Endpoint	V5 Endpoint	Notes
`GET /v4/observations`	`GET /v5/observations`	Many query params removed/renamed (see below)
`POST /v4/observations`	`POST /v5/observations`	Request body wrapper removed
`GET /v4/observations/{id}`	`GET /v5/observations/{id}`
`PUT /v4/observations/{id}`	`PUT /v5/observations/{id}`
`DELETE /v4/observations/{id}`	`DELETE /v5/observations/{id}`
`GET /v4/observations/{id}/docs`	`GET /v5/observations/{id}/docs`
`GET /v4/observations/{id}/docs/{doc_id}`	`GET /v5/observations/{id}/docs/{doc_id}`
`PUT /v4/observations/{id}/docs/{doc_id}`	`PUT /v5/observations/{id}/docs/{doc_id}`
`DELETE /v4/observations/{id}/docs/{doc_id}`	`DELETE /v5/observations/{id}/docs/{doc_id}`
`GET /v4/observations/{id}/neophytes`	`GET /v5/observations/{id}/neophytes`
`PUT /v4/observations/{id}/neophytes`	`PUT /v5/observations/{id}/neophytes`
`DELETE /v4/observations/{id}/neophytes`	`DELETE /v5/observations/{id}/neophytes`
`POST /v4/observations/{id}/neophytes`	Removed	Use `PUT` instead
`GET /v4/observations/{id}/supplements`	`GET /v5/observations/{id}/supplements`
`PUT /v4/observations/{id}/supplements`	`PUT /v5/observations/{id}/supplements`
`DELETE /v4/observations/{id}/supplements`	`DELETE /v5/observations/{id}/supplements`
`POST /v4/observations/{id}/supplements`	Removed	Use `PUT` instead
`GET /v4/observations/{id}/validations`	`GET /v5/observations/{id}/validations`
`PUT /v4/observations/{id}/validations`	`PUT /v5/observations/{id}/validations`
`GET /v4/observations/ids`	`GET /v5/observations/ids`	Many params removed/renamed (see below)
`GET /v4/simple_observations`	`GET /v5/simple_observations`
`GET /v4/clustered_observations/{srid}/{z}/{x}/{y}`	`GET /v5/clustered_observations/{srid}/{z}/{x}/{y}`	Only srid=3857 supported (Swiss grid/CH1093 21781 removed)

GET /observations — Query Parameter Changes

The following V4 query parameters have been removed or renamed:

V4 Parameter	V5 Equivalent	Notes
`ids`	`occurrence_id[in]=`	Use filter operation
`id`	`occurrence_id`	Use filter operation
`taxa`	`taxon_id[in]=`	Use filter operation
`projects`	`dataset_id[in]=`	Use filter operation
`project_id`	`dataset_id[eq]=`	Renamed
`observers`	`recorded_by_id[in]=`	Use filter operation (person IDs)
`after`	`event_date[gte]=`	Use filter operation
`before`	`event_date[lte]=`	Use filter operation
`releves`	`releve_id[in]=`	Use filter operation
`validation_statuses`	`validation[in]=`	Use filter operation
`presence`	`occurrence_status[eq]=`	Renamed
`specimen_types`	(removed)	No longer supported in V5
`cantons`	(removed)	Filter by `location_id` using administrative unit IDs
`municipalities`	`location_id[in]=`	Use administrative unit IDs
`original_taxon`	`verbatim_identification[iw_eq]=`	Use filter operation
`determinavit_cf` (comma-list)	`identification_qualifier[in]=`	Use filter operation
`taxa_relations_references`	`taxa_relations_reference_id`	Renamed (singular, filter op)
`auth` / `authorization` / `rights`	`right[eq]=`	Use filter operation
`srid`	`srid`	Still supported for output coordinate system; no longer used as a geometry filter input
`bbox`	`footprint_wkt[eq]=`	Use WKT polygon
`geometry`	`footprint_wkt[eq]=`	Use WKT polygon
`withReleve`	(removed)

New V5-only parameters:

event_type — filter by event type (releve type)
date_precision[ — filter by date precision
with_document_type — filter by document type associated with observation
taxa_group_id — filter by a group of taxa
related_resource_id — Filter by related resource id
relationship_of_resource — Filter by relationship of resource only if related_resource_id param is setted

POST/PUT Observations — Request Body Changes

V4 format wrapped the payload in an "observation" object:

POST /v4/observations
{
  "observation": {
    "project_id": 12345,
    "date": "2024-01-15T10:00:00+01:00",
    "taxon_id": 11018,
    "x": 2600000,
    "y": 1200000,
    "srid": 2056
  }
}

V5 format removes the outer "observation" wrapper and uses the direct payload:

POST /v5/observations
{
  "dataset_id": 12345,
  "event_date": "2024-01-15T10:00:00.000+01:00",
  "taxon_id": 11018,
  "basis_of_record": "HumanObservation",
  "decimal_longitude": 8.55,
  "decimal_latitude": 47.37
}

Note: decimal_longitude and decimal_latitude are read-only in V5 responses — they are computed from the observation’s geometry. For input, provide coordinates via footprint_wkt using WKT format (WGS84/EPSG:4326).

Observation Response Property Mapping

V4 Property	V5 Property	Darwin Core Term	Notes
`obs_id`	`occurrence_id`	dwc:occurrenceID
`project_id`	`dataset_id`	dwc:datasetID
`releve_type`	`event_type`	dwc:eventType
`date`	`event_date`	dwc:eventDate
`taxon_orig`	`verbatim_identification`	dwc:verbatimIdentification
`determinavit_cf`	`identification_qualifier`	dwc:identificationQualifier
`determinavit`	`identified_by`	dwc:identifiedBy
`introduced`	`degree_of_establishment`	dwc:degreeOfEstablishment
`observers`	`recorded_by_id`	dwc:recordedByID	V4: array of objects; V5: array of person IDs
`locality_descript`	`verbatim_locality`	dwc:verbatimLocality
`srid`	(removed)		Replaced by `geodetic_datum`
`x`	`decimal_longitude`	dwc:decimalLongitude
`y`	`decimal_latitude`	dwc:decimalLatitude
`geometry`	`footprint_wkt`	dwc:footprintWKT
`xy_type`	`georeference_protocol`	dwc:georeferenceProtocol
`xy_precision`	`coordinate_uncertainty_in_meters`	dwc:coordinateUncertaintyInMeters
`altitude_min`	`minimum_elevation_in_meters`	dwc:minimumElevationInMeters
`altitude_max`	`maximum_elevation_in_meters`	dwc:maximumElevationInMeters
`presence`	`occurrence_status`	dwc:occurrenceStatus
`count_unit`	`organism_quantity_type`	dwc:organismQuantityType
`abundance_code`	`organism_quantity`	dwc:organismQuantity
`phenology`	`life_stage`	dwc:lifeStage
`rem`	`occurrence_remarks`	dwc:occurrenceRemarks
`habitat_id`	`habitat`		Renamed
`cover`	`cover`		Unchanged
`vitality`	`vitality`		Unchanged
`specimen_type`	(removed)
`taxon_expert`	(removed)
`introduced_expert`	(removed)
`municipality_id`	`municipality_id`
`municipality_expert`	(removed)
`date_expert`	`date_expert`		Unchanged
`altitude_expert`	`altitude_expert`		Unchanged
`geo_expert`	(removed)
`authorizations`	(removed)
`last_modified_when`	(removed)
`v_taxon`, `v_validation_status`, `v_observers`, `v_co_canton`, `v_xy_radius`, `v_introduction_status`	(removed)
`v_presence_status`	`v_presence_status`		Unchanged
`v_native_status`	`establishment_means`		Unchanged
(new)	`basis_of_record`	dwc:basisOfRecord
(new)	`geodetic_datum`	dwc:geodeticDatum

`observers` Format Change

The observers field has been completely restructured:

V4: Array of objects containing person sub-objects:

"observers": [
  { "person": { "id": 123, "last_name": "Dupont" } }
]

V5: Array of person IDs directly:

"recorded_by_id": [123, 456]

Supplement Sub-resource Property Mapping

The /observations/{id}/supplements endpoint returns the following V5 changes:

V4 Property	V5 Property	Notes
`obs_type`	(removed)	Was always computed, not stored
`depth_min`	`minimum_depth_in_meters`
`depth_max`	`maximum_depth_in_meters`
`sexe`	`sex`
`project_obs_id`	`project_obs_id`	Unchanged
`abundance`	`abundance`	Unchanged
`pop_length`	`pop_length`	Unchanged
`pop_width`	`pop_width`	Unchanged
`plant_height`	`plant_height`	Unchanged
`releve_stratum`	`releve_stratum`	Unchanged
`cover_abs`	`cover_abs`	Unchanged
`cat_aggregation`	`cat_aggregation`	Unchanged
`substrate`	`substrate`	Unchanged

Releves

Releves (phytosociological surveys) are nested under the Observations tag in the API. All paths change from /v4/ to /v5/.

Endpoint Mapping

V4 Endpoint	V5 Endpoint
`GET /v4/releves`	`GET /v5/releves`
`POST /v4/releves`	`POST /v5/releves`
`GET /v4/releves/{id}`	`GET /v5/releves/{id}`
`PUT /v4/releves/{id}`	`PUT /v5/releves/{id}`
`DELETE /v4/releves/{id}`	`DELETE /v5/releves/{id}`

GET /releves — Query Parameter Changes

V4 Parameter	V5 Equivalent	Notes
`ids`	`id[in]=`	Use filter operation
`projects` / `project_id`	`dataset_id[in]=` / `dataset_id[eq]=`	Renamed
`observers`	`recorded_by_id[in]=`	Use filter operation
`taxa`	`taxon_id[in]=`	Use filter operation
`taxa_relations_references`	`taxa_relations_reference_id`	Renamed (singular, filter op)
`after`	`event_date[gte]=`	Use filter operation
`before`	`event_date[lte]=`	Use filter operation
`cantons`	(removed)	Filter by `location_id` using administrative unit IDs
`municipalities`	`location_id[in]=`	Use administrative unit IDs
`srid`	`srid`	Still supported for output coordinate system
`bbox`	`footprint_wkt[eq]=`	Use WKT polygon
`geometry`	`footprint_wkt[eq]=`	Use WKT polygon
`comparableId`	`id[gte]=`	Use filter operation

New V5-only parameters:

date_precision[eq]= — filter by date precision

POST/PUT Releves — Request Body

The {"releve": {...}} wrapper has been dropped in V5 — the payload is sent directly, just like observations. The property names have also changed. Pay special attention to the unit changes for height fields — trees and bushes layer heights change from centimeters to meters.

V4 example:

POST /v4/releves
{
  "releve": {
    "project_id": 1234,
    "name": "Releve_test",
    "surface": 22.5,
    "remark": "test releve",
    "trees_height": 2300,
    "bushes_height": 400,
    "herbaceous_height": 10,
    "moss_height": 1
  }
}

V5 example:

POST /v5/releves
{
  "dataset_id": 1234,
  "project": "Releve_test",
  "sample_size_value": 22.5,
  "event_remarks": "test releve",
  "tree_layer_height_in_meters": 23.0,
  "shrub_layer_height_in_meters": 4.0,
  "herb_layer_height_in_centimeters": 10,
  "moss_layer_height_in_centimeters": 1
}

Releve Response Property Mapping

⚠️ Unit change: trees_height and bushes_height were in centimeters in V4. In V5, tree_layer_height_in_meters and shrub_layer_height_in_meters are in meters. Divide by 100 when migrating stored values.

V4 Property	V5 Property	Notes
`project_id`	`dataset_id`
`name`	`project`
`surface`	`sample_size_value`
`remark`	`event_remarks`
`slope`	`inclination_in_degrees`
`total_cover`	`cover_total_in_percentage`
`trees_height` (centimeters)	`tree_layer_height_in_meters` (meters)	⚠️ Unit change: cm → m
`trees_cover`	`cover_trees_in_percentage`
`bushes_height` (centimeters)	`shrub_layer_height_in_meters` (meters)	⚠️ Unit change: cm → m
`bushes_cover`	`cover_shrubs_in_percentage`
`herbaceous_height` (centimeters)	`herb_layer_height_in_centimeters`	Same unit (cm)
`herbaceous_cover`	`cover_herbs_in_percentage`
`moss_height` (centimeters)	`moss_layer_height_in_centimeters`	Same unit (cm)
`moss_cover`	`cover_mosses_in_percentage`
`crypto_cover`	`cover_cryptogams_in_percentage`
`lichens_cover`	`cover_lichens_in_percentage`
`algae_cover`	`cover_algae_in_percentage`
`litter_cover`	`cover_litter_in_percentage`
`soil_cover`	`cover_soil_in_percentage`
`rocks_cover`	`cover_rock_in_percentage`
`water_cover`	`cover_water_in_percentage`
`quality_cover`	`quality_cover`	Unchanged
`quality_list`	`quality_list`	Unchanged
`soil_type`	`soil_type`	Unchanged
`orientation`	`orientation`	Unchanged
`soil_ph`	`soil_ph`	Unchanged
`last_modified_when`	(removed)
(new)	`sample_size_unit`	Unit of measure for sample size
(new)	`syntaxon_name`	Syntaxon name
(new)	`mosses_identified`	Boolean
(new)	`lichens_identified`	Boolean

Documents

The Documents endpoints manage files (photos, attachments) associated with observations. All paths change from /v4/ to /v5/, and V5 introduces a dedicated metadata update endpoint.

Endpoint Mapping

V4 Endpoint	V5 Endpoint	Notes
`GET /v4/docs`	`GET /v5/docs`	Several params removed (see below)
`POST /v4/docs`	`POST /v5/docs`
`GET /v4/docs/{id}`	`GET /v5/docs/{id}`
`PUT /v4/docs/{id}`	`PUT /v5/docs/{id}`
`DELETE /v4/docs/{id}`	`DELETE /v5/docs/{id}`
(none)	`PUT /v5/docs/{id}/metadatas`	New in V5 — update metadata without replacing the file

GET /docs — Query Parameter Changes

V4 Parameter	V5 Equivalent	Notes
`auth`	(removed)	Deprecated authorization level (4/7/10)
`authorization`	(removed)	Deprecated
`rights`	(removed)	Replaced by `right` (singular)
`ids`	`id[in]=`	Use filter operation
`projects`	(removed)	Use `dataset_id[in]=`
`project_id`	`dataset_id[eq]=`	Renamed
`filename`	(removed)	Use `file_name` (with filter operations)
`file_name`	`file_name`	Now uses filter operations (e.g. `file_name[iw_contains]=`)
`with_observation`	`with_observation`	Now uses filter operations (e.g. `with_observation[eq]=true`)
`right`	`right`	Unchanged
`id`	`id`	Unchanged
`dataset_id`	`dataset_id`	Unchanged

POST /docs — Request Body

The POST body for creating a document uses multipart/form-data (file upload). Rename the field inside the form:

V4 Field	V5 Field
`doc[project_id]`	`doc[dataset_id]`
`doc[doc_type]`	`doc[doc_type]`
`doc[doc_rem]`	`doc[doc_rem]`
`doc[file]`	`doc[file]`

V4 curl example:

curl -u user:pass -X POST -H "Content-Type: multipart/form-data" \
  -F doc[file]=@"/path/to/image.JPG" \
  -F doc[project_id]=12345 \
  -F doc[doc_rem]="Beautiful flower" \
  -F doc[doc_type]=894 \
  https://obs.infoflora.ch/rest/v4/docs.json

V5 curl example:

curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: multipart/form-data" \
  -F doc[file]=@"/path/to/image.JPG" \
  -F doc[dataset_id]=12345 \
  -F doc[doc_rem]="Beautiful flower" \
  -F doc[doc_type]=894 \
  https://obs.infoflora.ch/rest/v5/docs.json

Document Response Property Mapping

V4 Property	V5 Property	Notes
`id`	`id`	Unchanged
`doc_type`	`doc_type`	Unchanged
`folder_name`	`folder_name`	Unchanged
`file_name`	`file_name`	Unchanged
`original_file_name`	`original_file_name`	Unchanged
`file_url`	`file_url`	Unchanged
`thumbnail_urls`	`thumbnail_urls`	Unchanged
`mimetype`	`mimetype`	Unchanged
`project_id`	`dataset_id`	Renamed
`doc_rem`	`doc_rem`	Unchanged
`owner`	`owner`	Unchanged
`authorizations`	(removed)
`last_modified_when`	(removed)

Neophytes

The Neophytes endpoints provide summarized neophyte occurrence data. All paths change from /v4/ to /v5/. There are no response property changes — only deprecated query parameters have been cleaned up.

Endpoint Mapping

V4 Endpoint	V5 Endpoint	Auth
`GET /v4/neophytes/occurrences`	`GET /v5/neophytes/occurrences`	Requires `observation:read`
`GET /public/v4/neophytes/occurrences`	`GET /public/v5/neophytes/occurrences`	Public
`GET /public/v4/neophytes/simplified/occurrences`	`GET /public/v5/neophytes/simplified/occurrences`	Public
`GET /public/v4/neophytes/resolutions/{res}/reports`	Removed	Not available in V5
`GET /public/v4/neophytes/resolutions/{res}/x/{x}/y/{y}/reports`	Removed	Not available in V5

Query Parameter Changes

V4 Parameter	V5 Equivalent	Notes
`srid`	(removed)	Coordinates always WGS84
`bbox`	`footprint_wkt[eq]=`	Use WKT polygon
`geometry`	`footprint_wkt[eq]=`	Use WKT polygon
`taxa`	`taxon_id[in]=`	Use filter operation
`taxa_relations_references`	`taxa_relations_reference_id`	Renamed (singular, filter op)
`taxon_id`	`taxon_id`	Retained, now uses filter operations
`taxa_matching`	`taxa_matching`	Retained
`footprint_wkt`	`footprint_wkt`	Retained

Response

The NeophyteOccurrences schema is unchanged between V4 and V5. No property renaming is required.

The neophyte sub-resource accessed via /observations/{id}/neophytes is also unchanged in its response schema:

Property	Notes
`control_type`	Unchanged
`eradication`	Unchanged
`control_dtype`	Unchanged
`control_result`	Unchanged

Reminder: POST /v4/observations/{id}/neophytes is removed in V5. Use PUT /v5/observations/{id}/neophytes instead.

Taxonomy

Most of Taxonomy endpoints are public (no authentication required) and provide access to the taxonomic reference data. All paths change from /v4/ to /v5/. There are no response property changes — the migration is path changes only.

Endpoint Mapping

V4 Endpoint	V5 Endpoint
`GET /public/v4/taxonomy/names`	`GET /public/v5/taxonomy/names`
`GET /public/v4/taxonomy/names/{id}`	`GET /public/v5/taxonomy/names/{id}`
`GET /public/v4/taxonomy/taxa`	`GET /public/v5/taxonomy/taxa`
`GET /public/v4/taxonomy/taxa/{id}`	`GET /public/v5/taxonomy/taxa/{id}`
`GET /public/v4/taxonomy/taxa/profiles`	`GET /public/v5/taxonomy/taxa/profiles`
`GET /public/v4/taxonomy/taxa/{id}/profile`	`GET /public/v5/taxonomy/taxa/{id}/profile`
`GET /public/v4/taxonomy/taxa/{id}/relations`	`GET /public/v5/taxonomy/taxa/{id}/relations`
`GET /public/v4/taxonomy/references`	`GET /public/v5/taxonomy/references`
`GET /public/v4/taxonomy/references/{id}`	`GET /public/v5/taxonomy/references/{id}`

Query Parameter Changes

V4 Parameter	V5 Equivalent	Notes
`ids`	`id`	named; use filter ops
`references`	`reference_id`	named; use filter ops
`ranks`	`rank`	named; use filter ops
`status`	`taxonomic_status`	named; use filter ops
`groups`	`group`	named; use filter ops
`scientific_name`	`scientific_name`	named; use filter ops
`vernacular_name` / `common_name`	`vernacular_name`	`common_name` deprecated; use `vernacular_name` with filter ops
(new)	`fact_type`	filter by fact type
(new)	`fact_value`	filter by fact value

Response

Taxon response schemas are unchanged between V4 and V5. No property renaming is required.

Users

The Users category covers two resource types: People and Projects. Both require authentication.

People (`/people`)

Endpoint Mapping

V4 Endpoint	V5 Endpoint
`GET /v4/people`	`GET /v5/people`
`GET /v4/people/{id}`	`GET /v5/people/{id}`
(new)	`POST /v5/people`

Query Parameter Changes (`GET /people`)

V4 Parameter	V5 Equivalent	Notes
`person_id`	`id`	Use filter operations: `id[in]=1,2,3`
`lastname`	`last_name`	Renamed; use filter ops: `last_name[iw_contains]=Smith`
`firstname`	`first_name`	Renamed; use filter ops
`after`	`updated_since`	Renamed

Response

The response shape for person objects is unchanged.

Projects (`/projects`)

Endpoint Mapping

V4 Endpoint	V5 Endpoint
`GET /v4/projects`	`GET /v5/projects`
`POST /v4/projects`	`POST /v5/projects`
`GET /v4/projects/{id}`	`GET /v5/projects/{id}`
`PUT /v4/projects/{id}`	`PUT /v5/projects/{id}`
`DELETE /v4/projects/{id}`	`DELETE /v5/projects/{id}`
`GET /v4/projects/{id}/related_policies`	`GET /v5/projects/{id}/related_policies`

Query Parameter Changes (`GET /projects`)

V4 Parameter	V5 Equivalent	Notes
`auth`	`right`
`authorization`	`right`
`rights`	`right`
`name`	`project_name`	Renamed; use filter ops: `project_name[iw_contains]=`

POST Body Format Change

In V4, the project creation payload was wrapped in a data key:

// V4
POST /v4/projects
{
  "data": {
    "project_name": "My project",
    ...
  }
}

In V5, the payload is sent directly without any wrapper:

// V5
POST /v5/projects
{
  "project_name": "My project",
  ...
}

Response

Project response objects are unchanged.

Vocabulary

The Vocabulary category provides reference/lookup data. These endpoints are public (no authentication required). Significant changes include the removal of two deprecated endpoints and a critical query parameter rename.

Removed Endpoints

The following V4 endpoints are removed in V5. Use /administrative_units instead:

Removed V4 Endpoint	V5 Replacement
`GET /public/v4/cantons`	`GET /public/v5/administrative_units?unit_type[in]=canton`
`GET /public/v4/municipalities`	`GET /public/v5/administrative_units?unit_type[in]=municipality`

Endpoint Mapping

V4 Endpoint	V5 Endpoint
`GET /public/v4/administrative_units`	`GET /public/v5/administrative_units`
`GET /public/v4/habitats`	`GET /public/v5/habitats`
`GET /public/v4/vocabularies`	`GET /public/v5/vocabularies`

Query Parameter Changes

GET /vocabularies — Critical rename:

V4 Parameter	V5 Equivalent	Notes
`fieldname`	`field_name`	Critical rename — using the old name returns no results

GET /habitats — Removed parameters:

V4 Parameter	V5 Equivalent	Notes
`typoch`	(removed)	No longer supported
`name`	(removed)	No longer supported
`typology`	(removed)	No longer supported

GET /administrative_units — Removed parameters:

V4 Parameter	V5 Equivalent	Notes
`of_unit_types`	`unit_type`	Renamed; use filter operations
`ids`	`id`	Use filter operations: `id[in]=1,2,3`
`name`	`name`	Now uses filter operations: `name[iw_contains]=`
`geometry`	`footprint_wkt`	Spatial filter by geometry no longer supported on this endpoint

Response Changes

The vocabulary response objects are simplified in V5:

Property	V4	V5	Notes
`role`	Present (always `null`)	Removed	The `role` field is no longer returned

All other vocabulary properties are unchanged.

Additional Resources

V5 OpenAPI Specification: Observation V5
Filter Operations Guide: Request and Response Format
Darwin Core Standards: https://dwc.tdwg.org/

API Observation API Migration guide V4 to V5

#Migration Guide: Observation API V4 to V5

Table of Contents

#Overview

#Change Log Summary

#Added

#Changed

#Removed

#Breaking Changes

#1. Base URL Path Change

#2. Response Envelope Changes

#3. POST/PUT Request Body Format

#4. Geometry Filter Parameter Changes

#5. Deprecated Array-Style Filter Parameters Removed

#Query Parameter Filter Operations

#Filter Usage Examples

#Important Notes

#Total Values in List Responses

#V4 Behavior

#V5 Behavior

#Migration Impact

#POST and PUT Payload Format Changes

#V4 Format

#V5 Format

#Migration Steps

#Property and Parameter Renaming

#Observation Schema Property Mapping

#New Required Fields

#Deprecated Fields

#Vocabulary Field Name Changes

#Query Parameter Mapping

#Response Format Changes

#Single Resource Response

#List Response

#Category-Specific Migration

#Observations

#Endpoint Mapping

#GET /observations — Query Parameter Changes

#POST/PUT Observations — Request Body Changes

#Observation Response Property Mapping

#observers Format Change

#Supplement Sub-resource Property Mapping

#Releves

#Endpoint Mapping

#GET /releves — Query Parameter Changes

#POST/PUT Releves — Request Body

#Releve Response Property Mapping

#Documents

#Endpoint Mapping

#GET /docs — Query Parameter Changes

#POST /docs — Request Body

#Document Response Property Mapping

#Neophytes

#Endpoint Mapping

#Query Parameter Changes

#Response

#Taxonomy

#Endpoint Mapping

#Query Parameter Changes

#Response

#Users

#People (/people)

#Endpoint Mapping

#Query Parameter Changes (GET /people)

#Response

#Projects (/projects)

#Endpoint Mapping

#Query Parameter Changes (GET /projects)

#POST Body Format Change

#Response

#Vocabulary

#Removed Endpoints

#Endpoint Mapping

#Query Parameter Changes

#Response Changes

#Additional Resources

Migration Guide: Observation API V4 to V5

Overview

Change Log Summary

Added

Changed

Removed

Breaking Changes

1. Base URL Path Change

2. Response Envelope Changes

3. POST/PUT Request Body Format

4. Geometry Filter Parameter Changes

5. Deprecated Array-Style Filter Parameters Removed

Query Parameter Filter Operations

Filter Usage Examples

Important Notes

Total Values in List Responses

V4 Behavior

V5 Behavior

Migration Impact

POST and PUT Payload Format Changes

V4 Format

V5 Format

Migration Steps

Property and Parameter Renaming

Observation Schema Property Mapping

New Required Fields

Deprecated Fields

Vocabulary Field Name Changes

Query Parameter Mapping

Response Format Changes

Single Resource Response

List Response

Category-Specific Migration

Observations

Endpoint Mapping

GET /observations — Query Parameter Changes

POST/PUT Observations — Request Body Changes

Observation Response Property Mapping

`observers` Format Change

Supplement Sub-resource Property Mapping

Releves

Endpoint Mapping

GET /releves — Query Parameter Changes

POST/PUT Releves — Request Body

Releve Response Property Mapping

Documents

Endpoint Mapping

GET /docs — Query Parameter Changes

POST /docs — Request Body

Document Response Property Mapping

Neophytes

Endpoint Mapping

Query Parameter Changes

Response

Taxonomy

Endpoint Mapping

Query Parameter Changes

Response

Users

People (`/people`)

Endpoint Mapping

Query Parameter Changes (`GET /people`)

Response

Projects (`/projects`)

Endpoint Mapping

Query Parameter Changes (`GET /projects`)

POST Body Format Change

Response

Vocabulary

Removed Endpoints

Endpoint Mapping

Query Parameter Changes

Response Changes

Additional Resources