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.
https://tel.search.ch/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) |
Results 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: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