Requests are sent to the API as HTTP-URIs, according to the concept of REST.
If you obtain a key, you can make more queries per day and obtain structured data.
https://search.ch/tel/api/?was=john+meier&key=Your key
A normal and correct request is answered by status HTTP 200. Invalid requests or requests with an invalid API key will get the apropriate HTTP statuscode as a response.
The following parameters are possible in the request. All values must be urlencoded.
| Parameter | Optional | Description |
| was | no | General searchstring. Search for names, categories or phone numbers |
| wo | yes | Refine you search geographically. It can contain the name of a street or a city, a npa or an abbreviation of a canton. |
| q | yes | For single-field queries. The words will be searched in was and wo. |
| privat | yes | 1 = Search for private entries, 0 = Exclude private entries. Default = 1 |
| firma | yes | 1 = Search for a business, 0 = Exclude business entries. Default = 1 |
| pos | yes | Position of the first entry in the query. Used for queries with more than maxnum results. |
| maxnum | yes | Number of results in the feed. The output is limited to 200 entries. |
| key | yes | API-key. Use our online form to request your own key. |
| lang | yes | Output language. Possible values: de,fr,it,en Translatable information (e.g. categories) are translated into the specified language. |
| count_only | yes | 1 = return result count only (faster) |
Structured results (which require an API key) are shown as Atom feeds. The feed complemented with its own namespace for OpenSearch elements and tel.search.ch specific fields.
The following OpenSearch elements are directly subordinated on the element <feed>:
If no entries are found with the actual searchquery an additional query element is added with suggestions.
Example: <openSearch:Query role="correction" searchTerms="Bäckerei" totalResults="5256" />
The following elements are subordinated to an entry in the feed (/feed/entry) and represent a record:
| Field | API key mandatory | Description |
| /feed/entry/id | no | Unique identifier according to RFC 4287 |
| /feed/entry/published | no | Date of publication in timestamp syntax (RFC 3339) E.g. 2007-01-09T08:00:00Z |
| /feed/entry/updated | no | Last change of an entry in timestamp syntax (RFC 3339) E.g. 2007-01-12T14:32:11Z |
| /feed/entry/title | no | Title of the entry Name of the person or business |
| /feed/entry/content | no | Abstract of the entry in plaintext |
| /feed/entry/author/name | no | Author of the entry (according to RFC 4287) |
| /feed/entry/link/@rel='alternate' | no | Link to the detailpage of the entry on tel.search.ch |
| /feed/entry/link/@rel='edit' | no | Link to the correctionpage of the entry on tel.search.ch |
| /feed/entry/link/@type='text/x-vcard' | no | URL the VCard download |
| /feed/entry/tel:pos | yes | Position of the entry according to the whole resultset |
| /feed/entry/tel:id | yes | Unique tel.search.ch identification of the entry |
| /feed/entry/tel:type | yes | Type of the entry: Person or Organisation |
| /feed/entry/tel:org | yes | Organization name |
| /feed/entry/tel:name | yes | Lastname or the person or business |
| /feed/entry/tel:subname | yes | Additional name |
| /feed/entry/tel:firstname | yes | Firstname of the person |
| /feed/entry/tel:maidenname | yes | Maiden name of the person |
| /feed/entry/tel:occupation | yes | Occupation of the person, Additional information for business entries |
| /feed/entry/tel:category | yes | Category of the business entry (multiple elements possible) |
| /feed/entry/tel:street | yes | Street |
| /feed/entry/tel:streetno | yes | Number |
| /feed/entry/tel:pobox | yes | P.O.Box address |
| /feed/entry/tel:hamlet | yes | Hamlet |
| /feed/entry/tel:zip | yes | ZIP |
| /feed/entry/tel:city | yes | City |
| /feed/entry/tel:canton | yes | Abbreviation of canton (ZH,BE,AG,...) |
| /feed/entry/tel:nopromo | yes | * No promotions please |
| /feed/entry/tel:phone | yes | Phone number with area code |
| /feed/entry/tel:extra/@type='fax' | yes | Fax (optional) |
| /feed/entry/tel:extra/@type='email' | yes | E-mail (optional) |
| /feed/entry/tel:extra/@type='website' | yes | Website URL (optional) |
| /feed/entry/tel:extra/@type='skype' | yes | Skype name (optional) |
| /feed/entry/tel:extra/@type='icq|msn|aim|yahoo' | yes | Instant messenger (optional) |
An example for a response in Atom syntax: api-response.xml
Every request will be answered with a status code according to HTTP specification. The most frequent status codes are listed below including the specific meaning on API requests.
| Code | Description |
| 200 OK | No errors |
| 400 BAD REQUEST 401 | Invalid request e.g. missing or wrong parameters |
| 403 FORBIDDEN | Authorisation failed, wrong API key |
| 404 NOT FOUND | No API feed on this URL |
If the authorisation of the API key failed an additional description of the problem is added in the body in Atom feed syntax with dedicated fields:
| Code | Description |
| /feed/tel:errorCode | Errorcode |
| /feed/tel:errorReason | Cause of the error |
| /feed/tel:errorMessage | Description of the error |
An example of an error message in Atom syntax: api-error.xml