Merge pull request #51 from geoadmin/ltclm_feedback

ltclm · web-flow · commit dadfd619f5ef · 2025-10-27T14:20:10.000+01:00
PB-1969: Rework api3 docs
diff --git a/.vitepress/config.mts b/.vitepress/config.mts
@@ -139,6 +139,7 @@ function exploreDataItems(): DefaultTheme.SidebarItem[] {
   return [
     { text: "Get Layer Metadata", link: "/docs/get-layer-metadata" },
     { text: "Get Layer Attributes", link: "/docs/get-layer-attributes" },
+    { text: "Get Layer Attribute Values", link: "/docs/get-layer-attribute-values" },
     { text: "Get Layer Legend", link: "/docs/get-layer-legend" },
   ];
 }
diff --git a/docs/find-features.md b/docs/find-features.md
@@ -290,7 +290,7 @@ request='curl "https://api3.geo.admin.ch/rest/services/api/MapServer/find?"\
 "searchField=stn_label&"\
 "returnGeometry=false&"\
 "contains=false&"\
-"layerDefs={\"ch.swisstopo.amtliches-strassenverzeichnis\":\"com_fosnr=4307\"}"'
+"layerDefs=%7B%22ch.swisstopo.amtliches-strassenverzeichnis%22%3A%22com_fosnr%3D4307%22%7D"'
 example='{
   "results": [
     {
diff --git a/docs/get-elevation-profile.md b/docs/get-elevation-profile.md
@@ -29,7 +29,7 @@ This endpoint only has query parameters that modify the behavior of the request,
 ## Examples
 
 <ExampleCodeBlock
-request='$ curl https://api3.geo.admin.ch/rest/services/profile.json?geom={%22type%22:%22LineString%22,%22coordinates%22:[[2550050,1206550],[2556950,1204150],[2561050,1207950]]}'
+request='$ curl -G "https://api3.geo.admin.ch/rest/services/profile.json" --data-urlencode "geom={\"type\":\"LineString\",\"coordinates\":[[2550050,1206550],[2556950,1204150],[2561050,1207950]]}"'
 example='[
   {
     "alts": {
@@ -66,6 +66,6 @@ example='[
 />
 
 <ExampleCodeBlock
-request='$ curl https://api3.geo.admin.ch/rest/services/profile.csv?geom={"type":"LineString","coordinates":[[2550050,1206550],[2556950,1204150],[2561050,1207950]]}'
+request='$ curl -G "https://api3.geo.admin.ch/rest/services/profile.csv" --data-urlencode "geom={\"type\":\"LineString\",\"coordinates\":[[2550050,1206550],[2556950,1204150],[2561050,1207950]]}"'
 example='profile.csv'
 />
diff --git a/docs/get-layer-attribute-values.md b/docs/get-layer-attribute-values.md
@@ -0,0 +1,104 @@
+# Get Layer Attribute Values
+
+The attribute values endpoint provides a preview of possible values for a specific attribute (field) of a given vector layer.
+This is useful for building filter UIs, dropdowns, or for understanding the data distribution in a layer.
+
+<ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}/attributes/{attributeName}" method="GET" />
+
+## Request Details
+
+To interact with the Layer Attribute Values service, you need to provide specific parameters in your request.
+This endpoint only has **Path Parameters** which are mandatory.
+
+### Path Parameters
+
+| Parameters                      | Description                                                       |
+| ------------------------------- | ----------------------------------------------------------------- |
+| **layerBodId (required)**       | The technical name or the layer ID.                              |
+| **attributeName (required)**    | The name of the attribute for which to retrieve values.          |
+
+## Response Details
+
+The endpoint returns a **JSON** with information about the attribute values for the specified layer and attribute. The response includes an array of values. For attributes of type `DATE`, `INTEGER`, `NUMERIC` the endpoint returns the minimum and maximum values as a two-element array. For other attribute types the endpoint returns up to 50 distinct values, sorted alphabetically.
+
+Here is a description of the data contained in the response.
+
+| **Field**        | **Description**                                                      |
+| ---------------- | -------------------------------------------------------------------- |
+| `values`         | Array of attribute values                                            |
+
+## Examples
+
+Get distinct values for the `egid` attribute from layer `ch.bfs.gebaeude_wohnungs_register`:
+
+<ExampleCodeBlock 
+request='curl https://api3.geo.admin.ch/rest/services/api/MapServer/ch.bfs.gebaeude_wohnungs_register/attributes/egid'
+example='{
+    "values": [
+        "1",
+        "10",
+        "100",
+        "10000",
+        "1000001",
+        "1000002",
+        "1000007",
+        "1000008",
+        "1000009",
+        "100001",
+        "1000011",
+        "1000012",
+        "1000013",
+        "1000014",
+        "1000015",
+        "1000016",
+        "1000017",
+        "1000018",
+        "1000019",
+        "100002",
+        "1000020",
+        "1000021",
+        "1000022",
+        "1000024",
+        "1000026",
+        "1000027",
+        "1000028",
+        "1000029",
+        "100003",
+        "1000030",
+        "1000031",
+        "1000032",
+        "1000033",
+        "1000034",
+        "1000035",
+        "1000036",
+        "1000038",
+        "1000039",
+        "1000040",
+        "1000041",
+        "1000042",
+        "1000043",
+        "1000044",
+        "1000045",
+        "1000046",
+        "1000047",
+        "1000048",
+        "1000049",
+        "100005",
+        "1000050"
+    ]
+}'
+/>
+
+<br>
+
+Get the min and max value for the `garea` attribute from layer `ch.bfs.gebaeude_wohnungs_register`:
+
+<ExampleCodeBlock 
+request='curl "https://api3.geo.admin.ch/rest/services/api/MapServer/ch.bfs.gebaeude_wohnungs_register/attributes/garea"'
+example='{
+    "values": [
+        1,
+        99431
+    ]
+}'
+/>
diff --git a/docs/get-layer-metadata.md b/docs/get-layer-metadata.md
@@ -27,7 +27,7 @@ For each layer, there are some general identification properties
 | ------------ | --------------------------------------------------------------------------------------- |
 | `name`       | The name of the layer (short name, less than 30 characters).                            |
 | `fullName`   | The layer's full name (not necessarily different from `name`).                          |
-| `idGeoCat`   | The associated metadata ID in [GeoCat](http://www.geocat.ch/geonetwork/srv/eng/geocat). |
+| `idGeoCat`   | The associated metadata ID in [GeoCat](https://www.geocat.ch). |
 | `layerBodId` | The technical name or BOD ID.                                                           |
 
 and attributes listing more metaadata
@@ -36,20 +36,20 @@ and attributes listing more metaadata
 | ------------ | --------------------------------------------------------------------------------------- |
 | `wmsResource` | The WMS resource of the layer. |
 | `scaleLimit` | The scale at which the layer is valid. |
-| `inspireUpperAbstract` | The abstract of the [INSPIRE](https://www.geo.admin.ch/en/geo-information-switzerland/geodata-index-inspire.html) category (first level). |
-| `inspireName` | The name of the [INSPIRE](https://www.geo.admin.ch/en/geo-information-switzerland/geodata-index-inspire.html) category. |
+| `inspireUpperAbstract` | The abstract of the [INSPIRE](https://www.geo.admin.ch/en/inspire-services) category (first level). |
+| `inspireName` | The name of the [INSPIRE](https://www.geo.admin.ch/en/inspire-services) category. |
 | `urlDetails` | Link to the official details page. |
 | `bundCollectionNumber` | The collection number. |
 | `dataOwner` | The data owner. |
-| `inspireAbstract` | The abstract of the [INSPIRE](https://www.geo.admin.ch/en/geo-information-switzerland/geodata-index-inspire.html) category the layer belongs to. |
+| `inspireAbstract` | The abstract of the [INSPIRE](https://www.geo.admin.ch/en/inspire-services) category the layer belongs to. |
 | `abstract` | The layer abstract. |
 | `wmsContactAbbreviation` | The abbreviation contact for the WMS resource. |
 | `downloadUrl` | The link where the data can be downloaded. |
 | `maps` | The projects in which this layer is accessible. |
 | `wmsContactName` | The contact name for the WMS resource. |
 | `dataStatus` | The date of the latest data update. |
 | `bundCollectionName` | The collection name. |
-| `inspireUpperName` | The name of the [INSPIRE](https://www.geo.admin.ch/en/geo-information-switzerland/geodata-index-inspire.html) category (first level). |
+| `inspireUpperName` | The name of the [INSPIRE](https://www.geo.admin.ch/en/inspire-services) category (first level). |
 | `urlApplication` | The application where this layer is published. |
 | `tileInfo` | WMTS general information in JSON format. Note that this section is always identical and is not tied to a particular "map" like in ESRI specifications. |
 
@@ -71,7 +71,7 @@ $ curl https://api3.geo.admin.ch/rest/services/api/MapServer?searchText=wasser
 
 <br>
 
-Find a layer by [geocat ID](http://www.geocat.ch/geonetwork/srv/eng/geocat):
+Find a layer by [geocat ID](https://www.geocat.ch):
 
 ```sh
 $ curl https://api3.geo.admin.ch/rest/services/api/MapServer?searchText=f198f6f6-8efa-4235-a55f-99767ea0206c
diff --git a/docs/get-point-height.md b/docs/get-point-height.md
@@ -5,7 +5,7 @@ Retrieve the elevation for a specific coordinate.
 <ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/height" method="GET" />
 ::: info
 Outside of Switzerland a 10m grid elevation model is used. It is a combined digital elevation model consisting of elevation models from mapping agencies of France, Italy, Austria, Bavaria and Baden-Württemberg and derived with a resolution of 10m. The extend
-covers XMin: 2443000 YMin: 1024000 XMax: 2895000 YMax: 1340000
+covers XMin: 2'385'000 YMin: 974'000 XMax: 2'935'000 YMax: 1'404'000
 
 See [Height models](https://www.swisstopo.admin.ch/en/geodata/height/alti3d.html) for more details about data used by this service.
 :::
diff --git a/docs/identify-features.md b/docs/identify-features.md
@@ -5,7 +5,7 @@ Use this endpoint to discover features at a specific location.
 <ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/api/MapServer/identify" method="GET" />
 
 ::: warning
-No more than 50 features can be retrieved per request.
+No more than 200 features can be retrieved per request.
 :::
 
 ## Request Details
@@ -26,6 +26,7 @@ This endpoint only has query parameters that modify the behavior of the request,
 | **returnGeometry (optional)**        | This parameter defines whether the geometry is returned or not. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                            |
 | **geometryFormat (optional)**        | Returned geometry format. Defaults to ESRI geometry format. Supported values are: `esrijson` or `geojson`.                                                                                                                                                                                                                                                                                                                     |
 | **offset (optional)**                | Offset for the first record (if more than 50 records).                                                                                                                                                                                                                                                                                                                                                                         |
+| **limit (optional)**                 | The maximum number of results to retrieve per request (default limit=50, max limit=200)                                                                                                                                                                                                                                                                                                                                         |
 | **sr (optional)**                    | The spatial reference. Supported values: `21781` (LV03), `2056` (LV95), `4326` (WGS84), and `3857` (Web Pseudo-Mercator). Defaults to `21781`.                                                                                                                                                                                                                                                                                 |
 | **lang (optional)**                  | The language. Supported values: `de`, `fr`, `it`, `rm`, `en`. Defaults to `de`.                                                                                                                                                                                                                                                                                                                                                |
 | **layerDefs (optional)**             | Filter features with an expression. Syntax: `{ "<layerId>" : "<layerDef1>" }` where `<layerId>` must correspond to the layer specified in `layers`. See below for more details.                                                                                                                                                                                                                                                                            |
diff --git a/docs/search.md b/docs/search.md
@@ -79,7 +79,7 @@ Here is a description of the response's data.
 | **Field** | **Description**                                                                                                                                                    |
 | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `id`      | This is an internal value and therefore shouldn't be used.                                                                                                         |
-| `weight`  | The `weight` is dynamically computed according to the `searchText` that is provided. It informs the user about how close an entry is to the provided `searchText`. |
+| `weight`  | The `weight` attribute represents the similarity between the search query and the index. **For location search**: `weight = 100` typically indicates exact matches, `weight < 100` indicates partial/wildcard matches, `weight > 1000` indicates fuzzy search results. Since the search engine combines multiple ranking methods, weight values should be used as general guidelines only. **Important**: Absolute weight values may change without backward compatibility. |
 
 **Attributes:**
 | **Field** | **Description** |
diff --git a/docs/vector-tiles.md b/docs/vector-tiles.md
@@ -67,9 +67,9 @@ curl -o demo.pbf https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v
 ```
 
 ## GetTileSets
+MBTiles are used for storing tiled map data in SQLite databases for immediate or offline usage and for efficient transfer.
 
-MBTiles for storing tiled map data in SQLite databases for immediate or offline usage and for efficient transfer.
-A MBtileSet request is in the following form:
+TileSet request is in the following form:
 
 <ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{layerName}.mbtiles" method="GET" />
 
@@ -80,6 +80,10 @@ A MBtileSet request is in the following form:
 
 A GetTileSet request for a `.mbtiles` file in the Base Map dataset:
 
+::: warning
+The file that is being downloaded in the example below is approximately **900MB** in size.
+:::
+
 ```http
 curl -o demo.mbtiles https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/ch.swisstopo.base.vt.mbtiles
 ```
@@ -100,7 +104,7 @@ The URL of the metadata file is:
 A Metadata request for the Base Map dataset:
 
 <ExampleCodeBlock
-request="curl https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json"
+request="curl --compressed https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json"
 example='{
   "basename": "tiles/ch.swisstopo.base.vt/v1.0.0",
   "name": "Basiskarte_v1.0.0",
diff --git a/docs/wms.md b/docs/wms.md
@@ -7,15 +7,39 @@ outline: [2, 3]
 Federal offices make part of their data available via the WMS - Federal Spatial Data Infrastructure (FSDI) service.
 The data layers currently available in the WMS-FSDI correspond, with a few exceptions, to the geodata that are presented in [map.geo.admin.ch](https://map.geo.admin.ch).
 
+## Set the Language  
+
+The default response language of all WMS endpoints is German (`de`).  
+There are two ways to set a different language:  
+
+1. As a path parameter like in `https://wms.geo.admin.ch/{Lang}/?SERVICE=WMS&...`  
+2. As a query parameter `Lang` like in `https://wms.geo.admin.ch/?SERVICE=WMS&...&Lang=fr&...`  
+
+When both are present, the path parameter takes precedence over the query string parameter.  
+
+The supported values are: `de` (German), `fr` (French), `it` (Italian), `rm` (Rumantsch), `en` (English). Defaults to `de` if not specified
+
+::: info
+The language parameter (both path and query string variants) is supported by all WMS requests: `GetCapabilities`, `GetMap`, `GetFeatureInfo`, and `GetLegendGraphic`. This allows you to receive localized responses and layer information in your preferred language.
+:::
+
+<ApiCodeBlock url="https://wms.geo.admin.ch/{language}/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities&LANG=<Lang>" method="GET" />
+
 ## GetCapabilities
 
-The GetCapabilities document provides information about the service, along with layer description, both in German and French.
+The GetCapabilities document provides comprehensive information about the WMS service, including detailed layer descriptions available in all four Swiss national languages and English.
+
+### Path Parameters
+
+| Parameter                 | Description                         |
+| ------------------------- | ----------------------------------- |
+| **Lang** *(optional)*     | Specifies the language for the service response. |
 
-<ApiCodeBlock url="https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities&LANG=<Lang>" method="GET" />
+### Query Parameters
 
-| **Parameter**   | **Description**                                               |
+| Parameter       | Description                                                   |
 | --------------- | ------------------------------------------------------------- |
-| Lang (optional) | The language. Supported values: `de`, `fr` (Defaults to `de`) |
+| **Lang** *(optional)* | Specifies the language for the service response. |
 
 ### Supported Projections
 
diff --git a/docs/wmts.md b/docs/wmts.md
@@ -18,7 +18,7 @@ The GetCapabilities document provides information about the service, along with
 
 | **Parameter**   | **Description**                                               |
 | --------------- | ------------------------------------------------------------- |
-| Lang (optional) | The language. Supported values: `de`, `fr` (Defaults to `de`) |
+| Lang (optional) | Specifies the language for the service response. Supported values: `de` (German), `fr` (French), `it` (Italian), `rm` (Rumantsch), `en` (English). Defaults to `de` if not specified. |
 
 ### Supported Projections
 
@@ -40,8 +40,7 @@ Notes:
 
 - Partly due to a limitation of the WMTS 1.0.0 recommendations, each _projection_ has its own `GetCapabilities` document.
 - The same timestamps are available in all projections. New timestamps are added to the former ones.
-- The layer _ch.kantone.cadastralwebmap-farbe_ uses a WMS service as
-  its source.
+- The layer _ch.kantone.cadastralwebmap-farbe_ is sourced from a WMS service. For optimal quality and accuracy, use this layer only in EPSG:2056 and EPSG:21781. Using other projections may result in reduced quality due to reprojection limitations.
 - All layers are available at all scales. You have to check
   for which **tileMatrixSets** a particular layer is defined. Your
   WMTS client may either stretch the tiles from the last available
diff --git a/docs/xyz.md b/docs/xyz.md

Original file line number	Diff line number	Diff line change
`@@ -139,6 +139,7 @@ function exploreDataItems(): DefaultTheme.SidebarItem[] {`
`139`	`139`	`return [`
`140`	`140`	`{ text: "Get Layer Metadata", link: "/docs/get-layer-metadata" },`
`141`	`141`	`{ text: "Get Layer Attributes", link: "/docs/get-layer-attributes" },`
	`142`	`+ { text: "Get Layer Attribute Values", link: "/docs/get-layer-attribute-values" },`
`142`	`143`	`{ text: "Get Layer Legend", link: "/docs/get-layer-legend" },`
`143`	`144`	`];`
`144`	`145`	`}`
Original file line number	Diff line number	Diff line change
`@@ -290,7 +290,7 @@ request='curl "https://api3.geo.admin.ch/rest/services/api/MapServer/find?"\`
`290`	`290`	`"searchField=stn_label&"\`
`291`	`291`	`"returnGeometry=false&"\`
`292`	`292`	`"contains=false&"\`
`293`		`-"layerDefs={\"ch.swisstopo.amtliches-strassenverzeichnis\":\"com_fosnr=4307\"}"'`
	`293`	`+"layerDefs=%7B%22ch.swisstopo.amtliches-strassenverzeichnis%22%3A%22com_fosnr%3D4307%22%7D"'`
`294`	`294`	`example='{`
`295`	`295`	`"results": [`
`296`	`296`	`{`