Skip to content

PB-1969: Rework api3 docs #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ltclm merged 12 commits into from
Oct 27, 2025
Merged

PB-1969: Rework api3 docs #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
5abde59
PB-1969: Fix GeoCat links and INSPIRE category references
ltclm Oct 6, 2025
54070c7
PB-1969: Update identify-features.md
ltclm Oct 6, 2025
d5b2463
PB-1969: Fix layerDefs formatting in find-features.md
ltclm Oct 6, 2025
47eff19
PB-1969: Update feature retrieval limit from 50 to 200
ltclm Oct 6, 2025
5b80b0a
PB-1969: add documentation about layer attribute values endpoint
ltclm Oct 6, 2025
4f8d5ba
PB-1969: improve weight attribute documentation
ltclm Oct 6, 2025
7b54dbd
PB-1969: service-alti height / profile fix examples
ltclm Oct 7, 2025
d9af023
PB-1969: service-wms add lang parameter path vs query string document…
ltclm Oct 7, 2025
ac67460
PB-1969: service-wmts update language documentation, add note about c…
ltclm Oct 7, 2025
7bebec6
PB-1969: xyz update wmts getcap links
ltclm Oct 7, 2025
c1a0117
PB-1969: vectortiles fix examples, add warning about filesize
ltclm Oct 7, 2025
522f8eb
PB-1969: feedback ltstx
ltclm Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .vitepress/config.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" },
];
}
Expand Down
2 changes: 1 addition & 1 deletion docs/find-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
{
Expand Down
4 changes: 2 additions & 2 deletions docs/get-elevation-profile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -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'
/>
104 changes: 104 additions & 0 deletions docs/get-layer-attribute-values.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
]
}'
/>
12 changes: 6 additions & 6 deletions docs/get-layer-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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. |

Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/get-point-height.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::
Expand Down
3 changes: 2 additions & 1 deletion docs/identify-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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. |
Expand Down
2 changes: 1 addition & 1 deletion docs/search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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** |
Expand Down
10 changes: 7 additions & 3 deletions docs/vector-tiles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" />

Expand All @@ -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
```
Expand All @@ -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",
Expand Down
32 changes: 28 additions & 4 deletions docs/wms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
5 changes: 2 additions & 3 deletions docs/wmts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
Loading
Loading