# API REST Services¶

Most services are implementing or are heavily inspired by ESRI GeoServices REST Specification or by the Open Geospatial Consortium (OGC).

This service provides metadata for all the available layers in the GeoAdmin API.

### URL¶

https://api3.geo.admin.ch/rest/services/api/MapServer


### Input Parameters¶

RESTFul interface is available.

Parameters Description
searchText (optional) The text to search for in the layer description.
lang (optional) The language. Supported values: de, fr, it , rm, en. Defaults to “de”.
sr (optional) The spatial reference. Supported values: 21781 (LV03), 2056 (LV95). Defaults to “21781”.
callback (optional) The name of the callback function.

### Response syntax¶

Here is an example of response.

{
"layers": [
{
"name": "Temperature monitoring stations",
"fullName": "Water temperature monitoring stations",
"idGeoCat": "4f10c35a-8fac-4000-ab6d-7a294284059a",
"layerBodId": "ch.bafu.hydrologie-wassertemperaturmessstationen",
"attributes": {
"scaleLimit": "-",
"inspireUpperAbstract": "Environnement, biology and geology | Space and population",
"inspireName": "Environmental monitoring facilities | Human health and safety",
"abstract": "...",
"inspireAbstract": "...",
"dataOwner": "Federal Office for the Environment FOEN",
"wmsContactAbbreviation": "swisstopo",
"maps": "...",
"wmsContactName": "Federal Office of Topography swisstopo",
"dataStatus": "20130322",
"inspireUpperName": "Environment biology and geology | Space and population",
}
}
],
"tileInfo": {
"origin": {
"y": 350000,
"x": 420000,
"spatialReference": {
"wkid": 21781
}
},
"rows": 256,
"format": "PNG,JPEG",
"lods": [
{
"height": 1,
"width": 1,
"scale": 14285750.5715,
"resolution": 4000,
"level": 0
}, ...
{
"height": 12500,
"width": 18750,
"scale": 357.1425,
"resolution": 0.1,
"level": 28
}
],
"spatialReference": {
"wkid": 21781
},
"cols": 256,
"dpi": 96,
"compressionQuality": ""
},
"description": "Configuration for the map (topic) api",
"fullExtent": {
"xmin": 42000,
"ymin": 30000,
"ymax": 350000,
"xmax": 900000,
"spatialReference": {
"wkid": 21781
}
},
"units": "esriMeters",
"initialExtent": {
"xmin": 458000,
"ymin": 76375,
"ymax": 289125,
"xmax": 862500,
"spatialReference": {
"wkid": 21781
}
},
"spatialReference": {
"wkid": 21781
},
"capabilities": "Map",
}


Here is a description of the data one can find in the above response.

• layers: a list of object literals representing the layers
• 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
• layerBodId: the technical name or BOD id
• attributes: the metadata attributes associated to a given layer
• wmsResource: the WMS resource of the layer
• scaleLimit: the scale at which the layer is valid
• inspireUpperAbstract: the abstract of the INSPIRE category (first level)
• inprireName: the name of the INSPIRE category
• urlDetails: link to the official details page
• bundCollectionNumber: the collection number
• dataOwner: the data owner
• inprieAbstract: the abstract of the INSPIRE category the layer belongs to
• absctract: the layer absctract
• wmsContactAbbreviation: the abbreviation contact for the WMS resource
• 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 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.

## Layer Attributes¶

This service is used to expose the attributes names that are specific to a layer. This service is especially useful when combined wit h the find service.

### URL¶

https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}


### Input Parameters¶

RESTFul interface is available.

Parameters Description
lang (optional) The language. Supported values: de, fr, it , rm, en. (Defaults to de if browser language does not match any of the possible values)
callback (optional) The name of the callback function.

### Example¶

Get the all the available attributes names of the municipal boundaries: https://api3.geo.admin.ch/rest/services/api/MapServer/ch.swisstopo.swissboundaries3d-gemeinde-flaeche.fill

## Legend Resource¶

With a layer ID (or technical name), this service can be used to retrieve a legend.

### URL¶

https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}/legend


### Input Parameters¶

No css styling is provided per default so that you can use your own.

Parameters Description
lang (optional) The language. Supported values: de, fr, it , rm, en. (Defaults to de if browser language does not match any of the possible values)
callback (optional) The name of the callback function.

## Identify Features¶

This service can be used to discover features at a specific location. Here is a complete list of layers for which this service is available.

### URL¶

https://api3.geo.admin.ch/rest/services/api/MapServer/identify


### Input Parameters¶

No more than 50 features can be retrieved per request.

Parameters Description
geometry (required) The geometry to identify on. The geometry is specified by the geometry type. This parameter is specified as a separated list of coordinates. The simple syntax (comma separated list of coordinates) and the complex one can be used. (ESRI syntax for geometries)
geometryType (required) The type of geometry to identify on. Supported values are: esriGeometryPoint or esriGeometryPolyline or esriGeometryPolygon or esriGeometryEnvelope.
layers (optional) The layers to perform the identify operation on. Per default query all the layers in the GeoAdmin API. Notation: all:”comma separated list of technical layer names”.
mapExtent (required) The extent of the map. (minx, miny, maxx, maxy).
imageDisplay (required) The screen image display parameters (width, height, and dpi) of the map. The mapExtent and the imageDisplay parameters are used by the server to calculate the the distance on the map to search based on the tolerance in screen pixels.
tolerance (required) The tolerance in pixels around the specified geometry. This parameter is used to create a buffer around the geometry. Therefore, a tolerance of 0 deactivates the buffer creation.
returnGeometry (optional) This parameter defines whether the geometry is returned or not. Default to “true”.
geometryFormat (optional) Returned geometry format. Default to ESRI geometry format. Supported values are: “esrijson” or “geojson”.
sr (optional) The spatial reference. Supported values: 21781 (LV03), 2056 (LV95). Defaults to “21781”.
lang (optional) The language. Supported values: de, fr, it , rm, en. Defaults to “de”.
callback (optional) The name of the callback function.

### Examples¶

Equation:

SearchRadius = Max(MapWidthInMeters / ScreenWidthInPx, MapHeightInMeters / ScreenHeightInPx) * toleranceInPx


For instance if one wants a radius of 5 meters:

Max(100 / 100, 100 / 100) * 5 = 5


So you would set:

mapExtent=0,0,100,100&imageDisplay=100,100,100&tolerance=5&geometryType=esriGeometryPoint&geometry=548945,147956 to perform an identify request with a search radius of 5 meters around a given point.


## Find¶

This service is used to search the attributes of features. Each result include a feature ID, a layer ID, a layer name, a geometry (optionally) and attributes in the form of name-value pair. Here is a complete list of layers for which this service is available.

### URL¶

https://api3.geo.admin.ch/rest/services/api/MapServer/find


### Input Parameters¶

One layer, one search text and one attribute.

Parameters Description
layer (required) A layer ID (only one layer at a time can be specified).
searchText (required) The text to search for (one can use numerical values as well).
searchField (required) The name of the field to search (only one search field can be searched at a time).
contains (optional) If false, the operation searches for an exact match of the searchText string. An exact match is case sensitive. Otherwise, it searches for a value that contains the searchText string provided. This search is not case sensitive. The default is true.
geometryFormat (optional) Returned geometry format. Default to ESRI geometry format. Supported values are: “esrijson” or “geojson”.
returnGeometry (optional) This parameter defines whether the geometry is returned or not. Default to “true”.
sr (optional) The spatial reference. Supported values: 21781 (LV03), 2056 (LV95). Defaults to “21781”.
lang (optional) The language. Supported values: de, fr, it , rm, en. Defaults to “de”.
callback (optional) The name of the callback function.

## Feature Resource¶

With an ID (or several in a comma separated list) and a layer ID (technical name), this service can be used to retrieve a feature resource. Here is a complete list of layers for which this service is available.

### URL¶

https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}/{featureId},{featureId}


### Input Parameters¶

RESTFul interface is available.

Parameters Description
geometryFormat (optional) Returned geometry format. Default to ESRI geometry format. Supported values are: “esrijson” or “geojson”.
returnGeometry (optional) This parameter defines whether the geometry is returned or not. Default to “true”.
sr (optional) The spatial reference. Supported values: 21781 (LV03), 2056 (LV95). Defaults to “21781”.
lang (optional) The language. Supported values: de, fr, it , rm, en. Defaults to “de”.
callback (optional) The name of the callback function.

## Htmlpopup Resource¶

With an ID and a layer ID (technical name), this service can be used to retrieve an html popup. An html popup is an html formatted representation of the textual information about the feature. Here is a complete list of layers for which this service is available.

### URL¶

https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}/{featureId}/htmlPopup


### Input Parameters¶

No css styling is provided per default so that you can use your own.

Parameters Description
lang (optional) The language. Supported values: de, fr, it , rm, en. Defaults to “de”.
sr (optional) The spatial reference. Supported values: 21781 (LV03), 2056 (LV95). Defaults to “21781”.
callback (optional) The name of the callback function.

## Height¶

This service allows to obtain elevation information for a point. See Height models for more details about data used by this service.

Warning

### URL¶

https://api3.geo.admin.ch/rest/services/height


### Input Parameters¶

RESTFul interface is available.

Parameters Description
easting (required) The easting coordinate in LV03 (EPSG:21781) or LV95 (EPSG:2056)
northing (required) The northing coordinate in LV03 (EPSG:21781) or LV95 (EPSG:2056)
elevation_model (optional) The elevation model. Three elevation models are available DTM25, DTM2 (swissALTI3D) and COMB (a combination of DTM25 and DTM2). Default to “DTM25”.
sr(optional) The reference system to use (EPSG code). Valid values are 2056 (for LV95) and 21781 (for )LV03). If not given, trying to guess which one to use.
callback (optional) The name of the callback function.

## Profile¶

This service allows to obtain elevation information for a polyline in CSV format. See Height models for more details about data used by this service.

Warning

### URL¶

https://api3.geo.admin.ch/rest/services/profile.json (for json format)


### Input Parameters¶

RESTFul interface is available.

Parameters Description
geom (required) A GeoJSON representation of a polyline (type = LineString). The LineString should not have more than 6‘000 coordinates.
sr (optional) The reference system to use (EPSG code). Valid value are 2056 (for LV95) and 21781 (for LV03). Strongly advised to set one, but if not given, trying to guess which one to use.
elevation_models (optional) A comma separated list of elevation models. Three elevation models are available DTM25, DTM2 (swissALTI3D) and COMB (a combination of DTM25 and DTM2). Default to “DTM25”.
nb_points (optional) The number of points used for the polyline segmentation. Default “200”.
offset (optional) The offset value (INTEGER) in order to use the exponential moving algorithm . For a given value the offset value specify the number of values before and after used to calculate the average.
callback (optional) Only available for profile.json. The name of the callback function.

## WMTS¶

A RESTFul implementation of the WMTS OGC standard. For detailed information, see WMTS OGC standard

Warning

In order to have access to the WMTS, you require to register to swisstopo web access - Inscription form (in German), even if most layers are free to use. See Which layers are available ? for a list of all available layers.

Note

Only the RESTFul request encoding to GetTile is implemented, not the GetLegend and GetFeatureInfo. No KVP and SOAP request encoding is supported.

### GetCapabilities¶

The GetCapabilites document provides informations about the service, along with layer description, both in german and french.

### GetTile¶

<Scheme>://<ServerName>/<ProtocoleVersion>/<LayerName>/<Stylename>/<Time>/<TileMatrixSet>/<TileSetId>/<TileRow>/<TileCol>.<FormatExtension>


with the following parameters:

Parameter Example Explanation
Scheme http or https The scheme type
Version 1.0.0 WMTS protocol version
Layername ch.bfs.arealstatistik-1997 See the WMTS GetCapabilities document.
StyleName default Only default is supported.
Time 2010, 2010-01 Date of tile generation in (ISO-8601) or logical value like current. A list of available values is provided in the GetCapabilities document under the <Dimension> tag. We recommend to use the value under the <Default> tag. Note that these values might change frequently - check for updates regularly.
TileMatrixSet 2056 (constant) EPSG code for LV03/CH1903
TileSetId 22 Zoom level (see below)
TileRow 236
TileCol 284
FormatExtension png Mostly png, except for some raster layer (pixelkarte and swissimage)

The <TileMatrixSet> 21781 is as follow defined:

MinX              420000
MaxX              900000
MinY               30000
MaxY              350000
TileWidth            256


With the <tileOrigin> in the top left corner of the bounding box.

Resolution [m] Zoomlevel Map zoom Tile width m Tiles X Tiles Y Tiles Approx. scale at 96 dpi per zoom level
4000 0   1024000 1 1 1
3750 1   960000 1 1 1
3500 2   896000 1 1 1
3250 3   832000 1 1 1
3000 4   768000 1 1 1
2750 5   704000 1 1 1
2500 6   640000 1 1 1
2250 7   576000 1 1 1
2000 8   512000 1 1 1
1750 9   448000 2 1 2
1500 10   384000 2 1 2
1250 11   320000 2 1 2
1000 12   256000 2 2 4
750 13   192000 3 2 6
650 14 0 166400 3 2 6 1 : 2‘456‘694
500 15 1 128000 4 3 12 1 : 1‘889‘765
250 16 2 64000 8 5 40 1 : 944‘882
100 17 3 25600 19 13 247 1 : 377‘953
50 18 4 12800 38 25 950 1 : 188‘976
20 19 5 5120 94 63 5‘922 1 : 75‘591
10 20 6 2560 188 125 23‘500 1 : 37‘795
5 21 7 1280 375 250 93‘750 1 : 18‘898
2.5 22 8 640 750 500 375‘000 1 : 9‘449
2 23 9 512 938 625 586‘250 1 : 7‘559
1.5 24   384 1250 834 1‘042‘500
1 25 10 256 1875 1250 2‘343‘750 1 : 3‘780
0.5 26 11 128 3750 2500 9‘375‘000 1 : 1‘890
0.25 27 12 64 7500 5000 37‘500‘000 1 : 945
0.1 28 13 25.6 18750 12500 234‘375‘000 1 : 378

Notes

1. The projection for the tiles is LV95 (EPSG:2056). Other projection are supported, see further down.
2. The tiles are generated on-the-fly and stored in a cache (hundreds of requests per second)
3. The zoom level 24 (resolution 1.5m) has been generated, but is not currently used in the API.
4. The zoom levels 27 and 28 (resolution 0.25m and 0.1m) are only available for a few layers, e.g. swissimage or cadastral web map. For the others layers it is only a client zoom (tiles are stretched).
5. You have to use the <ResourceURL> to construct the GetTile request.
6. Axis order: for historical reasons, EPSG:21781 WMTS tiles use the non-standard row/col order, while all other projections use the usual col/row order. However, most desktop GIS allow you to either use the advertized order or to override it.
7. The tiles of a given layer might be updated withtout resulting in a new <Time> dimension in the GetCapabilities dimension. In case your application is caching tiles locally, you need to invalidate your local cache for this layer. To check the latest change of any layer, use the Cache Update service.

## Supported projections¶

Four projections are supported. The same tiles are offered in four other tilematrixsets/projection.

Note:

• Partly due to a limitation of the WTMS 1.0.0 recommendations, each projection has its own GetCapabilities document.
• The same access restrictions apply as above.
• The same timestamps are available in all projection. New timestamp are added to the former ones.
• The layer ch.kantone.cadastralwebmap-farbe uses a WMS service as its source.
• Note that all layers are available at all scales. You have to check for which tileMatrixSets a particuliar layer is defined. Your WMTS client may either stretch the tiles from the last available level or display nothing.

## Cache Update¶

As noted in the WMTS service, the Tiles of a given <Time> dimension might be updated for technical reasons. If you are caching Tiles locally, this might result in your cache being outdated. Use the Cache Update service to query the Date of the last update for a given layer. If your cache is older than the returned Date, you have to clear your local cache.

### URL¶

https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}/cacheUpdate


## Terrain Service¶

A RESTFul implementation of “CesiumQuantized Mesh terrain service. Terrain tiles are served according to the Tile Map Service (TMS) layout and global-geodetic profile. In order to access the terrain tiles, you require to fill a swisstopo web access - Inscription form (in German).

The layer.json file determines which terrain tiles are available.

### Parameters¶

A request is in the form:

https://<ServerName>/<ProtocoleVersion>/ch.swisstopo.terrain.3d/<Stylename>/<Time>/<TileMatrixSetId>/<Zoom>/<X>/<Y>.<FormatExtension>


with the following parameters:

Parameter Example Explanation
Version 1.0.0 The terrain service protocol version
Layername ch.swisstopo.terrain.3d (constant) The name of the terrain layer. (only one terrain layer is available)
StyleName default mostly constant
Time 2015311201 Date of tile generation in (ISO-8601).
TileMatrixSet 4326 (constant) EPSG code for WGS84
TileSetId 12 Zoom level (see below)
X 4309 The longitue index
Y 3111 The latitude index
FormatExtension terrain The file extension (a gzipped binary terrain file)

The <TileMatrixSet> 4326 is defined as follow:

MinX              5.013926957923385
MaxX              11.477436312994008
MinY              45.35600133779394
MaxY              48.27502358353741
TileWidth         256


With the <tileOrigin> in the bottom left corner of the bounding box.

Resoultion [m/pixel at equator] Zoomlevel Availability
78271.80469 0 [-180, -90, 90, 180]
39135.90234 1 [-180, -90, 90, 180]
19567.95117 2 [-180, -90, 90, 180]
9783.975586 3 [-180, -90, 90, 180]
4891.987793 4 [-180, -90, 90, 180]
2445.993896 5 [-180, -90, 90, 180]
1222.996948 6 [-180, -90, 90, 180]
611.4984741 7 [-180, -90, 90, 180]
305.749237 8 Ranges as defined in the layer.json file
152.8746185 9 Ranges as defined in the layer.json file
76.43730927 10 Ranges as defined in the layer.json file
38.21865463 11 Ranges as defined in the layer.json file
19.10932732 12 Ranges as defined in the layer.json file
9.554663658 13 Ranges as defined in the layer.json file
4.777331829 14 Ranges as defined in the layer.json file
2.388665915 15 Ranges as defined in the layer.json file
1.194332957 16 Ranges as defined in the layer.json file
0.597166479 17 Ranges as defined in the layer.json file

## 3D Tiles¶

A RESTFul implementation of “Cesium3D Tiles specification. In order to access the 3D tiles, you require a swisstopo web access - Inscription form .

The tileset.json file describes the available set of tiles. In order to use this service, you must currently use a fork of CesiumJS, the 3d-tiles branch. Stay informed and have a look at the current RoadMap for 3D Tiles.

Currently, 3 technical layers (ch.swisstopo.swisstlm3d.3d, ch.swisstopo.swissnames3d.3d, ch.swisstopo.vegetation.3d) are available and they contains all available 3D objects. Additional layers will be available in the future. Partial 3D buildings model coverage can be vizsualised here.

## SPARQL Service¶

This service enables the connection of geodata from different sources as Linked Data. It uses the open query language SPARQL.

### URL¶

https://sparql.geo.admin.ch/sparql


### Available datasets¶

https://atom.geo.admin.ch/inspire/service.xml - Service Feed