Skip to content

PB-2168: add links section documentation for address search results #109

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

Open
ltclm wants to merge 1 commit into
base: master
Choose a base branch
from
Open

PB-2168: add links section documentation for address search results #109

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
54 changes: 54 additions & 0 deletions access-data/search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,18 @@ Here is a description of the response's data.
| `x` and `y` | These attributes represent the coordinates of an entry. If an object's entry is a line or a polygon, those coordinates will always be on the underlying geometry. |
| `label` | The HTML label for an entry. |

**Links (for address results):**
| **Field** | **Description** |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `links` | An array of related resources for address search results. Each link contains: |
| `rel` | The relationship type, typically "related". |
| `title` | The layer ID of the related resource (e.g., "ch.swisstopo.amtliches-gebaeudeadressverzeichnis", "ch.bfs.gebaeude_wohnungs_register"). |
| `href` | The URL path to access the related feature resource. The `<featureid>` placeholder contains the actual feature ID. |

::: tip
For address search results, it is recommended to use the `links` provided in the response to get additional feature information instead of constructing feature URLs manually. The links point to related resources such as the official building address directory and building/dwelling register.
:::

Here is a list of possible origins sorted in ascending ranking order:

- **zipcode** (ch.swisstopo-vd.ortschaftenverzeichnis_plz)
Expand Down Expand Up @@ -139,6 +151,48 @@ example='{
}'
/>

Search for an address (note the `links` section containing related resources):

<ExampleCodeBlock
request="$ curl https://api3.geo.admin.ch/rest/services/ech/SearchServer?searchText=Landstrasse%208595%20Altnau&type=locations"
example='{
"results": [
{
"attrs": {
"detail": "landstrasse # 8595 altnau 4641 altnau ch tg",
"featureId": "191979601_0",
"geom_quadindex": "012323201233230311110",
"geom_st_box2d": "BOX(2737666 1275668,2737666 1275668)",
"label": "Landstrasse # <b>8595 Altnau</b>",
"lat": 47.61722946166992,
"lon": 9.269905090332031,
"num": 0,
"objectclass": "",
"origin": "address",
"rank": 7,
"x": 1275668,
"y": 2737666,
"zoomlevel": 10
},
"id": 1926520,
"weight": 100,
"links": [
{
"rel": "related",
"title": "ch.swisstopo.amtliches-gebaeudeadressverzeichnis",
"href": "/rest/services/ech/MapServer/ch.swisstopo.amtliches-gebaeudeadressverzeichnis/<featureid>"
},
{
"rel": "related",
"title": "ch.bfs.gebaeude_wohnungs_register",
"href": "/rest/services/ech/MapServer/ch.bfs.gebaeude_wohnungs_register/<featureid>"
}
]
}
Copy link
Contributor

@asteiner-swisstopo asteiner-swisstopo Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I run the query https://api3.geo.admin.ch/rest/services/ech/SearchServer?searchText=Landstrasse%208595%20Altnau&type=locations the answer does not contain a "links" section. Are you sure this is the right query?

Copy link
Contributor Author

@ltclm ltclm Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for now you have to use sys-api3.dev.bgdi.ch. This doc be deployed together with the next release deploy.
https://sys-api3.dev.bgdi.ch/rest/services/ech/SearchServer?searchText=Landstrasse%208595%20Altnau&type=locations

Copy link
Contributor

@asteiner-swisstopo asteiner-swisstopo Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, all good then ✅

]
}'
/>

Search for locations of type "parcel" and "district" (the origins):

<ExampleCodeBlock
Expand Down
Loading